@s2script/sdk 0.4.0 → 0.5.0

package/dist/cli.js

@@ -4,12 +4,12 @@
 import * as esbuild from "esbuild";
 import AdmZip from "adm-zip";
 import { readFileSync as readFileSync4, mkdirSync } from "node:fs";
-import { resolve as resolve4, join as join4 } from "node:path";
+import { resolve as resolve5, join as join6 } from "node:path";
 
 // src/typecheck/typecheck.ts
 import ts from "typescript";
-import { existsSync as existsSync2, readdirSync, readFileSync, writeFileSync, rmSync, mkdtempSync } from "node:fs";
-import { join as join2, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync3, readdirSync, readFileSync, writeFileSync, rmSync, mkdtempSync } from "node:fs";
+import { join as join3, resolve as resolve2 } from "node:path";
 import { tmpdir } from "node:os";
 
 // src/packages-resolve.ts
@@ -55,11 +55,47 @@ function resolvePackagesDir(opts) {
   );
 }
 
+// src/tsconfig-shared.ts
+var sharedCompilerOptionsJson = {
+  strict: true,
+  noEmit: true,
+  moduleResolution: "bundler",
+  module: "ESNext",
+  target: "ES2020",
+  lib: ["ES2020"],
+  types: [],
+  skipLibCheck: true,
+  allowImportingTsExtensions: true
+};
+function sharedProgramOptions(tsMod) {
+  return {
+    strict: sharedCompilerOptionsJson.strict,
+    noEmit: sharedCompilerOptionsJson.noEmit,
+    allowImportingTsExtensions: sharedCompilerOptionsJson.allowImportingTsExtensions,
+    moduleResolution: tsMod.ModuleResolutionKind.Bundler,
+    module: tsMod.ModuleKind.ESNext,
+    target: tsMod.ScriptTarget.ES2020,
+    lib: sharedCompilerOptionsJson.lib.map((l) => `lib.${l.toLowerCase()}.d.ts`),
+    types: [...sharedCompilerOptionsJson.types],
+    skipLibCheck: sharedCompilerOptionsJson.skipLibCheck
+  };
+}
+
+// src/contracts.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+function localContractPath(pluginDir, dep) {
+  const segs = dep.split("/");
+  if (segs.some((s) => s === "" || s === "." || s === "..")) return null;
+  const p = join2(pluginDir, ".s2script", "types", ...segs, "index.d.ts");
+  return existsSync2(p) ? p : null;
+}
+
 // src/typecheck/typecheck.ts
 function localDeclarationFiles(pluginDir) {
-  const srcDir = join2(pluginDir, "src");
-  if (!existsSync2(srcDir)) return [];
-  return readdirSync(srcDir).filter((f) => f.endsWith(".d.ts")).map((f) => join2(srcDir, f));
+  const srcDir = join3(pluginDir, "src");
+  if (!existsSync3(srcDir)) return [];
+  return readdirSync(srcDir).filter((f) => f.endsWith(".d.ts")).map((f) => join3(srcDir, f));
 }
 function declaredModules(dtsFiles) {
   const out = /* @__PURE__ */ new Set();
@@ -72,31 +108,33 @@ function declaredModules(dtsFiles) {
 function typecheckPlugin(pluginDir, opts) {
   const absDir = resolve2(pluginDir);
   const packagesDir = opts?.packagesDir ? resolve2(opts.packagesDir) : resolvePackagesDir({ pluginDir: absDir });
-  const pkg = JSON.parse(readFileSync(join2(absDir, "package.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync(join3(absDir, "package.json"), "utf8"));
   const s2 = pkg.s2script ?? {};
   const entryRel = s2.main ?? pkg.main;
-  if (!entryRel) throw new Error(`typecheckPlugin: no entry point in ${join2(absDir, "package.json")}`);
+  if (!entryRel) throw new Error(`typecheckPlugin: no entry point in ${join3(absDir, "package.json")}`);
   const entry = resolve2(absDir, entryRel);
   const isAlwaysResolved = (d) => d.startsWith("@s2script/sdk/") || d === "@s2script/cs2" || d.startsWith("@s2script/cs2/");
   const localDts = localDeclarationFiles(absDir);
   const locallyDeclared = declaredModules(localDts);
+  const allDeclaredDeps = [
+    ...Object.keys(s2.pluginDependencies ?? {}),
+    ...Object.keys(s2.optionalPluginDependencies ?? {})
+  ];
+  const contractPaths = {};
+  for (const d of allDeclaredDeps) {
+    const p = localContractPath(absDir, d);
+    if (p !== null) contractPaths[d] = [p];
+  }
   const deps = [
     ...Object.keys(s2.pluginDependencies ?? {}),
     ...Object.keys(s2.optionalPluginDependencies ?? {})
     // Never stub a module the plugin declares itself — a shorthand `declare module "X";` and a
     // full `declare module "X" { … }` for the same X collide.
-  ].filter((d) => !isAlwaysResolved(d) && !locallyDeclared.has(d));
+  ].filter((d) => !isAlwaysResolved(d) && !locallyDeclared.has(d) && contractPaths[d] === void 0);
   const options = {
-    strict: true,
-    noEmit: true,
     // Accept explicit `.ts` import extensions (node type-stripping requires them for source-to-source
     // imports; esbuild strips them at bundle time). Backward-compatible — extensionless imports still resolve.
-    allowImportingTsExtensions: true,
-    moduleResolution: ts.ModuleResolutionKind.Bundler,
-    module: ts.ModuleKind.ESNext,
-    target: ts.ScriptTarget.ES2020,
-    lib: ["lib.es2020.d.ts"],
-    types: [],
+    ...sharedProgramOptions(ts),
     baseUrl: packagesDir,
     paths: {
       // Builtins are `@s2script/sdk/<cap>` → packages/sdk/<cap>.d.ts. The `@s2script/*` fallback
@@ -104,15 +142,15 @@ function typecheckPlugin(pluginDir, opts) {
       // dirs are deleted). tsc picks the longest matching prefix, so `@s2script/sdk/*` wins for
       // sdk imports.
       "@s2script/sdk/*": ["sdk/*.d.ts"],
-      "@s2script/*": ["*/index.d.ts"]
-    },
-    skipLibCheck: true
+      "@s2script/*": ["*/index.d.ts"],
+      ...contractPaths
+    }
   };
-  const rootNames = [entry, join2(packagesDir, "sdk", "globals.d.ts"), ...localDts];
-  const tmp = mkdtempSync(join2(tmpdir(), "s2tc-"));
+  const rootNames = [entry, join3(packagesDir, "sdk", "globals.d.ts"), ...localDts];
+  const tmp = mkdtempSync(join3(tmpdir(), "s2tc-"));
   try {
     if (deps.length) {
-      const stub = join2(tmp, "ambient.d.ts");
+      const stub = join3(tmp, "ambient.d.ts");
       writeFileSync(stub, deps.map((d) => `declare module ${JSON.stringify(d)};`).join("\n") + "\n");
       rootNames.push(stub);
     }
@@ -132,7 +170,7 @@ function typecheckPlugin(pluginDir, opts) {
       }
       return { file, line, col, code: d.code, message: ts.flattenDiagnosticMessageText(d.messageText, "\n") };
     });
-    return { ok: out.length === 0, diagnostics: out };
+    return { ok: out.length === 0, diagnostics: out, program };
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }
@@ -239,8 +277,8 @@ function validateDecl(full, decl, typeStr, errs) {
 }
 
 // src/publish-gate.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, statSync } from "node:fs";
-import { join as join3, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync2, statSync } from "node:fs";
+import { join as join4, resolve as resolve3 } from "node:path";
 function hasPublishes(publishes) {
   if (publishes == null) return false;
   if (typeof publishes === "string") return publishes.trim().length > 0;
@@ -266,7 +304,7 @@ function assertPublishesTypes(pkg, pluginDir) {
     };
   }
   const typesPath = resolve3(pluginDir, typesRel);
-  if (!existsSync3(typesPath)) {
+  if (!existsSync4(typesPath)) {
     return { ok: false, error: `types file not found: ${typesRel}` };
   }
   const st = statSync(typesPath);
@@ -341,32 +379,160 @@ function derivePublishes(authored, pkgName, pkgVersion, typesPath) {
   return out;
 }
 
+// src/api-version.ts
+var HOST_API_VERSION_MAJOR = 2;
+var STAMPED_API_VERSION = `${HOST_API_VERSION_MAJOR}.x`;
+
+// src/publish-scan.ts
+import ts2 from "typescript";
+function isPluginContext(type) {
+  const sym = type.getSymbol() ?? type.aliasSymbol;
+  return sym?.getName() === "PluginContext";
+}
+function scanPluginProgram(program, pluginDir) {
+  const checker = program.getTypeChecker();
+  const out = { publishNames: [], dynamicPublishSites: [], useNames: [] };
+  const dirPrefix = pluginDir.replace(/\\/g, "/").replace(/\/+$/, "") + "/";
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile) continue;
+    if (!sf.fileName.replace(/\\/g, "/").startsWith(dirPrefix)) continue;
+    const visit = (node) => {
+      if (ts2.isCallExpression(node) && ts2.isPropertyAccessExpression(node.expression)) {
+        const method = node.expression.name.text;
+        if (method === "publish" || method === "use" || method === "tryUse") {
+          const recv = checker.getTypeAtLocation(node.expression.expression);
+          if (isPluginContext(recv)) {
+            const arg0 = node.arguments[0];
+            if (method === "publish") {
+              if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
+                out.publishNames.push(arg0.text);
+              } else {
+                const { line } = sf.getLineAndCharacterOfPosition(node.getStart());
+                out.dynamicPublishSites.push(`${sf.fileName}:${line + 1}`);
+              }
+            } else if (arg0 !== void 0 && ts2.isStringLiteralLike(arg0)) {
+              out.useNames.push(arg0.text);
+            }
+          }
+        }
+      }
+      ts2.forEachChild(node, visit);
+    };
+    visit(sf);
+  }
+  out.publishNames = [...new Set(out.publishNames)];
+  out.useNames = [...new Set(out.useNames)];
+  return out;
+}
+
+// src/lint/lint.ts
+import { ESLint } from "eslint";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join5, resolve as resolve4 } from "node:path";
+import s2lint from "@s2script/eslint-plugin";
+var CONFIG_FILES = ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts"];
+async function lintPlugin(pluginDir, program) {
+  const absDir = resolve4(pluginDir);
+  const hasOwnConfig = CONFIG_FILES.some((f) => existsSync5(join5(absDir, f)));
+  const eslint = hasOwnConfig ? new ESLint({ cwd: absDir, errorOnUnmatchedPattern: false }) : new ESLint({
+    cwd: absDir,
+    overrideConfigFile: true,
+    overrideConfig: s2lint.configs.build([program]),
+    errorOnUnmatchedPattern: false
+  });
+  const dirPrefix = absDir.replace(/\\/g, "/").replace(/\/+$/, "") + "/";
+  const targets = hasOwnConfig ? ["**/*.ts"] : program.getSourceFiles().filter((sf) => !sf.isDeclarationFile && sf.fileName.replace(/\\/g, "/").startsWith(dirPrefix)).map((sf) => sf.fileName);
+  if (targets.length === 0) return { ok: true, output: "", errorCount: 0 };
+  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 };
+}
+
 // src/build.ts
 async function buildPlugin(dir, packagesDir) {
-  const absDir = resolve4(dir);
-  const pkgPath = join4(absDir, "package.json");
+  const absDir = resolve5(dir);
+  const pkgPath = join6(absDir, "package.json");
   const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
-  const gate = assertPublishesTypes(pkg, absDir);
-  if (!gate.ok) {
-    throw new Error(`publish gate failed: ${gate.error}`);
-  }
   const s2 = pkg.s2script ?? {};
-  const derivedPublishes = derivePublishes(s2.publishes, pkg.name, pkg.version, gate.typesPath);
+  const config = s2.config ?? void 0;
+  if (config !== void 0) {
+    const cfgErrs = validateConfigBlock(config);
+    if (cfgErrs.length) throw new Error(`invalid s2script.config:
+  ${cfgErrs.join("\n  ")}`);
+  }
   const tc = typecheckPlugin(absDir, packagesDir !== void 0 ? { packagesDir } : void 0);
   if (!tc.ok) {
     throw new Error(`typecheck failed (${tc.diagnostics.length} error(s)):
 ${formatDiagnostics(tc.diagnostics)}`);
   }
-  const { name, version } = pkg;
-  const apiVersion = s2.apiVersion ?? "";
+  const scan = scanPluginProgram(tc.program, absDir);
+  const lint = await lintPlugin(absDir, tc.program);
+  if (!lint.ok) {
+    throw new Error(`lint failed (${lint.errorCount} error(s)):
+${lint.output}`);
+  }
+  if (lint.output.trim().length > 0) console.warn(lint.output);
+  if (scan.dynamicPublishSites.length > 0) {
+    throw new Error(
+      `ctx.publish name must be a string literal (the manifest publishes block is derived from code):
+  ` + scan.dynamicPublishSites.join("\n  ")
+    );
+  }
+  let effectivePublishes = s2.publishes;
+  if (!hasPublishes(effectivePublishes)) {
+    if (scan.publishNames.length === 1 && scan.publishNames[0] === pkg.name) {
+      effectivePublishes = "self";
+    } else if (scan.publishNames.length > 0) {
+      throw new Error(
+        `code publishes ${JSON.stringify(scan.publishNames)} but s2script.publishes is missing \u2014 a contract named differently from the package needs an authored entry with a concrete version`
+      );
+    }
+  } else {
+    const authoredNames = Object.keys(expandPublishes(effectivePublishes, pkg.name, pkg.version)).sort();
+    const codeNames = [...scan.publishNames].sort();
+    if (JSON.stringify(authoredNames) !== JSON.stringify(codeNames)) {
+      throw new Error(
+        `publishes drift: package.json declares ${JSON.stringify(authoredNames)} but the code's ctx.publish calls are ${JSON.stringify(codeNames)} \u2014 fix whichever is wrong (the manifest is generated from code; the loader re-verifies at Active)`
+      );
+    }
+  }
+  const gate = assertPublishesTypes({ ...pkg, s2script: { ...s2, publishes: effectivePublishes } }, absDir);
+  if (!gate.ok) {
+    throw new Error(`publish gate failed: ${gate.error}`);
+  }
+  const derivedPublishes = derivePublishes(
+    effectivePublishes,
+    pkg.name,
+    pkg.version,
+    gate.typesPath
+  );
   const pluginDependencies = s2.pluginDependencies ?? {};
   const optionalPluginDependencies = s2.optionalPluginDependencies ?? {};
-  const config = s2.config ?? void 0;
-  if (config !== void 0) {
-    const cfgErrs = validateConfigBlock(config);
-    if (cfgErrs.length) throw new Error(`invalid s2script.config:
-  ${cfgErrs.join("\n  ")}`);
+  const declaredDeps = /* @__PURE__ */ new Set([
+    ...Object.keys(pluginDependencies),
+    ...Object.keys(optionalPluginDependencies)
+  ]);
+  for (const used of scan.useNames) {
+    if (!declaredDeps.has(used)) {
+      console.warn(
+        `WARN: ctx.use/tryUse(${JSON.stringify(used)}) is not declared under s2script.pluginDependencies/optionalPluginDependencies \u2014 it will throw at runtime`
+      );
+    }
+  }
+  for (const dep of declaredDeps) {
+    if (!scan.useNames.includes(dep)) {
+      console.warn(`WARN: dependency ${JSON.stringify(dep)} is declared but never ctx.use()d`);
+    }
   }
+  const { name, version } = pkg;
+  if (s2.apiVersion !== void 0) {
+    console.warn(
+      `WARN: ${pkgPath}: s2script.apiVersion is ignored \u2014 s2s build derives apiVersion from the SDK (stamping ${JSON.stringify(STAMPED_API_VERSION)}). Remove the field.`
+    );
+  }
+  const apiVersion = STAMPED_API_VERSION;
   const external = Array.from(/* @__PURE__ */ new Set([
     "@s2script/*",
     ...Object.keys(pluginDependencies),
@@ -378,7 +544,7 @@ ${formatDiagnostics(tc.diagnostics)}`);
       `buildPlugin: no entry point found in ${pkgPath} (set s2script.main or main)`
     );
   }
-  const entryPoint = join4(absDir, entryRelative);
+  const entryPoint = join6(absDir, entryRelative);
   const result = await esbuild.build({
     entryPoints: [entryPoint],
     bundle: true,
@@ -401,6 +567,15 @@ ${formatDiagnostics(tc.diagnostics)}`);
     manifest.publishes = derivedPublishes;
   }
   if (config !== void 0) manifest.config = config;
+  const compiledAgainst = {};
+  for (const dep of [
+    ...Object.keys(pluginDependencies),
+    ...Object.keys(optionalPluginDependencies)
+  ]) {
+    const contractPath = localContractPath(absDir, dep);
+    if (contractPath !== null) compiledAgainst[dep] = hashContract(contractPath);
+  }
+  if (Object.keys(compiledAgainst).length > 0) manifest.compiledAgainst = compiledAgainst;
   const zip = new AdmZip();
   zip.addFile("manifest.json", Buffer.from(JSON.stringify(manifest, null, 2)));
   zip.addFile("plugin.js", Buffer.from(pluginJs));
@@ -412,16 +587,16 @@ ${formatDiagnostics(tc.diagnostics)}`);
     }
   }
   const sanitizedId = name.replace(/[^a-zA-Z0-9._-]/g, "_");
-  const outDir = join4(absDir, "dist");
+  const outDir = join6(absDir, "dist");
   mkdirSync(outDir, { recursive: true });
-  const outPath = join4(outDir, `${sanitizedId}.s2sp`);
+  const outPath = join6(outDir, `${sanitizedId}.s2sp`);
   zip.writeZip(outPath);
   return outPath;
 }
 
 // src/schemagen/gen.ts
 import { readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join5 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/schemagen/model.ts
 var READ = {
@@ -613,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 resolve7 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+      const resolve8 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
       let entry;
       if (f.accessorKind === "str") {
-        entry = `get: function () { return this.ref.readString(${resolve7}, ${f.strLen}); }`;
+        entry = `get: function () { return this.ref.readString(${resolve8}, ${f.strLen}); }`;
       } else if (f.accessorKind === "u64" || f.accessorKind === "i64") {
-        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve7}); return v === null ? null : v.toString(); }`;
+        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve8}); 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(${resolve7}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+        entry = `get: function () { var a = this.ref.readFloats(${resolve8}, ${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]}(${resolve7}); }`;
+        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve8}); }`;
       }
       if (f.writable) {
         const wm = WRITE[f.accessorKind];
-        entry += `, set: function (v) { var o = ${resolve7}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
+        entry += `, set: function (v) { var o = ${resolve8}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
       }
       out.push(`    ${S(f.propName)}: { ${entry} },`);
     }
@@ -653,8 +828,8 @@ var LIST_PATH = "games/cs2/codegen-classes.json";
 var JS_OUT = "games/cs2/js/schema.generated.js";
 var DTS_OUT = "packages/cs2/schema.generated.d.ts";
 function runGenSchema(repoRoot, opts) {
-  const catalog = JSON.parse(readFileSync5(join5(repoRoot, CATALOG_PATH), "utf8"));
-  const list = JSON.parse(readFileSync5(join5(repoRoot, LIST_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync5(join7(repoRoot, CATALOG_PATH), "utf8"));
+  const list = JSON.parse(readFileSync5(join7(repoRoot, LIST_PATH), "utf8"));
   const model = buildModel(catalog, list);
   const dts = emitDts(model);
   const js = emitJs(model);
@@ -663,7 +838,7 @@ function runGenSchema(repoRoot, opts) {
   const drift = [];
   const files = [[JS_OUT, js], [DTS_OUT, dts]];
   for (const [rel, content] of files) {
-    const abs = join5(repoRoot, rel);
+    const abs = join7(repoRoot, rel);
     if (opts.check) {
       let cur = "";
       try {
@@ -683,7 +858,7 @@ function runGenSchema(repoRoot, opts) {
 
 // src/eventgen/gen.ts
 import { readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join8 } from "node:path";
 
 // src/eventgen/model.ts
 var TYPE_TO_GETTER = {
@@ -768,11 +943,11 @@ function emitEventDts(model) {
 var CATALOG_PATH2 = "games/cs2/gamedata/event-catalog.json";
 var DTS_OUT2 = "packages/cs2/events.generated.d.ts";
 function runGenEvents(repoRoot, opts) {
-  const catalog = JSON.parse(readFileSync6(join6(repoRoot, CATALOG_PATH2), "utf8"));
+  const catalog = JSON.parse(readFileSync6(join8(repoRoot, CATALOG_PATH2), "utf8"));
   const model = buildEventModel(catalog);
   const dts = emitEventDts(model);
   const drift = [];
-  const abs = join6(repoRoot, DTS_OUT2);
+  const abs = join8(repoRoot, DTS_OUT2);
   if (opts.check) {
     let cur = "";
     try {
@@ -788,7 +963,7 @@ function runGenEvents(repoRoot, opts) {
 
 // src/navgen/gen.ts
 import { readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 
 // src/navgen/model.ts
 var SUPPORTED_NAV_KINDS = /* @__PURE__ */ new Set([
@@ -863,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 resolve7 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
+      const resolve8 = `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, ${resolve7}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readUInt64Via(this.path, ${resolve8}); return v === null ? null : v.toString(); }`;
       } else if (kind === "i64") {
-        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve7}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve8}); 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, ${resolve7}, ${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, ${resolve8}, ${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, ${resolve7}); }`;
+        getter = `get: function () { return this.root.readHandleVia(this.path, ${resolve8}); }`;
       } else {
         const method = READ_VIA[kind];
         if (!method) continue;
-        getter = `get: function () { return this.root.${method}(this.path, ${resolve7}); }`;
+        getter = `get: function () { return this.root.${method}(this.path, ${resolve8}); }`;
       }
       out.push(`    ${S2(f.propName)}: { ${getter} },`);
     }
@@ -950,8 +1125,8 @@ var CATALOG_PATH3 = "games/cs2/gamedata/schema-catalog.json";
 var JS_OUT2 = "games/cs2/js/nav.generated.js";
 var DTS_OUT3 = "packages/cs2/nav.generated.d.ts";
 function runGenNav(repoRoot, opts) {
-  const config = JSON.parse(readFileSync7(join7(repoRoot, TARGETS_PATH), "utf8"));
-  const catalog = JSON.parse(readFileSync7(join7(repoRoot, CATALOG_PATH3), "utf8"));
+  const config = JSON.parse(readFileSync7(join9(repoRoot, TARGETS_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync7(join9(repoRoot, CATALOG_PATH3), "utf8"));
   const model = buildNavModel(config, catalog);
   const js = emitNavJs(model);
   const dts = emitNavDts(model);
@@ -959,7 +1134,7 @@ function runGenNav(repoRoot, opts) {
   const drift = [];
   const files = [[JS_OUT2, js], [DTS_OUT3, dts]];
   for (const [rel, content] of files) {
-    const abs = join7(repoRoot, rel);
+    const abs = join9(repoRoot, rel);
     if (opts.check) {
       let cur = "";
       try {
@@ -978,11 +1153,12 @@ function runGenNav(repoRoot, opts) {
 import {
   mkdirSync as mkdirSync2,
   writeFileSync as writeFileSync5,
-  existsSync as existsSync4,
+  existsSync as existsSync6,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync8
+  readFileSync as readFileSync8,
+  symlinkSync
 } from "node:fs";
-import { dirname as dirname2, join as join8, resolve as resolve5, basename } from "node:path";
+import { dirname as dirname2, join as join10, resolve as resolve6, basename } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { spawnSync } from "node:child_process";
@@ -990,13 +1166,13 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 function readCliVersion() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join8(here, "..", "package.json"),
+    join10(here, "..", "package.json"),
     // dist/cli.js → packages/sdk/package.json
-    join8(here, "..", "..", "package.json")
+    join10(here, "..", "..", "package.json")
     // src/create → packages/sdk/package.json
   ];
   for (const p of candidates) {
-    if (!existsSync4(p)) continue;
+    if (!existsSync6(p)) continue;
     try {
       const pkg = JSON.parse(readFileSync8(p, "utf8"));
       if (pkg.name === "@s2script/sdk" && pkg.version) return pkg.version;
@@ -1008,18 +1184,18 @@ function readCliVersion() {
 function findLocalPackagesDir() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    join8(here, "..", ".."),
+    join10(here, "..", ".."),
     // dist/cli.js → packages
-    join8(here, "..", "..", "..")
+    join10(here, "..", "..", "..")
     // src/create → packages
   ];
   for (const c of candidates) {
-    if (isPackagesDir(c)) return resolve5(c);
+    if (isPackagesDir(c)) return resolve6(c);
   }
   return void 0;
 }
 function defaultNameFromPath(dir) {
-  const base = basename(resolve5(dir));
+  const base = basename(resolve6(dir));
   const slug = base.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "plugin";
   return `@plugin/${slug}`;
 }
@@ -1056,9 +1232,9 @@ function assertInstall(v) {
 }
 function createPackageNames(game) {
   if (game === "cs2") {
-    return ["sdk", "cs2"];
+    return ["sdk", "cs2", "eslint-plugin"];
   }
-  return ["sdk"];
+  return ["sdk", "eslint-plugin"];
 }
 function resolvePublishedVersion(pkg) {
   const r = spawnSync("npm", ["view", pkg, "version"], { encoding: "utf8", timeout: 5e3 });
@@ -1068,68 +1244,62 @@ function versionSpecFrom(status, stdout) {
   const v = (stdout ?? "").trim();
   return status === 0 && /^\d+\.\d+\.\d+/.test(v) ? `^${v}` : "latest";
 }
-function registryDevDeps(game, sdkVersion, resolve7 = resolvePublishedVersion) {
+function registryDevDeps(game, sdkVersion, resolve8 = resolvePublishedVersion) {
   const deps = {};
   for (const n of createPackageNames(game)) {
-    deps[`@s2script/${n}`] = n === "sdk" ? `^${sdkVersion}` : resolve7(`@s2script/${n}`);
+    deps[`@s2script/${n}`] = n === "sdk" ? `^${sdkVersion}` : resolve8(`@s2script/${n}`);
   }
   return deps;
 }
 function fileDevDeps(packagesDir, game) {
   const deps = {};
   for (const n of createPackageNames(game)) {
-    const abs = join8(packagesDir, n);
-    if (!existsSync4(join8(abs, "package.json"))) return void 0;
+    const abs = join10(packagesDir, n);
+    if (!existsSync6(join10(abs, "package.json"))) return void 0;
     deps[`@s2script/${n}`] = `file:${abs}`;
   }
   return deps;
 }
 function pluginSource(game) {
   if (game === "cs2") {
-    return `import { Commands } from "@s2script/sdk/commands";
+    return `import { plugin } from "@s2script/sdk/plugin";
 import { Chat } from "@s2script/sdk/chat";
 
-export function onLoad(): void {
-  Commands.register("hello", (ctx) => {
-    ctx.reply("hello from s2script");
-    if (ctx.callerSlot >= 0) {
-      Chat.toSlot(ctx.callerSlot, "hello from s2script");
+export default plugin((ctx) => {
+  ctx.commands.register("hello", (cmd) => {
+    cmd.reply("hello from s2script");
+    if (cmd.callerSlot >= 0) {
+      Chat.toSlot(cmd.callerSlot, "hello from s2script");
     }
   });
-}
-
-export function onUnload(): void {}
+});
 `;
   }
-  return `import { OnGameFrame } from "@s2script/sdk/frame";
+  return `import { plugin } from "@s2script/sdk/plugin";
 import { delay } from "@s2script/sdk/timers";
 
-export function onLoad(): void {
+export default plugin((ctx) => {
   let n = 0;
-  OnGameFrame.subscribe(() => {
+  ctx.server.onGameFrame(() => {
     n += 1;
   });
-  void delay(1000).then(() => {
-    console.log("s2script plugin alive; frames so far:", n);
-  });
+  void delay(1000).then(() => console.log("s2script plugin alive; frames so far:", n));
+});
+`;
 }
+var ESLINT_RANGE = "^10.7.0";
+function eslintConfig() {
+  return `import s2script from "@s2script/eslint-plugin";
 
-export function onUnload(): void {}
+// The SAME pinned rules \`s2s build\` enforces \u2014 the editor's ESLint extension picks this up,
+// so a violation is a red squiggle before you ever build (green editor => green build).
+export default s2script.configs.recommended({ tsconfigRootDir: import.meta.dirname });
 `;
 }
 function tsconfigJson() {
   return JSON.stringify(
     {
-      compilerOptions: {
-        strict: true,
-        noEmit: true,
-        moduleResolution: "bundler",
-        module: "ESNext",
-        target: "ES2020",
-        lib: ["ES2020"],
-        types: [],
-        skipLibCheck: true
-      },
+      compilerOptions: sharedCompilerOptionsJson,
       include: ["src", "node_modules/@s2script/sdk/globals.d.ts"]
     },
     null,
@@ -1138,7 +1308,10 @@ function tsconfigJson() {
 }
 function packageJsonContent(name, game, version, localPackagesDir) {
   const fileDeps = localPackagesDir ? fileDevDeps(localPackagesDir, game) : void 0;
-  const devDependencies = fileDeps ?? registryDevDeps(game, version);
+  const devDependencies = {
+    ...fileDeps ?? registryDevDeps(game, version),
+    eslint: ESLINT_RANGE
+  };
   return JSON.stringify(
     {
       name,
@@ -1148,10 +1321,7 @@ function packageJsonContent(name, game, version, localPackagesDir) {
       scripts: {
         build: "s2s build ."
       },
-      devDependencies,
-      s2script: {
-        apiVersion: "1.x"
-      }
+      devDependencies
     },
     null,
     2
@@ -1164,6 +1334,12 @@ dist/
 .DS_Store
 `;
 }
+function linkLocalPackagesForNoInstall(targetPath, localPackagesDir) {
+  const nm = join10(targetPath, "node_modules");
+  mkdirSync2(nm, { recursive: true });
+  const dest = join10(nm, "@s2script");
+  if (!existsSync6(dest)) symlinkSync(localPackagesDir, dest);
+}
 function runInstall(dir, pm) {
   if (pm === "none") return;
   const r = spawnSync(pm, ["install"], {
@@ -1175,7 +1351,7 @@ function runInstall(dir, pm) {
   if (r.status !== 0) throw new Error(`${pm} install failed (exit ${r.status})`);
 }
 async function createPlugin(opts = {}) {
-  const targetPath = resolve5(opts.path ?? ".");
+  const targetPath = resolve6(opts.path ?? ".");
   const interactive = Boolean(input.isTTY && output.isTTY && !opts.yes);
   let game = assertGame(opts.game);
   let name = opts.name;
@@ -1184,7 +1360,7 @@ async function createPlugin(opts = {}) {
   if (template !== "minimal") {
     throw new Error(`unknown template ${JSON.stringify(template)} (v1 supports: minimal)`);
   }
-  if (existsSync4(targetPath)) {
+  if (existsSync6(targetPath)) {
     const kids = readdirSync2(targetPath);
     const meaningful = kids.filter((k) => k !== ".git");
     if (meaningful.length) {
@@ -1231,18 +1407,21 @@ async function createPlugin(opts = {}) {
   install = install ?? (opts.noInstall ? "none" : "npm");
   const version = readCliVersion();
   const localPackagesDir = findLocalPackagesDir();
-  mkdirSync2(join8(targetPath, "src"), { recursive: true });
+  mkdirSync2(join10(targetPath, "src"), { recursive: true });
   writeFileSync5(
-    join8(targetPath, "package.json"),
+    join10(targetPath, "package.json"),
     packageJsonContent(name, game, version, localPackagesDir)
   );
-  writeFileSync5(join8(targetPath, "tsconfig.json"), tsconfigJson());
-  writeFileSync5(join8(targetPath, "src", "plugin.ts"), pluginSource(game));
-  writeFileSync5(join8(targetPath, ".gitignore"), gitignore());
+  writeFileSync5(join10(targetPath, "tsconfig.json"), tsconfigJson());
+  writeFileSync5(join10(targetPath, "eslint.config.mjs"), eslintConfig());
+  writeFileSync5(join10(targetPath, "src", "plugin.ts"), pluginSource(game));
+  writeFileSync5(join10(targetPath, ".gitignore"), gitignore());
   let installed = false;
   if (install !== "none") {
     runInstall(targetPath, install);
     installed = true;
+  } else if (localPackagesDir) {
+    linkLocalPackagesForNoInstall(targetPath, localPackagesDir);
   }
   return {
     dir: targetPath,
@@ -1257,7 +1436,7 @@ async function createPlugin(opts = {}) {
 // src/config/gen.ts
 import AdmZip2 from "adm-zip";
 import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync3 } from "node:fs";
-import { join as join9 } from "node:path";
+import { join as join11 } from "node:path";
 
 // src/config/config-path.ts
 function configFileName(id) {
@@ -1304,7 +1483,7 @@ function genConfigFromManifest(manifest, outDir) {
   const id = typeof manifest.id === "string" ? manifest.id : "";
   if (!id) throw new Error("config gen: manifest declares config but has no id");
   mkdirSync3(outDir, { recursive: true });
-  const path = join9(outDir, configFileName(id));
+  const path = join11(outDir, configFileName(id));
   writeFileSync6(path, generateDefaultJsonc(config));
   return path;
 }
@@ -1328,11 +1507,11 @@ function runConfigGen(s2sps, outDir) {
 
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname3, join as join10, resolve as resolve6 } from "node:path";
+import { dirname as dirname3, join as join12, resolve as resolve7 } from "node:path";
 var argv = process.argv.slice(2);
 var command = argv[0];
 function repoRootFromCli() {
-  return join10(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join12(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 function parseFlag(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`));
@@ -1444,7 +1623,7 @@ if (command === "gen-schema") {
   try {
     const packagesDir = resolvePackagesDir({
       explicit: packagesDirFlag,
-      pluginDir: resolve6(dir),
+      pluginDir: resolve7(dir),
       fromCliUrl: import.meta.url
     });
     console.log(await buildPlugin(dir, packagesDir));