@defold-typescript/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1017 @@
+// src/build-session.ts
+import { readFileSync as readFileSync2, rmSync } from "node:fs";
+import * as path3 from "node:path";
+import {
+  createTranspileSession
+} from "@defold-typescript/transpiler";
+
+// src/build-output.ts
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+var DEFAULT_INCLUDE = ["src/**/*.ts"];
+var PROJECT_BUCKET = "<project>";
+function toPosix(p, sep2 = path.sep) {
+  return p.split(sep2).join("/");
+}
+function readBuildConfig(cwd) {
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  let raw;
+  try {
+    raw = readFileSync(tsconfigPath, "utf8");
+  } catch {
+    throw new Error(`defold-typescript build: no tsconfig.json at ${cwd}; run 'defold-typescript init' first.`);
+  }
+  const tsconfig = JSON.parse(raw);
+  const outDir = tsconfig.compilerOptions?.outDir;
+  const include = tsconfig.include?.length ? tsconfig.include : DEFAULT_INCLUDE;
+  return { outDir, include };
+}
+function stripIncludeBase(pattern) {
+  const firstWildcard = pattern.search(/[*?[]/);
+  if (firstWildcard === -1) {
+    return pattern.endsWith("/") ? pattern : `${path.posix.dirname(pattern)}/`;
+  }
+  const upToWildcard = pattern.slice(0, firstWildcard);
+  const lastSlash = upToWildcard.lastIndexOf("/");
+  return lastSlash === -1 ? "" : upToWildcard.slice(0, lastSlash + 1);
+}
+function computeLuaRel(rel, config) {
+  const { outDir, include } = config;
+  if (outDir === undefined || outDir === "" || outDir === ".") {
+    return rel.replace(/\.ts$/, ".lua");
+  }
+  const includeBase = include.map(stripIncludeBase).filter((base) => rel.startsWith(base)).sort((a, b) => b.length - a.length)[0] ?? "";
+  const relUnderBase = rel.slice(includeBase.length);
+  return path.posix.join(outDir, relUnderBase.replace(/\.ts$/, ".lua"));
+}
+function collectFailures(diagnostics) {
+  const failures = new Map;
+  for (const diag of diagnostics) {
+    const bucket = diag.file ?? PROJECT_BUCKET;
+    const list = failures.get(bucket);
+    if (list) {
+      list.push(diag.message);
+    } else {
+      failures.set(bucket, [diag.message]);
+    }
+  }
+  return failures;
+}
+function throwIfFailures(failures) {
+  if (failures.size === 0) {
+    return;
+  }
+  const formatted = [...failures.entries()].map(([file, messages]) => `  ${file}: ${messages.join("; ")}`).join(`
+`);
+  throw new Error(`defold-typescript build: ${failures.size} file(s) failed:
+${formatted}`);
+}
+function writeLuaFile(cwd, luaRel, lua, map) {
+  const luaAbs = path.join(cwd, luaRel);
+  mkdirSync(path.dirname(luaAbs), { recursive: true });
+  if (map) {
+    const mapBasename = `${path.posix.basename(luaRel)}.map`;
+    writeFileSync(`${luaAbs}.map`, map);
+    writeFileSync(luaAbs, `${lua}
+--# sourceMappingURL=${mapBasename}
+`);
+  } else {
+    writeFileSync(luaAbs, lua);
+  }
+}
+
+// src/scan.ts
+import { globSync, statSync } from "node:fs";
+import * as path2 from "node:path";
+function scanFilesSync(cwd, pattern) {
+  return globSync(pattern, { cwd }).filter((rel) => statSync(path2.join(cwd, rel)).isFile());
+}
+
+// src/build-session.ts
+function createBuildSession(opts) {
+  const { cwd } = opts;
+  const config = readBuildConfig(cwd);
+  const session = createTranspileSession();
+  function writeOutputs(result, keys) {
+    const failures = collectFailures(result.diagnostics);
+    const written = [];
+    for (const rel of keys) {
+      if (failures.has(rel)) {
+        continue;
+      }
+      const lua = result.lua[rel];
+      if (lua === undefined) {
+        continue;
+      }
+      const luaRel = computeLuaRel(rel, config);
+      writeLuaFile(cwd, luaRel, lua, result.sourceMaps[rel]);
+      written.push(luaRel);
+    }
+    throwIfFailures(failures);
+    return { written };
+  }
+  function buildAll() {
+    const seen = new Set;
+    for (const pattern of config.include) {
+      for (const match of scanFilesSync(cwd, pattern)) {
+        seen.add(toPosix(match));
+      }
+    }
+    const sources = [...seen].sort();
+    if (sources.length === 0) {
+      return { written: [] };
+    }
+    const files = {};
+    for (const rel of sources) {
+      files[rel] = readFileSync2(path3.join(cwd, rel), "utf8");
+    }
+    const result = session.update(files);
+    return writeOutputs(result, sources);
+  }
+  function applyEvents(changed, removed) {
+    const changes = {};
+    for (const rel of changed) {
+      changes[rel] = readFileSync2(path3.join(cwd, rel), "utf8");
+    }
+    for (const rel of removed) {
+      changes[rel] = null;
+    }
+    const result = session.update(changes);
+    for (const rel of removed) {
+      const luaAbs = path3.join(cwd, computeLuaRel(rel, config));
+      rmSync(luaAbs, { force: true });
+      rmSync(`${luaAbs}.map`, { force: true });
+    }
+    return writeOutputs(result, changed);
+  }
+  return { buildAll, applyEvents };
+}
+// src/dispatch.ts
+import { existsSync as existsSync5, readFileSync as readFileSync7 } from "node:fs";
+import * as path9 from "node:path";
+
+// src/api-registry.ts
+import { existsSync, readFileSync as readFileSync3 } from "node:fs";
+import { createRequire } from "node:module";
+import * as path4 from "node:path";
+function findPackageRoot(start) {
+  let dir = start;
+  for (;; ) {
+    if (existsSync(path4.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function resolveTypesPackageRoot() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const entry = require2.resolve("@defold-typescript/types");
+    return findPackageRoot(path4.dirname(entry));
+  } catch {
+    return null;
+  }
+}
+function loadApiTargetsRegistry() {
+  const root = resolveTypesPackageRoot();
+  if (root === null) {
+    return [];
+  }
+  const registryPath = path4.join(root, "api-targets.json");
+  if (!existsSync(registryPath)) {
+    return [];
+  }
+  try {
+    const { targets } = JSON.parse(readFileSync3(registryPath, "utf8"));
+    return targets;
+  } catch {
+    return [];
+  }
+}
+
+// src/defold-version.ts
+var CURRENT_STABLE_DEFOLD_VERSION = "1.12.4";
+function readDefoldVersionPin(pkg) {
+  if (typeof pkg !== "object" || pkg === null) {
+    return;
+  }
+  const namespace = pkg["defold-typescript"];
+  if (typeof namespace !== "object" || namespace === null) {
+    return;
+  }
+  const version = namespace["defold-version"];
+  return typeof version === "string" ? version : undefined;
+}
+function resolveDefoldVersion(opts) {
+  if (opts.flag !== undefined) {
+    return { version: opts.flag, source: "flag" };
+  }
+  if (opts.pin !== undefined) {
+    return { version: opts.pin, source: "pin" };
+  }
+  return { version: CURRENT_STABLE_DEFOLD_VERSION, source: "default" };
+}
+
+// src/api-surface.ts
+var CURRENT_STABLE_SURFACE_ID = `defold-${CURRENT_STABLE_DEFOLD_VERSION}`;
+function selectApiSurface(resolvedVersion) {
+  const id = `defold-${resolvedVersion}`;
+  const target = loadApiTargetsRegistry().find((t) => t.id === id);
+  if (target) {
+    return { surfaceId: target.id, available: true };
+  }
+  return { surfaceId: null, available: false };
+}
+
+// src/build.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import * as path5 from "node:path";
+import { transpileProject } from "@defold-typescript/transpiler";
+function runBuild(opts) {
+  const { cwd } = opts;
+  const config = readBuildConfig(cwd);
+  const seen = new Set;
+  for (const pattern of config.include) {
+    for (const match of scanFilesSync(cwd, pattern)) {
+      seen.add(toPosix(match));
+    }
+  }
+  const sources = [...seen].sort();
+  if (sources.length === 0) {
+    return { written: [] };
+  }
+  const files = {};
+  for (const rel of sources) {
+    files[rel] = readFileSync4(path5.join(cwd, rel), "utf8");
+  }
+  const result = transpileProject({ files });
+  const failures = collectFailures(result.diagnostics);
+  const written = [];
+  for (const rel of sources) {
+    if (failures.has(rel)) {
+      continue;
+    }
+    const lua = result.lua[rel];
+    if (!lua) {
+      continue;
+    }
+    const luaRel = computeLuaRel(rel, config);
+    writeLuaFile(cwd, luaRel, lua, result.sourceMaps[rel]);
+    written.push(luaRel);
+  }
+  throwIfFailures(failures);
+  return { written };
+}
+
+// src/init.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "node:fs";
+import * as path6 from "node:path";
+
+// src/script-kind.ts
+var DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
+var KIND_BY_EXT = {
+  ".script": "script",
+  ".gui_script": "gui-script",
+  ".render_script": "render-script"
+};
+var SKIP_SEGMENTS = new Set(["node_modules", ".defold-types", "build"]);
+function isSkipped(relPath) {
+  return relPath.split(/[/\\]/).some((segment) => SKIP_SEGMENTS.has(segment));
+}
+function isComponentPath(relPath) {
+  return Object.keys(KIND_BY_EXT).some((ext) => relPath.endsWith(ext));
+}
+function detectScriptKinds(cwd) {
+  const kinds = new Set;
+  for (const [ext, kind] of Object.entries(KIND_BY_EXT)) {
+    for (const match of scanFilesSync(cwd, `**/*${ext}`)) {
+      if (!isSkipped(match)) {
+        kinds.add(kind);
+        break;
+      }
+    }
+  }
+  return kinds;
+}
+function selectScriptKind(kinds) {
+  if (kinds.size !== 1) {
+    return null;
+  }
+  for (const kind of kinds) {
+    return kind;
+  }
+  return null;
+}
+function selectScriptKindEntrypoint(kinds) {
+  const kind = selectScriptKind(kinds);
+  return kind === null ? DEFAULT_TYPES_ENTRYPOINT : `${DEFAULT_TYPES_ENTRYPOINT}/${kind}`;
+}
+var RESTRICTED_MODULES = {
+  script: "",
+  "gui-script": "gui",
+  "render-script": "render"
+};
+var ALL_RESTRICTED_MODULES = ["gui", "render"];
+function excludedModulesForKind(kind) {
+  if (kind === null) {
+    return new Set;
+  }
+  const allowed = RESTRICTED_MODULES[kind];
+  return new Set(ALL_RESTRICTED_MODULES.filter((mod) => mod !== allowed));
+}
+
+// src/init.ts
+var CONFLICTING_TS_CONFIGS = [
+  "tsconfig.json",
+  "defold-typescript.config.ts",
+  "defold-typescript.config.mts",
+  "defold-typescript.config.js"
+];
+var TSCONFIG_COMPILER_OPTIONS = {
+  target: "ES2022",
+  module: "ESNext",
+  moduleResolution: "Bundler",
+  lib: ["ES2022"],
+  strict: true,
+  skipLibCheck: true
+};
+var GITIGNORE_LINES = ["src/**/*.lua", "src/**/*.lua.map"];
+var BIOME_JSON_CONTENT = {
+  $schema: "https://biomejs.dev/schemas/2.4.15/schema.json",
+  files: {
+    includes: ["src/**/*.ts", "!**/dist", "!**/node_modules", "!**/*.lua"]
+  },
+  formatter: {
+    enabled: true,
+    indentStyle: "space",
+    indentWidth: 2,
+    lineWidth: 100
+  },
+  linter: {
+    enabled: true,
+    rules: {
+      recommended: true,
+      style: {
+        useImportType: "error",
+        useNodejsImportProtocol: "error"
+      },
+      correctness: {
+        noUnusedImports: "error",
+        noUnusedVariables: "warn"
+      }
+    }
+  },
+  javascript: {
+    formatter: {
+      quoteStyle: "double",
+      semicolons: "always",
+      trailingCommas: "all",
+      arrowParentheses: "always"
+    }
+  }
+};
+var MAIN_TS_CONTENT = `export function init(): void {
+  const start = vmath.vector3(0, 0, 0);
+  msg.post("main:/hero", "spawn", { start });
+}
+`;
+var MAIN_SCRIPT_CONTENT = `function init(self) end
+function update(self, dt) end
+function on_message(self, message_id, message, sender) end
+function final(self) end
+`;
+var MAIN_COLLECTION_CONTENT = `name: "main"
+scale_along_z: 0
+embedded_instances {
+  id: "main"
+  data: "components {\\n  id: \\"main\\"\\n  component: \\"/main/main.script\\"\\n}\\n"
+  position { x: 0.0 y: 0.0 z: 0.0 }
+  rotation { x: 0.0 y: 0.0 z: 0.0 w: 1.0 }
+  scale3 { x: 1.0 y: 1.0 z: 1.0 }
+}
+`;
+var SCAFFOLD_DEV_DEPS = {
+  "@defold-typescript/transpiler": "workspace:*",
+  "@defold-typescript/types": "workspace:*",
+  "@biomejs/biome": "^2.2.0"
+};
+function writeJson(filePath, value) {
+  writeFileSync2(filePath, `${JSON.stringify(value, null, 2)}
+`);
+}
+function writeGitignore(cwd) {
+  const gitignorePath = path6.join(cwd, ".gitignore");
+  if (existsSync2(gitignorePath)) {
+    const existing = readFileSync5(gitignorePath, "utf8");
+    const present = new Set(existing.split(`
+`).map((line) => line.trim()));
+    const missing = GITIGNORE_LINES.filter((line) => !present.has(line));
+    if (missing.length === 0) {
+      return;
+    }
+    const prefix = existing.endsWith(`
+`) || existing === "" ? "" : `
+`;
+    writeFileSync2(gitignorePath, `${existing}${prefix}${missing.join(`
+`)}
+`);
+  } else {
+    writeFileSync2(gitignorePath, `${GITIGNORE_LINES.join(`
+`)}
+`);
+  }
+}
+function writeBiome(cwd, written) {
+  const biomePath = path6.join(cwd, "biome.json");
+  if (existsSync2(biomePath)) {
+    return;
+  }
+  writeJson(biomePath, BIOME_JSON_CONTENT);
+  written.push("biome.json");
+}
+function writeTsSurface(cwd, written) {
+  mkdirSync2(path6.join(cwd, "src"), { recursive: true });
+  writeFileSync2(path6.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
+  written.push("src/main.ts");
+  const kinds = detectScriptKinds(cwd);
+  const tsconfig = {
+    compilerOptions: {
+      ...TSCONFIG_COMPILER_OPTIONS,
+      types: [selectScriptKindEntrypoint(kinds)]
+    },
+    include: ["src/**/*.ts"]
+  };
+  writeJson(path6.join(cwd, "tsconfig.json"), tsconfig);
+  written.push("tsconfig.json");
+  const pkgPath = path6.join(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
+    const existing = JSON.parse(readFileSync5(pkgPath, "utf8"));
+    const devDeps = { ...existing.devDependencies ?? {} };
+    for (const [name, version] of Object.entries(SCAFFOLD_DEV_DEPS)) {
+      if (!(name in devDeps)) {
+        devDeps[name] = version;
+      }
+    }
+    existing.devDependencies = devDeps;
+    existing["defold-typescript"] ??= { "defold-version": CURRENT_STABLE_DEFOLD_VERSION };
+    writeJson(pkgPath, existing);
+  } else {
+    const fresh = {
+      name: path6.basename(cwd),
+      version: "0.0.0",
+      type: "module",
+      devDependencies: { ...SCAFFOLD_DEV_DEPS },
+      "defold-typescript": { "defold-version": CURRENT_STABLE_DEFOLD_VERSION }
+    };
+    writeJson(pkgPath, fresh);
+  }
+  written.push("package.json");
+  writeGitignore(cwd);
+  written.push(".gitignore");
+  writeBiome(cwd, written);
+  return selectScriptKind(kinds);
+}
+function runNewProjectInit(cwd, force = false) {
+  if (!existsSync2(cwd)) {
+    mkdirSync2(cwd, { recursive: true });
+  } else if (readdirSync(cwd).length > 0 && !force) {
+    throw new Error(`defold-typescript init: refusing to synthesize a new Defold project into non-empty directory ${cwd}. Pass --force to proceed.`);
+  }
+  const written = [];
+  writeFileSync2(path6.join(cwd, "game.project"), `[project]
+title = ${path6.basename(cwd)}
+main_collection = /main/main.collectionc
+`);
+  written.push("game.project");
+  mkdirSync2(path6.join(cwd, "main"), { recursive: true });
+  writeFileSync2(path6.join(cwd, "main", "main.collection"), MAIN_COLLECTION_CONTENT);
+  written.push("main/main.collection");
+  writeFileSync2(path6.join(cwd, "main", "main.script"), MAIN_SCRIPT_CONTENT);
+  written.push("main/main.script");
+  const scriptKind = writeTsSurface(cwd, written);
+  return { written, scriptKind };
+}
+function runInit(opts) {
+  const { cwd, force = false } = opts;
+  if (!existsSync2(path6.join(cwd, "game.project"))) {
+    return runNewProjectInit(cwd, force);
+  }
+  if (!force) {
+    for (const rel of CONFLICTING_TS_CONFIGS) {
+      if (existsSync2(path6.join(cwd, rel))) {
+        throw new Error(`defold-typescript init: refusing to overwrite existing TS config: ${rel}. Pass --force to overwrite.`);
+      }
+    }
+  }
+  const written = [];
+  const scriptKind = writeTsSurface(cwd, written);
+  return { written, scriptKind };
+}
+
+// src/json-output.ts
+function renderResult(input) {
+  const ok = input.error === undefined;
+  const base = ok ? { command: input.command, ok, written: input.written ?? [] } : { command: input.command, ok, error: input.error };
+  const withVersion = input.defoldVersion === undefined ? base : { ...base, defoldVersion: input.defoldVersion };
+  const withSurface = "apiSurface" in input ? { ...withVersion, apiSurface: input.apiSurface } : withVersion;
+  const withScriptKind = "scriptKind" in input ? { ...withSurface, scriptKind: input.scriptKind } : withSurface;
+  const payload = "materializedSurface" in input ? { ...withScriptKind, materializedSurface: input.materializedSurface } : withScriptKind;
+  return `${JSON.stringify(payload)}
+`;
+}
+
+// src/materialize.ts
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync6,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import * as path7 from "node:path";
+var MATERIALIZED_ROOT = ".defold-types";
+function writeJson2(filePath, value) {
+  writeFileSync3(filePath, `${JSON.stringify(value, null, 2)}
+`);
+}
+function listDts(dir) {
+  return readdirSync2(dir).filter((file) => file.endsWith(".d.ts")).sort();
+}
+function materializeApiSurface(opts) {
+  const { cwd, surface, sourceGeneratedDir } = opts;
+  if (!surface.available || surface.surfaceId === null || sourceGeneratedDir === null) {
+    return { materializedDir: null, active: null };
+  }
+  const { surfaceId } = surface;
+  const relDir = path7.posix.join(MATERIALIZED_ROOT, surfaceId);
+  const absDir = path7.join(cwd, MATERIALIZED_ROOT, surfaceId);
+  mkdirSync3(absDir, { recursive: true });
+  const excluded = excludedModulesForKind(opts.scriptKind ?? null);
+  const sources = listDts(sourceGeneratedDir).filter((file) => file !== "index.d.ts").filter((file) => !excluded.has(file.replace(/\.d\.ts$/, "")));
+  const srcDir = path7.resolve(sourceGeneratedDir, "..", "src");
+  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) => existsSync3(path7.join(srcDir, file)));
+  const coreTypesSrc = path7.join(srcDir, "core-types.ts");
+  const includeCoreTypes = overloads.length > 0 && existsSync3(coreTypesSrc);
+  const wanted = new Set(sources);
+  for (const file of overloads) {
+    wanted.add(file);
+  }
+  if (includeCoreTypes) {
+    wanted.add("core-types.d.ts");
+  }
+  for (const existing of readdirSync2(absDir)) {
+    if (existing.endsWith(".d.ts") && existing !== "index.d.ts" && !wanted.has(existing)) {
+      rmSync2(path7.join(absDir, existing));
+    }
+  }
+  for (const file of sources) {
+    writeFileSync3(path7.join(absDir, file), readFileSync6(path7.join(sourceGeneratedDir, file), "utf8"));
+  }
+  if (includeCoreTypes) {
+    writeFileSync3(path7.join(absDir, "core-types.d.ts"), readFileSync6(coreTypesSrc, "utf8"));
+  }
+  for (const file of overloads) {
+    writeFileSync3(path7.join(absDir, file), readFileSync6(path7.join(srcDir, file), "utf8"));
+  }
+  const modules = [...sources, ...overloads].map((file) => file.replace(/\.d\.ts$/, ""));
+  const imports = modules.map((mod) => `import "./${mod}";`).join(`
+`);
+  writeFileSync3(path7.join(absDir, "index.d.ts"), `${imports}
+
+export {};
+`);
+  writeJson2(path7.join(absDir, "package.json"), {
+    name: `@defold-typescript/materialized-${surfaceId}`,
+    types: "index.d.ts"
+  });
+  return { materializedDir: relDir, active: surfaceId };
+}
+function ensureGitignoreLine(cwd, line) {
+  const gitignorePath = path7.join(cwd, ".gitignore");
+  if (!existsSync3(gitignorePath)) {
+    writeFileSync3(gitignorePath, `${line}
+`);
+    return;
+  }
+  const existing = readFileSync6(gitignorePath, "utf8");
+  const present = new Set(existing.split(`
+`).map((entry) => entry.trim()));
+  if (present.has(line)) {
+    return;
+  }
+  const prefix = existing.endsWith(`
+`) || existing === "" ? "" : `
+`;
+  writeFileSync3(gitignorePath, `${existing}${prefix}${line}
+`);
+}
+function ensureMaterializedReference(cwd, materializedDir) {
+  if (materializedDir === null) {
+    return;
+  }
+  const surfaceId = path7.posix.basename(materializedDir);
+  const tsconfigPath = path7.join(cwd, "tsconfig.json");
+  if (existsSync3(tsconfigPath)) {
+    const tsconfig = JSON.parse(readFileSync6(tsconfigPath, "utf8"));
+    tsconfig.compilerOptions = {
+      ...tsconfig.compilerOptions ?? {},
+      typeRoots: [MATERIALIZED_ROOT],
+      types: [surfaceId]
+    };
+    writeJson2(tsconfigPath, tsconfig);
+  }
+  ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);
+}
+function resolveCurrentSurfaceGeneratedDir() {
+  const root = resolveTypesPackageRoot();
+  return root === null ? null : path7.join(root, "generated");
+}
+async function materializeRefDocSurface(opts) {
+  const { cwd, surfaceId, resolveOpts } = opts;
+  const root = resolveTypesPackageRoot();
+  if (root === null) {
+    return { materializedDir: null, active: null };
+  }
+  const registry = opts.registry ?? loadApiTargetsRegistry();
+  const target = registry.find((t) => t.id === surfaceId);
+  if (!target || target.source?.kind !== "ref-doc") {
+    return { materializedDir: null, active: null };
+  }
+  const excludeModules = [...excludedModulesForKind(opts.scriptKind ?? null)];
+  const relDir = path7.posix.join(MATERIALIZED_ROOT, surfaceId);
+  const absDir = path7.join(cwd, MATERIALIZED_ROOT, surfaceId);
+  try {
+    const mod = await import(path7.join(root, "scripts", "materialize-version.ts"));
+    const selfContained = { ...target, coreTypesImport: "./core-types" };
+    await mod.materializeVersionedSurface(selfContained, {
+      destDir: absDir,
+      ...resolveOpts ? { resolveOpts } : {},
+      ...excludeModules.length > 0 ? { excludeModules } : {}
+    });
+    copyFileSync(path7.join(root, "src", "core-types.ts"), path7.join(absDir, "core-types.d.ts"));
+  } catch {
+    rmSync2(absDir, { recursive: true, force: true });
+    return { materializedDir: null, active: null };
+  }
+  return { materializedDir: relDir, active: surfaceId };
+}
+
+// src/watch.ts
+import { existsSync as existsSync4, watch as fsWatch } from "node:fs";
+import * as path8 from "node:path";
+var DEFAULT_DEBOUNCE_MS = 50;
+var recursiveWatcherFactory = (srcDir, onEvent) => {
+  const w = fsWatch(srcDir, { recursive: true }, (eventType, filename) => {
+    onEvent({
+      kind: eventType === "rename" ? "rename" : "change",
+      path: filename ?? ""
+    });
+  });
+  return { close: () => w.close() };
+};
+function formatBuildLine(written) {
+  return `defold-typescript build: wrote ${written.length} files: ${written.join(", ")}
+`;
+}
+function rewrapInitError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return new Error(message.replace(/^defold-typescript build:/, "defold-typescript watch:"));
+}
+function runWatch(opts) {
+  const { cwd, stdout, stderr } = opts;
+  const debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const factory = opts.watcherFactory ?? recursiveWatcherFactory;
+  let resolveDone;
+  let rejectDone;
+  const done = new Promise((res, rej) => {
+    resolveDone = res;
+    rejectDone = rej;
+  });
+  let session;
+  try {
+    opts.syncSurface?.();
+    session = createBuildSession({ cwd });
+    const { written } = session.buildAll();
+    stdout.write(formatBuildLine(written));
+  } catch (err) {
+    rejectDone(rewrapInitError(err));
+    return {
+      stop: () => {},
+      done,
+      waitForIdle: () => Promise.resolve()
+    };
+  }
+  const srcDir = path8.join(cwd, "src");
+  let scheduled = null;
+  let syncScheduled = null;
+  let rebuildBusy = false;
+  let syncBusy = false;
+  let stopped = false;
+  let idleResolvers = [];
+  const pending = new Set;
+  function notifyIdle() {
+    if (rebuildBusy || syncBusy)
+      return;
+    const resolvers = idleResolvers;
+    idleResolvers = [];
+    for (const resolve2 of resolvers)
+      resolve2();
+  }
+  function rebuild() {
+    scheduled = null;
+    const drained = [...pending];
+    pending.clear();
+    const changed = [];
+    const removed = [];
+    for (const rel of drained) {
+      const key = `src/${toPosix(rel)}`;
+      if (existsSync4(path8.join(srcDir, rel))) {
+        changed.push(key);
+      } else {
+        removed.push(key);
+      }
+    }
+    try {
+      const { written } = session.applyEvents(changed, removed);
+      stdout.write(formatBuildLine(written));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stderr.write(`${message}
+`);
+    }
+    rebuildBusy = false;
+    notifyIdle();
+  }
+  function onEvent(e) {
+    if (stopped)
+      return;
+    rebuildBusy = true;
+    if (e.path)
+      pending.add(e.path);
+    if (scheduled)
+      clearTimeout(scheduled);
+    scheduled = setTimeout(rebuild, debounceMs);
+  }
+  const watcher = factory(srcDir, onEvent);
+  function runSync() {
+    syncScheduled = null;
+    try {
+      opts.syncSurface?.();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      stderr.write(`${message}
+`);
+    }
+    syncBusy = false;
+    notifyIdle();
+  }
+  function onComponentEvent(e) {
+    if (stopped)
+      return;
+    if (!e.path || isSkipped(e.path) || !isComponentPath(e.path))
+      return;
+    syncBusy = true;
+    if (syncScheduled)
+      clearTimeout(syncScheduled);
+    syncScheduled = setTimeout(runSync, debounceMs);
+  }
+  const componentWatcher = opts.componentWatcherFactory ? opts.componentWatcherFactory(cwd, onComponentEvent) : null;
+  function stop() {
+    if (stopped)
+      return;
+    stopped = true;
+    if (scheduled) {
+      clearTimeout(scheduled);
+      scheduled = null;
+    }
+    if (syncScheduled) {
+      clearTimeout(syncScheduled);
+      syncScheduled = null;
+    }
+    watcher.close();
+    componentWatcher?.close();
+    rebuildBusy = false;
+    syncBusy = false;
+    notifyIdle();
+    resolveDone(0);
+  }
+  function waitForIdle() {
+    if (!rebuildBusy && !syncBusy)
+      return Promise.resolve();
+    return new Promise((resolve2) => {
+      idleResolvers.push(resolve2);
+    });
+  }
+  return { stop, done, waitForIdle };
+}
+
+// src/dispatch.ts
+var USAGE = `Usage: defold-typescript <init|build|watch> [path]
+`;
+function parseDefoldVersionFlag(argv) {
+  let flag;
+  const rest = [];
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--defold-version") {
+      flag = argv[i + 1];
+      i++;
+    } else if (arg?.startsWith("--defold-version=")) {
+      flag = arg.slice("--defold-version=".length);
+    } else if (arg !== undefined) {
+      rest.push(arg);
+    }
+  }
+  return { flag, rest };
+}
+function readProjectPin(cwd) {
+  const pkgPath = path9.join(cwd, "package.json");
+  if (!existsSync5(pkgPath)) {
+    return;
+  }
+  try {
+    return readDefoldVersionPin(JSON.parse(readFileSync7(pkgPath, "utf8")));
+  } catch {
+    return;
+  }
+}
+function dispatch(argv, io, internals) {
+  const json = argv.includes("--json");
+  const force = argv.includes("--force");
+  const { flag: defoldVersionFlag, rest: nonFlagArgs } = parseDefoldVersionFlag(argv);
+  const positional = nonFlagArgs.filter((a) => a !== "--json" && a !== "--force");
+  const [command, ...rest] = positional;
+  const cwd = rest[0] ? path9.resolve(rest[0]) : process.cwd();
+  const pin = readProjectPin(cwd);
+  const resolvedVersion = resolveDefoldVersion({
+    ...defoldVersionFlag !== undefined ? { flag: defoldVersionFlag } : {},
+    ...pin !== undefined ? { pin } : {}
+  }).version;
+  const surface = selectApiSurface(resolvedVersion);
+  const apiSurface = surface.surfaceId;
+  if (command === "init") {
+    try {
+      const { written, scriptKind } = runInit({ cwd, force });
+      if (json) {
+        io.stdout.write(renderResult({
+          command: "init",
+          written,
+          defoldVersion: resolvedVersion,
+          apiSurface,
+          scriptKind
+        }));
+      } else {
+        io.stdout.write(`defold-typescript init: wrote ${written.length} files: ${written.join(", ")}
+`);
+      }
+      return 0;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (json) {
+        io.stdout.write(renderResult({ command: "init", error: message }));
+      } else {
+        io.stderr.write(`${message}
+`);
+      }
+      return 1;
+    }
+  }
+  if (command === "build") {
+    const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+    const reportBuild = (written, materializedDir) => {
+      ensureMaterializedReference(cwd, materializedDir);
+      if (json) {
+        io.stdout.write(renderResult({
+          command: "build",
+          written,
+          defoldVersion: resolvedVersion,
+          apiSurface,
+          scriptKind,
+          materializedSurface: materializedDir
+        }));
+      } else {
+        io.stdout.write(`defold-typescript build: wrote ${written.length} files: ${written.join(", ")}
+`);
+      }
+      return 0;
+    };
+    const reportError = (err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      if (json) {
+        io.stdout.write(renderResult({ command: "build", error: message }));
+      } else {
+        io.stderr.write(`${message}
+`);
+      }
+      return 1;
+    };
+    const isRefDocSurface = surface.available && surface.surfaceId !== null && surface.surfaceId !== CURRENT_STABLE_SURFACE_ID;
+    if (isRefDocSurface) {
+      const surfaceId = surface.surfaceId;
+      return (async () => {
+        try {
+          const { written } = runBuild({ cwd });
+          const { materializedDir } = await materializeRefDocSurface({
+            cwd,
+            surfaceId,
+            scriptKind,
+            ...internals?.resolveOpts ? { resolveOpts: internals.resolveOpts } : {},
+            ...internals?.refDocRegistry ? { registry: internals.refDocRegistry } : {}
+          });
+          if (!json && materializedDir === null) {
+            io.stderr.write(`defold-typescript build: could not materialize ${surfaceId}; the default surface stays active
+`);
+          }
+          return reportBuild(written, materializedDir);
+        } catch (err) {
+          return reportError(err);
+        }
+      })();
+    }
+    try {
+      const { written } = runBuild({ cwd });
+      const sourceGeneratedDir = internals?.sourceGeneratedDir ?? resolveCurrentSurfaceGeneratedDir();
+      const { materializedDir } = materializeApiSurface({
+        cwd,
+        surface,
+        sourceGeneratedDir,
+        scriptKind
+      });
+      return reportBuild(written, materializedDir);
+    } catch (err) {
+      return reportError(err);
+    }
+  }
+  if (command === "watch") {
+    const isRefDocSurface = surface.available && surface.surfaceId !== null && surface.surfaceId !== CURRENT_STABLE_SURFACE_ID;
+    let syncSurface;
+    let componentWatcherFactory;
+    if (!isRefDocSurface) {
+      const sourceGeneratedDir = internals?.sourceGeneratedDir ?? resolveCurrentSurfaceGeneratedDir();
+      syncSurface = () => {
+        const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+        const { materializedDir } = materializeApiSurface({
+          cwd,
+          surface,
+          sourceGeneratedDir,
+          scriptKind
+        });
+        ensureMaterializedReference(cwd, materializedDir);
+      };
+      componentWatcherFactory = internals ? internals.componentWatcherFactory : recursiveWatcherFactory;
+    }
+    const launchWatch = () => {
+      const watchOpts = {
+        cwd,
+        stdout: io.stdout,
+        stderr: io.stderr,
+        ...internals?.watcherFactory ? { watcherFactory: internals.watcherFactory } : {},
+        ...internals?.debounceMs !== undefined ? { debounceMs: internals.debounceMs } : {},
+        ...syncSurface ? { syncSurface } : {},
+        ...componentWatcherFactory ? { componentWatcherFactory } : {}
+      };
+      const handle = runWatch(watchOpts);
+      if (internals) {
+        internals.onWatchStart?.(handle);
+      } else {
+        process.once("SIGINT", () => handle.stop());
+      }
+      return handle.done.catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        io.stderr.write(`${message}
+`);
+        return 1;
+      });
+    };
+    if (isRefDocSurface) {
+      const surfaceId = surface.surfaceId;
+      const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+      return (async () => {
+        const { materializedDir } = await materializeRefDocSurface({
+          cwd,
+          surfaceId,
+          scriptKind,
+          ...internals?.resolveOpts ? { resolveOpts: internals.resolveOpts } : {},
+          ...internals?.refDocRegistry ? { registry: internals.refDocRegistry } : {}
+        });
+        ensureMaterializedReference(cwd, materializedDir);
+        return launchWatch();
+      })();
+    }
+    return launchWatch();
+  }
+  io.stderr.write(USAGE);
+  return 1;
+}
+export {
+  runWatch,
+  runInit,
+  dispatch,
+  createBuildSession
+};