spawnpack 0.1.9 → 0.1.11

package/dist/spawnpack.js

@@ -1539,7 +1539,9 @@ import { join } from "node:path";
 var VERSIONS = {
   minEngineVersion: [1, 26, 0],
   manifestFormat: 2,
-  esbuildFilter: "0.3.0"
+  rolldown: "^1.0.0-beta.56",
+  esToolkit: "^1.43.0",
+  jsoncParser: "^3.3.1"
 };
 var DEFAULT_MINECRAFT_DEPENDENCY_VERSIONS = {
   server: "2.6.0",
@@ -1744,7 +1746,7 @@ function generatePackageJson(config, versions) {
     if (!config.useRgl) {
       scripts.build = "tsc --project tsconfig.json";
     }
-    scripts.typecheck = "tsc --project tsconfig.json --noEmit";
+    scripts.typecheck = config.useRgl ? "tsc --project data/scripts/tsconfig.json --noEmit" : "tsc --project tsconfig.json --noEmit";
     scripts.format = "dprint fmt";
   }
   if (config.scripting === "javascript") {
@@ -1754,6 +1756,7 @@ function generatePackageJson(config, versions) {
     name: `${config.identifier}-${config.projectId}`,
     version: PACK_VERSION2,
     private: true,
+    ...config.useRgl ? { workspaces: ["./filters/*"] } : {},
     type: "module",
     scripts,
     dependencies: getSelectedScriptDependencies(config, versions)
@@ -1815,7 +1818,7 @@ function generateDprintConfig() {
 }
 function generateRglConfig(config) {
   return {
-    $schema: "https://raw.githubusercontent.com/ink0rr/rgl-schemas/main/config/v1.0.json",
+    $schema: "https://raw.githubusercontent.com/ink0rr/rgl-schemas/main/config/v1.1.json",
     author: config.author,
     name: config.projectName,
     packs: {
@@ -1825,41 +1828,93 @@ function generateRglConfig(config) {
     regolith: {
       dataPath: "./data",
       filterDefinitions: {
-        esbuild: {
-          url: "github.com/ink0rr/regolith-filters",
-          version: VERSIONS.esbuildFilter
+        typegen: {
+          runWith: "nodejs",
+          script: "./filters/typegen/main.js"
+        },
+        rolldown: {
+          runWith: "nodejs",
+          script: "./filters/rolldown/main.js"
         }
       },
       profiles: {
         default: {
           export: { target: "development" },
           filters: [
-            {
-              filter: "esbuild",
-              settings: {
-                outfile: `./BP/${getScriptEntryPath(config)}`,
-                sourcemap: true,
-                minify: false
-              }
-            }
+            { filter: "typegen" },
+            { filter: "rolldown" }
           ]
         },
         build: {
           export: { target: "local" },
           filters: [
-            {
-              filter: "esbuild",
-              settings: {
-                outfile: `./BP/${getScriptEntryPath(config)}`,
-                minify: true
-              }
-            }
+            { filter: "typegen" },
+            { filter: "rolldown", arguments: ["--prod"] }
+          ]
+        },
+        preview: {
+          export: { target: "development" },
+          filters: [
+            { profile: "build" }
           ]
         }
       }
     }
   };
 }
+function getRolldownExternalModules(config) {
+  return ["@minecraft/server", ...config.scriptPackages.serverUi ? ["@minecraft/server-ui"] : []];
+}
+function generateRolldownFilterMain(config) {
+  const external = getRolldownExternalModules(config).map((moduleName) => JSON.stringify(moduleName)).join(", ");
+  const outfile = `./BP/${getScriptEntryPath(config)}`;
+  return `import { build, defineConfig } from "rolldown";
+
+const arg = process.argv[2];
+
+const config = defineConfig({
+	external: [${external}],
+	input: "./data/scripts/main.ts",
+	output: {
+		format: "esm",
+		file: ${JSON.stringify(outfile)},
+		sourcemap: true,
+	},
+	tsconfig: "./data/scripts/tsconfig.json",
+});
+
+if (arg === "--prod") {
+	config.output.minify = true;
+	config.output.sourcemap = false;
+	config.transform = {
+		dropLabels: ["DEBUG"],
+	};
+}
+
+await build(config);
+`;
+}
+function generateRolldownFilterPackageJson() {
+  return {
+    name: "rolldown-filter",
+    private: true,
+    type: "module",
+    dependencies: {
+      rolldown: VERSIONS.rolldown
+    }
+  };
+}
+function generateTypegenFilterPackageJson() {
+  return {
+    name: "typegen",
+    private: true,
+    type: "module",
+    dependencies: {
+      "es-toolkit": VERSIONS.esToolkit,
+      "jsonc-parser": VERSIONS.jsoncParser
+    }
+  };
+}
 function generateMainTs(config) {
   return `import { world } from "@minecraft/server";
 
@@ -1882,11 +1937,74 @@ function generateLangFile(projectName, packType) {
 pack.description=Generated with Spawnpack
 `;
 }
-function generateGitignore() {
-  return `node_modules/
-dist/
-.logs/
-*.zip
+function generateScriptsTsConfig() {
+  return {
+    compilerOptions: {
+      lib: [
+        "ES2015",
+        "ES2016.Array.Include",
+        "ES2017.ArrayBuffer",
+        "ES2017.Date",
+        "ES2017.Object",
+        "ES2017.String",
+        "ES2017.TypedArrays",
+        "ES2018.AsyncIterable",
+        "ES2018.AsyncGenerator",
+        "ES2018.Promise",
+        "ES2018.Regexp",
+        "ES2019.Array",
+        "ES2019.Object",
+        "ES2019.String",
+        "ES2019.Symbol",
+        "ES2020.BigInt",
+        "ES2020.Date",
+        "ES2020.Number",
+        "ES2015.Promise",
+        "ES2020.String",
+        "ES2020.Promise",
+        "ES2020.Symbol.WellKnown",
+        "ES2021.Promise",
+        "ES2021.String",
+        "ES2022.Array",
+        "ES2022.Error",
+        "ES2022.Object",
+        "ES2022.RegExp",
+        "ES2022.String",
+        "ES2023.Array",
+        "ES2023.Collection",
+        "ES2024.ArrayBuffer",
+        "ES2024.Collection",
+        "ES2024.Object",
+        "ES2024.Promise",
+        "ES2024.Regexp",
+        "ES2024.String"
+      ],
+      target: "es2024",
+      module: "es2022",
+      moduleDetection: "force",
+      allowJs: true,
+      moduleResolution: "bundler",
+      noEmit: true,
+      strict: true,
+      skipLibCheck: true,
+      noFallthroughCasesInSwitch: true,
+      noImplicitOverride: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      paths: { "~/*": ["./*"] }
+    }
+  };
+}
+function generateGitignore(config) {
+  const lines = ["node_modules/", "dist/", ".logs/", "*.zip"];
+  if (config.useRgl) {
+    lines.push("/.regolith", "/build");
+  }
+  if (config.useRgl && config.scripting === "typescript") {
+    lines.push("data/scripts/generated_types.ts");
+  }
+  return `${lines.join(`
+`)}
 `;
 }
 function generateReadme(config) {
@@ -1895,13 +2013,14 @@ function generateReadme(config) {
   const installStep = config.scripting !== "none" ? "1. Install dependencies with `bun install` or `npm install`." : "1. No package install is required for this scaffold.";
   const buildSteps = config.scripting === "none" ? "2. Edit your BP/RP JSON files directly inside `packs/`." : config.useRgl ? "2. Run `rgl watch` while developing to rebuild and export your add-on automatically.\n3. Run `rgl run build` when you want a production build." : config.scripting === "typescript" ? "2. Write your gameplay scripts in `data/scripts/`.\n3. Run `bun run build` or `npm run build` to compile TypeScript into `packs/BP/scripts/`." : "2. Write your gameplay scripts in `packs/BP/scripts/` and let Minecraft copy the pack into `com.mojang`.";
   const aiDocFilename = getAiDocFilename(config.aiSetup);
+  const ponytailAiLine = config.installPonytail ? config.aiSetup === "other" ? "Ponytail is enabled via `opencode.json`.\n\n" : "To enable ponytail in Claude Code, run `/plugin marketplace add DietrichGebert/ponytail` then `/plugin install ponytail@ponytail`.\n\n" : "";
   const aiSection = aiDocFilename !== null ? `## AI Tooling
 
 Spawnpack generated \`${aiDocFilename}\` and \`.mcp.json\` for AI-assisted development. The configured MCP servers work out of the box — no API keys required.
 
 Exa's hosted MCP runs on a rate-limited free tier. If you need higher limits, you can add your own Exa API key to \`.mcp.json\` (optional): https://dashboard.exa.ai/api-keys
 
-` : "";
+${ponytailAiLine}` : "";
   const scriptPackageSection = config.scripting !== "none" ? `## Script Packages
 
 Selected npm packages are installed through \`package.json\`. Only runtime Script API modules such as \`@minecraft/server\` and \`@minecraft/server-ui\` are written to \`packs/BP/manifest.json\`; npm-side libraries such as \`@minecraft/vanilla-data\` and \`@minecraft/math\` are imported and bundled from \`package.json\`.
@@ -1935,6 +2054,7 @@ ${scriptPackageSection}${config.useRgl ? `## rgl Workflow
 - \`rgl watch\` rebuilds your scripts and exports your add-on while you work.
 - \`rgl run\` builds a development export once.
 - \`rgl run build\` creates a production-ready build.
+- \`typegen\` auto-generates typed custom IDs (\`BlockId\`/\`EntityId\`/\`ItemId\`) into \`data/scripts/generated_types.ts\` on each build.
 
 The generated \`config.json\` already points the script bundle to \`${runtimeEntry}\`.
 
@@ -1970,6 +2090,10 @@ function generateTerrainTexture(config) {
 }
 
 // src/engine/generator.ts
+var TYPEGEN_FILTER_TEMPLATE_URLS = [
+  new URL("../../templates/filters/typegen/main.js", import.meta.url),
+  new URL("../templates/filters/typegen/main.js", import.meta.url)
+];
 var BP_NAMESPACED_DIRECTORIES = [
   "animation_controllers",
   "animations",
@@ -2009,6 +2133,16 @@ async function writeJsonFile(filePath, value) {
 async function writeTextFile(filePath, value) {
   await writeFile(filePath, value, "utf8");
 }
+async function createTypegenFilterMain() {
+  for (const templateUrl of TYPEGEN_FILTER_TEMPLATE_URLS) {
+    const templateFile = Bun.file(templateUrl);
+    const exists = await templateFile.exists().then((value) => value, () => false);
+    if (exists) {
+      return await templateFile.text();
+    }
+  }
+  return await Bun.file(TYPEGEN_FILTER_TEMPLATE_URLS[0]).text();
+}
 function getScopedContentDirectory(basePath, folder, config) {
   return join(basePath, folder, ...getMarketplaceScopeSegments(config));
 }
@@ -2069,6 +2203,9 @@ async function generateProject(config) {
       directories.push(join(bpPath, "scripts"), join(bpPath, "scripts", config.identifier), bpScriptPath);
     }
   }
+  if (config.useRgl && config.scripting !== "none") {
+    directories.push(join(destination, "filters"), join(destination, "filters", "rolldown"), join(destination, "filters", "typegen"));
+  }
   await Promise.all(directories.filter(shouldCreateDirectory).map((directory) => mkdir(directory, { recursive: true })));
   const bpUuid = crypto.randomUUID();
   const rpUuid = crypto.randomUUID();
@@ -2086,7 +2223,7 @@ async function generateProject(config) {
     writeTextFile(join(rpPath, "textures", "flipbook_textures.json"), "[]"),
     writeTextFile(join(bpPath, "texts", "languages.json"), '["en_US"]'),
     writeTextFile(join(rpPath, "texts", "languages.json"), '["en_US"]'),
-    writeTextFile(join(destination, ".gitignore"), generateGitignore()),
+    writeTextFile(join(destination, ".gitignore"), generateGitignore(config)),
     writeTextFile(join(destination, "README.md"), generateReadme(config))
   ];
   if (config.scripting !== "none") {
@@ -2096,10 +2233,11 @@ async function generateProject(config) {
     writes.push(writeTextFile(join(bpScriptPath, "main.js"), generateMainJs(config)));
   }
   if (config.scripting === "typescript") {
-    writes.push(writeJsonFile(join(destination, "tsconfig.json"), generateTsConfig(config)), writeJsonFile(join(destination, "dprint.json"), generateDprintConfig()), writeTextFile(join(dataScriptsPath, "main.ts"), generateMainTs(config)));
+    const tsconfigWrite = config.useRgl ? writeJsonFile(join(dataScriptsPath, "tsconfig.json"), generateScriptsTsConfig()) : writeJsonFile(join(destination, "tsconfig.json"), generateTsConfig(config));
+    writes.push(tsconfigWrite, writeJsonFile(join(destination, "dprint.json"), generateDprintConfig()), writeTextFile(join(dataScriptsPath, "main.ts"), generateMainTs(config)));
   }
   if (config.scripting !== "none" && config.useRgl) {
-    writes.push(writeJsonFile(join(destination, "config.json"), generateRglConfig(config)));
+    writes.push(writeJsonFile(join(destination, "config.json"), generateRglConfig(config)), writeTextFile(join(destination, "filters", "rolldown", "main.js"), generateRolldownFilterMain(config)), writeJsonFile(join(destination, "filters", "rolldown", "package.json"), generateRolldownFilterPackageJson()), writeJsonFile(join(destination, "filters", "typegen", "package.json"), generateTypegenFilterPackageJson()), writeTextFile(join(destination, "filters", "typegen", "main.js"), await createTypegenFilterMain()));
   }
   await Promise.all(writes);
 }
@@ -2142,6 +2280,7 @@ var AI_EXCLUDE_LINES = [
   "/CLAUDE.md",
   "/AGENTS.md",
   "/.mcp.json",
+  "/opencode.json",
   "/.claude/"
 ];
 function getTemplateUrls(filename) {
@@ -2201,13 +2340,42 @@ async function setupGitExcludes(projectPath) {
     return;
   });
 }
-async function setupAi(projectPath, aiSetup) {
+async function writeOpencodePluginConfig(projectPath) {
+  const configPath = join3(projectPath, "opencode.json");
+  const pluginId = "@dietrichgebert/ponytail";
+  const file = Bun.file(configPath);
+  const exists = await file.exists().then((value) => value, () => false);
+  let nextConfig = {
+    $schema: "https://opencode.ai/config.json",
+    plugin: [pluginId]
+  };
+  if (exists) {
+    try {
+      const parsed = await file.json();
+      const plugins = Array.isArray(parsed.plugin) ? [...parsed.plugin] : [];
+      if (!plugins.includes(pluginId)) {
+        plugins.push(pluginId);
+      }
+      nextConfig = { ...parsed, plugin: plugins };
+    } catch {}
+  }
+  await Bun.write(configPath, `${JSON.stringify(nextConfig, null, 4)}
+`).then(() => {
+    return;
+  }, () => {
+    return;
+  });
+}
+async function setupAi(projectPath, aiSetup, installPonytail) {
   if (aiSetup === "none") {
     return;
   }
   await generateAiDoc(projectPath, aiSetup);
   await setupGitExcludes(projectPath);
   await generateMcpConfig(projectPath);
+  if (installPonytail && aiSetup === "other") {
+    await writeOpencodePluginConfig(projectPath);
+  }
 }
 
 // src/provisioning/tools.ts
@@ -2405,8 +2573,20 @@ function showFolderTree(config) {
   lines.push(import_picocolors.default.dim("│     └─ manifest.json"));
   if (config.scripting === "typescript") {
     lines.push(import_picocolors.default.dim("├─ data/scripts/"));
-    lines.push(import_picocolors.default.dim("│  └─ main.ts"));
-    lines.push(import_picocolors.default.dim("├─ tsconfig.json"));
+    if (config.useRgl) {
+      lines.push(import_picocolors.default.dim("│  ├─ main.ts"));
+      lines.push(import_picocolors.default.dim("│  └─ tsconfig.json"));
+      lines.push(import_picocolors.default.dim("├─ filters/"));
+      lines.push(import_picocolors.default.dim("│  ├─ rolldown/"));
+      lines.push(import_picocolors.default.dim("│  │  ├─ main.js"));
+      lines.push(import_picocolors.default.dim("│  │  └─ package.json"));
+      lines.push(import_picocolors.default.dim("│  └─ typegen/"));
+      lines.push(import_picocolors.default.dim("│     ├─ main.js"));
+      lines.push(import_picocolors.default.dim("│     └─ package.json"));
+    } else {
+      lines.push(import_picocolors.default.dim("│  └─ main.ts"));
+      lines.push(import_picocolors.default.dim("├─ tsconfig.json"));
+    }
     lines.push(import_picocolors.default.dim("├─ dprint.json"));
   }
   if (config.scripting === "javascript") {
@@ -2422,6 +2602,9 @@ function showFolderTree(config) {
   if (aiDocFilename !== null) {
     lines.push(import_picocolors.default.dim(`├─ ${aiDocFilename}`));
     lines.push(import_picocolors.default.dim("├─ .mcp.json"));
+    if (config.installPonytail && config.aiSetup === "other") {
+      lines.push(import_picocolors.default.dim("├─ opencode.json"));
+    }
   }
   lines.push(import_picocolors.default.dim("├─ .gitignore"));
   lines.push(import_picocolors.default.dim("└─ README.md"));
@@ -2449,6 +2632,7 @@ function showReview(config) {
     `${border}  ${import_picocolors.default.dim(padLabel("rgl:"))} ${formatToggle(config.useRgl)}`,
     `${border}  ${import_picocolors.default.dim(padLabel("Rockide:"))} ${formatToggle(config.installRockide)}`,
     `${border}  ${import_picocolors.default.dim(padLabel("AI Setup:"))} ${formatValue(getAiSetupLabel(config.aiSetup))}`,
+    ...config.aiSetup !== "none" ? [`${border}  ${import_picocolors.default.dim(padLabel("Ponytail:"))} ${formatToggle(config.installPonytail)}`] : [],
     "",
     `${border}  ${teal(import_picocolors.default.bold("Planned structure"))}`,
     ...showFolderTree(config).split(`
@@ -2483,6 +2667,16 @@ function showPostGeneration(config) {
     usefulCommands.push("");
     usefulCommands.push(`${teal(import_picocolors.default.bold("Note"))} ${import_picocolors.default.dim(".mcp.json is ready to use — the configured MCP servers need no API keys.")}`);
   }
+  if (config.installPonytail) {
+    usefulCommands.push("");
+    if (config.aiSetup === "claude") {
+      usefulCommands.push(`${teal(import_picocolors.default.bold("Ponytail"))} ${import_picocolors.default.dim("Run inside Claude Code:")}`);
+      usefulCommands.push(`  ${import_picocolors.default.cyan("/plugin marketplace add DietrichGebert/ponytail")}`);
+      usefulCommands.push(`  ${import_picocolors.default.cyan("/plugin install ponytail@ponytail")}`);
+    } else {
+      usefulCommands.push(`${teal(import_picocolors.default.bold("Ponytail"))} ${import_picocolors.default.dim("Added to opencode.json — installs on next opencode run.")}`);
+    }
+  }
   O2.message([...nextSteps, "", ...usefulCommands].join(`
 `), {
     symbol: teal("▲")
@@ -2655,7 +2849,7 @@ async function runWizard() {
     message: import_picocolors2.default.bold("AI setup"),
     initialValue: "none",
     options: [
-      { value: "none", label: "None", hint: "no AI docs or MCP config" },
+      { value: "none", label: "None", hint: "No AI configuration setup" },
       { value: "claude", label: "Claude", hint: "generate CLAUDE.md and .mcp.json" },
       { value: "other", label: "Other", hint: "generate AGENTS.md and .mcp.json" }
     ]
@@ -2663,6 +2857,17 @@ async function runWizard() {
   if (q(aiSetup)) {
     return abortWizard();
   }
+  let installPonytail = false;
+  if (aiSetup !== "none") {
+    const ponytailChoice = await ot2({
+      message: `${import_picocolors2.default.bold("Install ponytail plugin?")} ${import_picocolors2.default.dim("Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote. https://github.com/DietrichGebert/ponytail")}`,
+      initialValue: true
+    });
+    if (q(ponytailChoice)) {
+      return abortWizard();
+    }
+    installPonytail = ponytailChoice;
+  }
   const config = {
     projectName: trimmedProjectName,
     author: author.trim(),
@@ -2674,7 +2879,8 @@ async function runWizard() {
     useMarketplaceStructure,
     useRgl: scripting === "none" ? false : useRgl,
     aiSetup,
-    installRockide: installRockide2
+    installRockide: installRockide2,
+    installPonytail
   };
   showReview(config);
   const shouldGenerate = await ot2({
@@ -2703,7 +2909,7 @@ var generation = fe();
 generation.start(teal3("Generating your Bedrock addon scaffold..."));
 await generateProject(config);
 if (config.aiSetup !== "none") {
-  await setupAi(config.destination, config.aiSetup);
+  await setupAi(config.destination, config.aiSetup, config.installPonytail);
 }
 await runProvisioning(config);
 generation.stop(import_picocolors3.default.green("Spawnpack scaffold generated."));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "spawnpack",
-    "version": "0.1.9",
+    "version": "0.1.11",
     "description": "Minecraft Bedrock addon project generator — scaffold your BP+RP in seconds",
     "author": "veedy-dev",
     "license": "MIT",
@@ -13,6 +13,7 @@
         "dist/spawnpack.js",
         "templates/CLAUDE.md",
         "templates/AGENTS.md",
+        "templates/filters/typegen/main.js",
         "README.md",
         "LICENSE",
         "package.json"

package/templates/AGENTS.md

@@ -246,27 +246,37 @@ PLAN:
 ALWAYS use Exa to search the latest Minecraft Script API documentation before implementing. APIs change every major update — never trust memory.
 </guideline>
 
-<guideline name="no_try_catch" priority="critical">
-Do NOT use `try-catch` blocks (overhead concerns). Use **guard clauses** for error prevention instead.
-
-```typescript
-// ✅ CORRECT: Use guard clauses
-function processBlock(block: Block | undefined): void {
+<guideline name="guard_first_error_handling" priority="critical">
+Prefer **guard clauses** for predictable invalid state: missing values, unloaded or invalid entities, optional components, permissions, and known preconditions. `throw`, `try`, and `catch` are allowed when they are truly necessary: APIs can fail despite correct guards, you are crossing IO/persistence/parsing/async boundaries, or you need cleanup, recovery, or clearer error context.
+
+Keep `catch` blocks narrow and purposeful. Do not use `try-catch` as normal control flow, to hide mistakes, or where a simple guard makes the failure impossible.
+
+```typescript
+// ✅ CORRECT: Use guard clauses
+function processBlock(block: Block | undefined): void {
   if (!block) return;
   if (!block.isValid) return;
   const permutation = block.permutation;
-}
-
-// ❌ WRONG: Using try-catch
-function processBlockBad(block: Block): void {
-  try {
-    const permutation = block.permutation;
-  } catch (e) {
-    // Overhead!
-  }
-}
-```
-</guideline>
+}
+
+// ✅ CORRECT: Use try-catch only at a real failure boundary
+function loadSavedConfig(rawConfig: string): AddonConfig {
+  try {
+    return JSON.parse(rawConfig) as AddonConfig;
+  } catch (error) {
+    throw new Error("Saved addon config is not valid JSON", { cause: error });
+  }
+}
+
+// ❌ WRONG: Catching instead of checking known state
+function processBlockBad(block: Block | undefined): void {
+  try {
+    const permutation = block!.permutation;
+  } catch {
+  }
+}
+```
+</guideline>
 
 <guideline name="typescript_verification" priority="critical">
 ALWAYS run `tsc --noEmit` after implementing. Ensure **zero warnings, zero errors, and no unused variables/imports**.
@@ -395,7 +405,7 @@ ALWAYS use Minecraft Bedrock Edition JSON Schemas for validation of BP/RP JSON f
 - Use explicit return types on functions
 - Use `readonly` for immutable properties
 - Prefer interfaces over type aliases for object shapes
-- Use `undefined` checks instead of try-catch
+- Use `undefined` checks and guard clauses before reaching for try-catch
 </best_practices>
 
 <best_practices name="script_api">
@@ -598,7 +608,7 @@ POTENTIAL CONCERNS:
 13. Editing files from stale context without re-reading first
 14. Duplicating state instead of fixing the real problem
 15. Writing library/framework code from memory without searching Exa for current docs first
-16. Using try-catch in Minecraft Script API code
+16. Using broad try-catch in Minecraft Script API code where guard clauses would be clearer
 17. Creating custom math functions when @minecraft/math has them available
 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
 19. Writing BP/RP JSON files without schema validation
@@ -614,7 +624,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
-4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
+4. **GUARD CLAUSES FIRST** — Prefer guards; use throw/try-catch only at real failure boundaries
 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
@@ -625,7 +635,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
 - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
 - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation
-- ❌ Used try-catch in Minecraft code? → Violated no-try-catch rule
+- ❌ Used broad try-catch where guards would work? → Violated guard-first error handling
 - ❌ Made changes without running `tsc --noEmit`? → Violated TypeScript verification
 - ❌ Created custom math function without checking @minecraft/math? → Violated library-first rule
 - ❌ Used raw string like `"inventory"` or `"minecraft:wolf"`? → Violated vanilla-data rule

package/templates/CLAUDE.md

@@ -246,27 +246,37 @@ PLAN:
 ALWAYS use Exa to search the latest Minecraft Script API documentation before implementing. APIs change every major update — never trust memory.
 </guideline>
 
-<guideline name="no_try_catch" priority="critical">
-Do NOT use `try-catch` blocks (overhead concerns). Use **guard clauses** for error prevention instead.
-
-```typescript
-// ✅ CORRECT: Use guard clauses
-function processBlock(block: Block | undefined): void {
+<guideline name="guard_first_error_handling" priority="critical">
+Prefer **guard clauses** for predictable invalid state: missing values, unloaded or invalid entities, optional components, permissions, and known preconditions. `throw`, `try`, and `catch` are allowed when they are truly necessary: APIs can fail despite correct guards, you are crossing IO/persistence/parsing/async boundaries, or you need cleanup, recovery, or clearer error context.
+
+Keep `catch` blocks narrow and purposeful. Do not use `try-catch` as normal control flow, to hide mistakes, or where a simple guard makes the failure impossible.
+
+```typescript
+// ✅ CORRECT: Use guard clauses
+function processBlock(block: Block | undefined): void {
   if (!block) return;
   if (!block.isValid) return;
   const permutation = block.permutation;
-}
-
-// ❌ WRONG: Using try-catch
-function processBlockBad(block: Block): void {
-  try {
-    const permutation = block.permutation;
-  } catch (e) {
-    // Overhead!
-  }
-}
-```
-</guideline>
+}
+
+// ✅ CORRECT: Use try-catch only at a real failure boundary
+function loadSavedConfig(rawConfig: string): AddonConfig {
+  try {
+    return JSON.parse(rawConfig) as AddonConfig;
+  } catch (error) {
+    throw new Error("Saved addon config is not valid JSON", { cause: error });
+  }
+}
+
+// ❌ WRONG: Catching instead of checking known state
+function processBlockBad(block: Block | undefined): void {
+  try {
+    const permutation = block!.permutation;
+  } catch {
+  }
+}
+```
+</guideline>
 
 <guideline name="typescript_verification" priority="critical">
 ALWAYS run `tsc --noEmit` after implementing. Ensure **zero warnings, zero errors, and no unused variables/imports**.
@@ -395,7 +405,7 @@ ALWAYS use Minecraft Bedrock Edition JSON Schemas for validation of BP/RP JSON f
 - Use explicit return types on functions
 - Use `readonly` for immutable properties
 - Prefer interfaces over type aliases for object shapes
-- Use `undefined` checks instead of try-catch
+- Use `undefined` checks and guard clauses before reaching for try-catch
 </best_practices>
 
 <best_practices name="script_api">
@@ -598,7 +608,7 @@ POTENTIAL CONCERNS:
 13. Editing files from stale context without re-reading first
 14. Duplicating state instead of fixing the real problem
 15. Writing library/framework code from memory without searching Exa for current docs first
-16. Using try-catch in Minecraft Script API code
+16. Using broad try-catch in Minecraft Script API code where guard clauses would be clearer
 17. Creating custom math functions when @minecraft/math has them available
 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
 19. Writing BP/RP JSON files without schema validation
@@ -614,7 +624,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
-4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
+4. **GUARD CLAUSES FIRST** — Prefer guards; use throw/try-catch only at real failure boundaries
 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
@@ -625,7 +635,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
 - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
 - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation
-- ❌ Used try-catch in Minecraft code? → Violated no-try-catch rule
+- ❌ Used broad try-catch where guards would work? → Violated guard-first error handling
 - ❌ Made changes without running `tsc --noEmit`? → Violated TypeScript verification
 - ❌ Created custom math function without checking @minecraft/math? → Violated library-first rule
 - ❌ Used raw string like `"inventory"` or `"minecraft:wolf"`? → Violated vanilla-data rule

package/templates/filters/typegen/main.js

@@ -0,0 +1,86 @@
+import { pascalCase } from "es-toolkit";
+import * as JSONC from "jsonc-parser";
+import { glob, mkdir, readFile, writeFile } from "node:fs/promises";
+import { matchesGlob } from "node:path";
+
+const entries = [
+	{
+		type: "BlockId",
+		pattern: "BP/blocks/**/*.json",
+		jsonPath: ["minecraft:block", "description", "identifier"],
+		identifiers: [],
+	},
+	{
+		type: "EntityId",
+		pattern: "BP/entities/**/*.json",
+		jsonPath: ["minecraft:entity", "description", "identifier"],
+		identifiers: [],
+	},
+	{
+		type: "ItemId",
+		pattern: "BP/items/**/*.json",
+		jsonPath: ["minecraft:item", "description", "identifier"],
+		identifiers: [],
+	},
+];
+
+for (const dir of ["BP", "RP"]) {
+	for await (const path of glob(`${dir}/**/*.json`)) {
+		const entry = entries.find((f) => matchesGlob(path, f.pattern));
+		if (!entry) continue;
+
+		let found = false;
+		const text = await readFile(path, "utf8");
+		JSONC.visit(text, {
+			onArrayBegin() {
+				return !found;
+			},
+			onObjectBegin() {
+				return !found;
+			},
+			onLiteralValue(value, _offset, _length, _startLine, _startCharacter, pathSupplier) {
+				if (typeof value !== "string") return;
+				if (!pathSupplier().every((segment, i) => segment === entry.jsonPath[i])) return;
+
+				found = true;
+				entry.identifiers.push(value);
+			},
+		});
+	}
+}
+
+const lines = ["// Auto-generated file. DO NOT EDIT MANUALLY!\n"];
+
+for (const entry of entries) {
+	if (entry.identifiers.length === 0) continue;
+
+	lines.push(`export const enum ${entry.type} {`);
+	for (const id of entry.identifiers) {
+		const colIndex = id.indexOf(":");
+		if (colIndex === -1) {
+			console.warn(`Invalid identifier: ${id}`);
+			continue;
+		}
+		const name = id.slice(colIndex + 1).trim();
+		if (name === "") {
+			console.warn(`Invalid identifier: ${id}`);
+			continue;
+		}
+		lines.push(`\t${pascalCase(name)} = "${id}",`);
+	}
+	lines.push(`}\n`);
+}
+
+const res = lines.join("\n");
+
+const ROOT_DIR = process.env.ROOT_DIR;
+
+const current = await readFile(`${ROOT_DIR}/data/scripts/generated_types.ts`, "utf8")
+	.catch(() => null);
+
+if (current !== res) {
+	await Promise.all([
+		writeFile(`${ROOT_DIR}/data/scripts/generated_types.ts`, res),
+		writeFile("./data/scripts/generated_types.ts", res),
+	]);
+}