@s2script/sdk 0.3.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,28 +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,
-    moduleResolution: ts.ModuleResolutionKind.Bundler,
-    module: ts.ModuleKind.ESNext,
-    target: ts.ScriptTarget.ES2020,
-    lib: ["lib.es2020.d.ts"],
-    types: [],
+    // 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.
+    ...sharedProgramOptions(ts),
     baseUrl: packagesDir,
     paths: {
       // Builtins are `@s2script/sdk/<cap>` → packages/sdk/<cap>.d.ts. The `@s2script/*` fallback
@@ -101,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);
     }
@@ -129,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 });
   }
@@ -139,30 +180,105 @@ function formatDiagnostics(diags) {
 }
 
 // src/config-validate.ts
+function isDeclType(t) {
+  return t === "string" || t === "int" || t === "float" || t === "bool";
+}
+function matchesType(v, t) {
+  switch (t) {
+    case "string":
+      return typeof v === "string";
+    case "int":
+      return typeof v === "number" && Number.isInteger(v);
+    case "float":
+      return typeof v === "number";
+    case "bool":
+      return typeof v === "boolean";
+  }
+}
 function validateConfigBlock(config) {
   const errs = [];
   if (config == null) return errs;
-  if (typeof config !== "object" || Array.isArray(config)) return ["s2script.config must be an object"];
-  for (const [key, raw] of Object.entries(config)) {
-    if (typeof raw !== "object" || raw === null) {
-      errs.push(`config '${key}': must be { type, default }`);
+  validateEntries(config, "", errs);
+  return errs;
+}
+function validateEntries(node, prefix, errs) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    errs.push(`${prefix ? `config '${prefix}'` : "s2script.config"} must be an object`);
+    return;
+  }
+  for (const [key, raw] of Object.entries(node)) {
+    const full = prefix ? `${prefix}.${key}` : key;
+    if (key.includes(".")) {
+      errs.push(`config '${full}': key must not contain '.' (dotted names are reserved for section access)`);
       continue;
     }
-    const decl = raw;
-    const t = decl.type, d = decl.default;
-    if (t !== "string" && t !== "int" && t !== "float" && t !== "bool") {
-      errs.push(`config '${key}': unknown type ${JSON.stringify(t)} (want string|int|float|bool)`);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      errs.push(`config '${full}': must be a declaration { type, default } or a section object`);
       continue;
     }
-    const ok = t === "string" && typeof d === "string" || t === "int" && typeof d === "number" && Number.isInteger(d) || t === "float" && typeof d === "number" || t === "bool" && typeof d === "boolean";
-    if (!ok) errs.push(`config '${key}': default ${JSON.stringify(d)} does not match type '${t}'`);
+    const obj = raw;
+    if (typeof obj.type === "string") {
+      validateDecl(full, obj, obj.type, errs);
+    } else {
+      validateEntries(obj, full, errs);
+    }
   }
-  return errs;
+}
+function validateDecl(full, decl, typeStr, errs) {
+  if (!isDeclType(typeStr)) {
+    errs.push(`config '${full}': unknown type ${JSON.stringify(typeStr)} (want string|int|float|bool)`);
+    return;
+  }
+  const t = typeStr;
+  if (!("default" in decl)) {
+    errs.push(`config '${full}': missing 'default'`);
+  } else if (!matchesType(decl.default, t)) {
+    errs.push(`config '${full}': default ${JSON.stringify(decl.default)} does not match type '${t}'`);
+  }
+  const hasMin = decl.min !== void 0;
+  const hasMax = decl.max !== void 0;
+  const hasEnum = decl.enum !== void 0;
+  if (hasEnum && (hasMin || hasMax)) {
+    errs.push(`config '${full}': 'enum' is mutually exclusive with 'min'/'max'`);
+  }
+  if (hasMin || hasMax) {
+    if (t !== "int" && t !== "float") {
+      errs.push(`config '${full}': 'min'/'max' apply to int|float only (type '${t}')`);
+    }
+    if (hasMin && typeof decl.min !== "number") errs.push(`config '${full}': 'min' must be a number`);
+    if (hasMax && typeof decl.max !== "number") errs.push(`config '${full}': 'max' must be a number`);
+    if (typeof decl.min === "number" && typeof decl.max === "number" && decl.min > decl.max) {
+      errs.push(`config '${full}': 'min' (${decl.min}) exceeds 'max' (${decl.max})`);
+    }
+    if (typeof decl.default === "number") {
+      if (typeof decl.min === "number" && decl.default < decl.min) errs.push(`config '${full}': default ${decl.default} is below min ${decl.min}`);
+      if (typeof decl.max === "number" && decl.default > decl.max) errs.push(`config '${full}': default ${decl.default} is above max ${decl.max}`);
+    }
+  }
+  if (hasEnum) {
+    if (t !== "string" && t !== "int") {
+      errs.push(`config '${full}': 'enum' applies to string|int only (type '${t}')`);
+    }
+    if (!Array.isArray(decl.enum) || decl.enum.length === 0) {
+      errs.push(`config '${full}': 'enum' must be a non-empty array`);
+    } else {
+      for (const e of decl.enum) {
+        if (!matchesType(e, t)) errs.push(`config '${full}': enum value ${JSON.stringify(e)} does not match type '${t}'`);
+      }
+      if ("default" in decl && matchesType(decl.default, t) && !decl.enum.some((e) => e === decl.default)) {
+        errs.push(`config '${full}': default ${JSON.stringify(decl.default)} is not one of enum`);
+      }
+    }
+  }
+  if (decl.sensitive !== void 0 && typeof decl.sensitive !== "boolean") errs.push(`config '${full}': 'sensitive' must be a boolean`);
+  if (decl.group !== void 0 && typeof decl.group !== "string") errs.push(`config '${full}': 'group' must be a string`);
+  if (decl.label !== void 0 && typeof decl.label !== "string") errs.push(`config '${full}': 'label' must be a string`);
+  if (decl.description !== void 0 && typeof decl.description !== "string") errs.push(`config '${full}': 'description' must be a string`);
 }
 
 // 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;
@@ -188,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);
@@ -263,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),
@@ -300,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,
@@ -323,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));
@@ -334,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 = {
@@ -535,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} },`);
     }
@@ -575,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);
@@ -585,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 {
@@ -605,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 = {
@@ -690,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 {
@@ -710,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([
@@ -785,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} },`);
     }
@@ -872,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);
@@ -881,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 {
@@ -900,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";
@@ -912,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;
@@ -930,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}`;
 }
@@ -978,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 });
@@ -990,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,
@@ -1060,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,
@@ -1070,10 +1321,7 @@ function packageJsonContent(name, game, version, localPackagesDir) {
       scripts: {
         build: "s2s build ."
       },
-      devDependencies,
-      s2script: {
-        apiVersion: "1.x"
-      }
+      devDependencies
     },
     null,
     2
@@ -1086,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"], {
@@ -1097,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;
@@ -1106,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) {
@@ -1153,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,
@@ -1176,13 +1433,85 @@ 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 join11 } from "node:path";
+
+// src/config/config-path.ts
+function configFileName(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_") + ".json";
+}
+
+// src/config/gen.ts
+function isDecl(v) {
+  return typeof v.type === "string";
+}
+function generateDefaultJsonc(config) {
+  return "{\n" + genEntries(config, 1) + "}\n";
+}
+function genEntries(entries, indent) {
+  const pad = "  ".repeat(indent);
+  const keys = Object.keys(entries).filter((k) => !k.includes(".")).sort();
+  let out = "";
+  keys.forEach((key, i) => {
+    const comma = i + 1 < keys.length ? "," : "";
+    const raw = entries[key];
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return;
+    const obj = raw;
+    if (isDecl(obj)) {
+      const desc = typeof obj.description === "string" ? obj.description : "";
+      out += `${pad}// ${String(obj.type)}${desc ? ` \u2014 ${desc}` : ""}
+`;
+      out += `${pad}${JSON.stringify(key)}: ${JSON.stringify(obj.default)}${comma}
+`;
+    } else {
+      out += `${pad}${JSON.stringify(key)}: {
+`;
+      out += genEntries(obj, indent + 1);
+      out += `${pad}}${comma}
+`;
+    }
+  });
+  return out;
+}
+function genConfigFromManifest(manifest, outDir) {
+  const config = manifest.config;
+  if (config == null || typeof config !== "object" || Array.isArray(config) || Object.keys(config).length === 0) {
+    return null;
+  }
+  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 = join11(outDir, configFileName(id));
+  writeFileSync6(path, generateDefaultJsonc(config));
+  return path;
+}
+function genConfigForS2sp(s2spPath, outDir) {
+  const zip = new AdmZip2(s2spPath);
+  const entry = zip.getEntry("manifest.json");
+  if (!entry) throw new Error(`config gen: ${s2spPath} has no manifest.json`);
+  const manifest = JSON.parse(entry.getData().toString("utf8"));
+  return genConfigFromManifest(manifest, outDir);
+}
+function runConfigGen(s2sps, outDir) {
+  const written = [];
+  const skipped = [];
+  for (const p of s2sps) {
+    const r = genConfigForS2sp(p, outDir);
+    if (r) written.push(r);
+    else skipped.push(p);
+  }
+  return { written, skipped };
+}
+
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname3, join as join9, 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 join9(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join12(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 function parseFlag(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`));
@@ -1194,6 +1523,20 @@ function parseFlag(args, name) {
 function hasFlag(args, name) {
   return args.includes(name);
 }
+function positionals(args, flagsWithValue) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const name = a.split("=")[0];
+      if (flagsWithValue.includes(name) && !a.includes("=")) i++;
+      continue;
+    }
+    if (a.startsWith("-")) continue;
+    out.push(a);
+  }
+  return out;
+}
 if (command === "gen-schema") {
   const repoRoot = repoRootFromCli();
   const check = argv[1] === "--check";
@@ -1257,6 +1600,22 @@ if (command === "gen-schema") {
     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();
+  const s2sps = positionals(args, ["--out"]);
+  if (s2sps.length === 0) {
+    console.error("Usage: s2s config gen <plugin.s2sp...> --out <dir>");
+    process.exit(1);
+  }
+  try {
+    const { written, skipped } = runConfigGen(s2sps, outDir);
+    for (const w of written) console.log(`config gen: wrote ${w}`);
+    for (const s of skipped) console.log(`config gen: ${s} declares no config \u2014 skipped`);
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
 } else if (command === "build" && argv[1]) {
   const args = argv.slice(1);
   const dir = args.find((a) => !a.startsWith("-"));
@@ -1264,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));
@@ -1274,7 +1633,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 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 config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]"
   );
   process.exit(1);
 }