@defold-typescript/cli 0.5.1 → 0.5.3

package/README.md

@@ -4,11 +4,16 @@ The end-user CLI for scaffolding and building [Defold](https://defold.com/)
 projects written in TypeScript, transpiled to Lua.
 
 ```sh
-bunx @defold-typescript/cli init    # add TypeScript to a Defold project, or scaffold a new one
-bunx @defold-typescript/cli build   # transpile src/ to Lua alongside your Defold sources
-bunx @defold-typescript/cli watch   # rebuild on change
+bunx @defold-typescript/cli@latest init   # add TypeScript to a Defold project, or scaffold a new one
+bun install                               # install the scaffolded devDependencies (types, biome)
+bunx @defold-typescript/cli build         # transpile src/ to Lua alongside your Defold sources
+bunx @defold-typescript/cli watch         # rebuild on change
 ```
 
+Scaffold with the `@latest` tag — `init` writes your `@defold-typescript/types`
+version pin, so a stale `bunx` cache would pin an older release. Run `bun install`
+once after `init` to put the scaffolded dev dependencies on disk.
+
 The package name is scoped (`@defold-typescript/cli`); `bunx defold-typescript`
 without the scope resolves a different, nonexistent package. Install it to get
 the shorter `defold-typescript` binary on your `PATH` and pin the version:

package/dist/bin.js

@@ -231,6 +231,169 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFi
 import * as path6 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
+// src/debug-launcher.ts
+var PLATFORM_TARGETS = {
+  darwin: { enginePlatform: "x86_64-darwin", buildFolder: "x86_64-osx", executable: "dmengine" },
+  linux: { enginePlatform: "x86_64-linux", buildFolder: "x86_64-linux", executable: "dmengine" },
+  win32: {
+    enginePlatform: "x86_64-win32",
+    buildFolder: "x86_64-win32",
+    executable: "dmengine.exe"
+  }
+};
+var ENGINE_INFO_URL = "https://d.defold.com/stable/info.json";
+var ENGINE_ARCHIVE_BASE = "https://d.defold.com/archive/stable";
+var DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+function debugLaunchConfig() {
+  return {
+    name: "Defold: Debug (TypeScript)",
+    type: "lua-local",
+    request: "launch",
+    stopOnEntry: false,
+    verbose: false,
+    internalConsoleOptions: "openOnSessionStart",
+    program: { command: "bun" },
+    args: [DEBUG_LAUNCHER_REL]
+  };
+}
+var VSCODE_LAUNCH_CONTENT = {
+  version: "0.2.0",
+  configurations: [debugLaunchConfig()]
+};
+function renderDebugLauncher() {
+  const targets = JSON.stringify(PLATFORM_TARGETS, null, 2);
+  return `import { chmodSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+
+// Windows only: paths to OpenAL32.dll and wrap_oal.dll from your Defold SDK
+// (defoldsdk/ext/lib/x86_64-win32/). Leave empty on macOS/Linux.
+const WINDOWS_OPENAL32_PATH = "";
+const WINDOWS_WRAPOAL_PATH = "";
+
+interface EngineTarget {
+  enginePlatform: string;
+  buildFolder: string;
+  executable: string;
+}
+
+const PLATFORM_TARGETS: Record<string, EngineTarget> = ${targets};
+
+const ENGINE_INFO_URL = "${ENGINE_INFO_URL}";
+const ENGINE_ARCHIVE_BASE = "${ENGINE_ARCHIVE_BASE}";
+
+const target = PLATFORM_TARGETS[process.platform];
+if (!target) {
+  console.error(\`Unsupported platform: \${process.platform}\`);
+  process.exit(1);
+}
+
+const here = path.dirname(new URL(import.meta.url).pathname);
+const stockEnginePath = path.join(here, target.executable);
+
+if (!existsSync(stockEnginePath)) {
+  const info = (await (await fetch(ENGINE_INFO_URL)).json()) as { sha1: string };
+  const url = \`\${ENGINE_ARCHIVE_BASE}/\${info.sha1}/engine/\${target.enginePlatform}/\${target.executable}\`;
+  console.log(\`Fetching \${url}\`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(\`Engine download failed: \${res.status} \${res.statusText}\`);
+    process.exit(1);
+  }
+  await Bun.write(stockEnginePath, res);
+}
+
+const buildFolder = path.join("build", target.buildFolder);
+const buildEnginePath = path.join(buildFolder, target.executable);
+let enginePath = existsSync(buildEnginePath) ? buildEnginePath : stockEnginePath;
+
+if (process.platform === "win32" && enginePath === buildEnginePath) {
+  for (const [src, name] of [
+    [WINDOWS_OPENAL32_PATH, "OpenAL32.dll"],
+    [WINDOWS_WRAPOAL_PATH, "wrap_oal.dll"],
+  ] as const) {
+    const dest = path.join(buildFolder, name);
+    if (src && !existsSync(dest)) {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+// macOS: a build engine launched in place attaches to the editor process; copy
+// it aside first so it runs standalone.
+if (process.platform === "darwin" && enginePath === buildEnginePath) {
+  const tempEngine = path.join(buildFolder, "temp", target.executable);
+  mkdirSync(path.dirname(tempEngine), { recursive: true });
+  copyFileSync(buildEnginePath, tempEngine);
+  enginePath = tempEngine;
+}
+
+if (process.platform !== "win32") {
+  chmodSync(enginePath, 0o755);
+}
+
+const projectc = path.join("build", "default", "game.projectc");
+console.log(\`Launching \${enginePath} \${projectc}\`);
+const proc = Bun.spawn([enginePath, projectc], {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+process.exit(await proc.exited);
+`;
+}
+var DEBUG_LAUNCHER_SOURCE = renderDebugLauncher();
+
+// src/mise-scaffold.ts
+var MANAGED_MARKER = "# managed by @defold-typescript";
+var MISE_TASKS_TOML = `${MANAGED_MARKER}
+[tasks."defold-typescript:build"]
+description = "Build the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript build"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:watch"]
+description = "Watch and rebuild the TypeScript sources with the installed defold-typescript CLI"
+run = "bunx --no-install defold-typescript watch"
+
+${MANAGED_MARKER}
+[tasks."defold-typescript:upgrade"]
+description = "Upgrade the defold-typescript CLI to its latest release and re-pin the types dependency"
+run = ["bunx @defold-typescript/cli@latest init --force", "bun install"]
+`;
+function stripManagedBlocks(text) {
+  const lines = text.split(`
+`);
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (line.trim() === MANAGED_MARKER) {
+      i += 1;
+      while (i < lines.length && (lines[i] ?? "").trim() !== "") {
+        i += 1;
+      }
+      if (i < lines.length) {
+        i += 1;
+      }
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+  return out.join(`
+`);
+}
+function mergeMiseToml(existing) {
+  if (existing === undefined) {
+    return MISE_TASKS_TOML;
+  }
+  const userContent = stripManagedBlocks(existing).replace(/\s*$/, "");
+  if (userContent === "") {
+    return MISE_TASKS_TOML;
+  }
+  return `${userContent}
+
+${MISE_TASKS_TOML}`;
+}
+
 // src/script-kind.ts
 var DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
 var KIND_BY_EXT = {
@@ -342,12 +505,118 @@ var BIOME_JSON_CONTENT = {
   }
 };
 var VSCODE_EXTENSIONS_CONTENT = {
-  recommendations: ["sumneko.lua", "astronachos.defold"],
+  recommendations: ["sumneko.lua", "astronachos.defold", "tomblind.local-lua-debugger-vscode"],
   unwantedRecommendations: ["johnnymorganz.luau-lsp"]
 };
 var VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"]
 };
+var HOOK_COMMENTS = {
+  init: "Initialize the component and return its state.",
+  update: "Update the component every frame; `dt` is the time step.",
+  fixed_update: "Update at the fixed physics time step.",
+  late_update: "Update every frame after `update`.",
+  on_message: "Handle an incoming message.",
+  on_input: "Handle input once input focus is acquired.",
+  final: "Clean up when the component is deleted.",
+  on_reload: "React to a hot reload of this script."
+};
+var HOOK_SIGNATURES = {
+  init: "",
+  update: "self, dt",
+  fixed_update: "self, dt",
+  late_update: "self, dt",
+  on_message: "self, message_id, message, sender",
+  on_input: "self, action_id, action",
+  final: "self",
+  on_reload: "self"
+};
+var SNIPPET_HOOK_ORDER = Object.keys(HOOK_SIGNATURES);
+function hookLines(includeOnInput, startTabStop) {
+  const lines = [];
+  let tabStop = startTabStop;
+  for (const hook of SNIPPET_HOOK_ORDER) {
+    if (hook === "init") {
+      continue;
+    }
+    if (hook === "on_input" && !includeOnInput) {
+      continue;
+    }
+    lines.push(`  // ${HOOK_COMMENTS[hook]}`);
+    lines.push(`  ${hook}(${HOOK_SIGNATURES[hook]}) {$${tabStop}},`);
+    tabStop += 1;
+  }
+  return lines;
+}
+function inlineSnippetBody(factory, includeOnInput) {
+  return [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    `export const script = ${factory}({`,
+    `  // ${HOOK_COMMENTS.init}`,
+    "  init() {",
+    "    return { $0 };",
+    "  },",
+    ...hookLines(includeOnInput, 1),
+    "});"
+  ];
+}
+function typedSnippetBody(factory, includeOnInput) {
+  return [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    "type Self = {",
+    "  // Your script's state goes here.",
+    "  $1",
+    "};",
+    "",
+    `export const script = ${factory}<Self>({`,
+    `  // ${HOOK_COMMENTS.init}`,
+    "  init(): Self {",
+    "    return { $0 };",
+    "  },",
+    ...hookLines(includeOnInput, 2),
+    "});"
+  ];
+}
+var VSCODE_SNIPPETS_CONTENT = {
+  "Defold script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-script",
+    body: inlineSnippetBody("defineScript", true),
+    description: "Empty Defold script; state inferred from init's return."
+  },
+  "Defold script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-script-typed",
+    body: typedSnippetBody("defineScript", true),
+    description: "Empty Defold script with an explicit Self type."
+  },
+  "Defold GUI script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-gui",
+    body: inlineSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script; state inferred from init's return."
+  },
+  "Defold GUI script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-gui-typed",
+    body: typedSnippetBody("defineGuiScript", true),
+    description: "Empty Defold GUI script with an explicit Self type."
+  },
+  "Defold render script (inferred self)": {
+    scope: "typescript",
+    prefix: "defold-render",
+    body: inlineSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script; state inferred from init's return."
+  },
+  "Defold render script (typed self)": {
+    scope: "typescript",
+    prefix: "defold-render-typed",
+    body: typedSnippetBody("defineRenderScript", false),
+    description: "Empty Defold render script with an explicit Self type."
+  }
+};
 var MAIN_TS_CONTENT = `export function init(): void {
   const start = vmath.vector3(0, 0, 0);
   msg.post("main:/hero", "spawn", { start });
@@ -421,6 +690,12 @@ function writeBiome(cwd, written) {
   writeJson(biomePath, BIOME_JSON_CONTENT);
   written.push("biome.json");
 }
+function writeMiseTasks(cwd, written) {
+  const misePath = path6.join(cwd, "mise.toml");
+  const existing = existsSync2(misePath) ? readFileSync5(misePath, "utf8") : undefined;
+  writeFileSync2(misePath, mergeMiseToml(existing));
+  written.push("mise.toml");
+}
 function parseJsonc(text) {
   let out = "";
   let inString = false;
@@ -522,6 +797,59 @@ function writeVscodeSettings(cwd, written) {
   writeJson(filePath, VSCODE_SETTINGS_CONTENT);
   written.push(".vscode/settings.json");
 }
+function writeVscodeSnippets(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "defold-typescript.code-snippets");
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    for (const [key, snippet] of Object.entries(VSCODE_SNIPPETS_CONTENT)) {
+      if (!(key in existing)) {
+        existing[key] = snippet;
+      }
+    }
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
+  written.push(".vscode/defold-typescript.code-snippets");
+}
+function writeVscodeLaunch(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "launch.json");
+  const ours = debugLaunchConfig();
+  if (existsSync2(filePath)) {
+    const existing = readVscodeJson(filePath);
+    if (existing === null) {
+      return;
+    }
+    const configs = Array.isArray(existing.configurations) ? [...existing.configurations] : [];
+    const names = new Set(configs.map((c) => isJsonObject(c) ? c.name : undefined));
+    if (!names.has(ours.name)) {
+      configs.push(ours);
+    }
+    existing.configurations = configs;
+    existing.version ??= VSCODE_LAUNCH_CONTENT.version;
+    writeJson(filePath, existing);
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeJson(filePath, VSCODE_LAUNCH_CONTENT);
+  written.push(".vscode/launch.json");
+}
+function writeVscodeDebugLauncher(cwd, written) {
+  const dir = path6.join(cwd, ".vscode");
+  const filePath = path6.join(dir, "defold-debug.ts");
+  if (existsSync2(filePath)) {
+    return;
+  }
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync2(filePath, DEBUG_LAUNCHER_SOURCE);
+  written.push(".vscode/defold-debug.ts");
+}
 function writeTsSurface(cwd, written, force = false) {
   mkdirSync2(path6.join(cwd, "src"), { recursive: true });
   writeFileSync2(path6.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -563,8 +891,12 @@ function writeTsSurface(cwd, written, force = false) {
   writeGitignore(cwd);
   written.push(".gitignore");
   writeBiome(cwd, written);
+  writeMiseTasks(cwd, written);
   writeVscodeExtensions(cwd, written);
   writeVscodeSettings(cwd, written);
+  writeVscodeSnippets(cwd, written);
+  writeVscodeLaunch(cwd, written);
+  writeVscodeDebugLauncher(cwd, written);
   return selectScriptKind(kinds);
 }
 function runNewProjectInit(cwd, force = false) {
@@ -647,7 +979,7 @@ function materializeApiSurface(opts) {
   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 overloads = ["msg-overloads.d.ts", "message-guard.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 engineGlobalsSrc = path7.join(srcDir, "engine-globals.d.ts");
@@ -722,12 +1054,16 @@ function ensureMaterializedReference(cwd, 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);
+    const current = tsconfig.compilerOptions ?? {};
+    const alreadyRepointed = JSON.stringify(current.typeRoots) === JSON.stringify([MATERIALIZED_ROOT]) && JSON.stringify(current.types) === JSON.stringify([surfaceId]);
+    if (!alreadyRepointed) {
+      tsconfig.compilerOptions = {
+        ...current,
+        typeRoots: [MATERIALIZED_ROOT],
+        types: [surfaceId]
+      };
+      writeJson2(tsconfigPath, tsconfig);
+    }
   }
   ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);
 }

package/dist/debug-launcher.d.ts

@@ -0,0 +1,43 @@
+export interface EngineTarget {
+    readonly enginePlatform: string;
+    readonly buildFolder: string;
+    readonly executable: string;
+}
+export declare const DEBUG_LAUNCHER_REL = ".vscode/defold-debug.ts";
+export declare function targetPlatform(platform: NodeJS.Platform): EngineTarget;
+export declare function engineDownloadUrl(sha1: string, enginePlatform: string, executable: string): string;
+export interface ResolveEngineOptions {
+    readonly cwd: string;
+    readonly target: EngineTarget;
+    readonly stockPath: string;
+    readonly probe: (candidate: string) => boolean;
+}
+export declare function resolveEnginePath(opts: ResolveEngineOptions): string;
+export declare function debugLaunchConfig(): {
+    name: string;
+    type: string;
+    request: string;
+    stopOnEntry: boolean;
+    verbose: boolean;
+    internalConsoleOptions: string;
+    program: {
+        command: string;
+    };
+    args: string[];
+};
+export declare const VSCODE_LAUNCH_CONTENT: {
+    version: string;
+    configurations: {
+        name: string;
+        type: string;
+        request: string;
+        stopOnEntry: boolean;
+        verbose: boolean;
+        internalConsoleOptions: string;
+        program: {
+            command: string;
+        };
+        args: string[];
+    }[];
+};
+export declare const DEBUG_LAUNCHER_SOURCE: string;