@s2script/sdk 0.3.0 → 0.4.0

package/config.d.ts

@@ -1,5 +1,7 @@
 /** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
-export type Config = Record<string, string | number | boolean>;
+/** A materialized config value: a scalar, or a nested section object of further values. */
+export type ConfigValue = string | number | boolean | { [k: string]: ConfigValue };
+export type Config = Record<string, ConfigValue>;
 export declare const config: {
   getString(key: string): string;
   getInt(key: string): number;

package/dist/cli.js

@@ -89,6 +89,9 @@ function typecheckPlugin(pluginDir, opts) {
   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,
@@ -139,25 +142,100 @@ 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
@@ -1176,13 +1254,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 join9 } 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 = join9(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 join10, resolve as resolve6 } from "node:path";
 var argv = process.argv.slice(2);
 var command = argv[0];
 function repoRootFromCli() {
-  return join9(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join10(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 function parseFlag(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`));
@@ -1194,6 +1344,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 +1421,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("-"));
@@ -1274,7 +1454,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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",
   "bin": {