@defold-typescript/cli 0.5.2 → 0.5.4

package/src/init.ts

@@ -1,7 +1,10 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ScriptHookName } from "@defold-typescript/types";
+import { DEBUG_LAUNCHER_SOURCE, debugLaunchConfig, VSCODE_LAUNCH_CONTENT } from "./debug-launcher";
 import { CURRENT_STABLE_DEFOLD_VERSION } from "./defold-version";
+import { mergeMiseToml } from "./mise-scaffold";
 import {
   detectScriptKinds,
   type ScriptKind,
@@ -73,7 +76,7 @@ const BIOME_JSON_CONTENT = {
 };
 
 const VSCODE_EXTENSIONS_CONTENT = {
-  recommendations: ["sumneko.lua", "astronachos.defold"],
+  recommendations: ["sumneko.lua", "astronachos.defold", "tomblind.local-lua-debugger-vscode"],
   unwantedRecommendations: ["johnnymorganz.luau-lsp"],
 };
 
@@ -88,43 +91,81 @@ interface VscodeSnippet {
   description: string;
 }
 
+// One learn-more comment and one parameter list per lifecycle hook, keyed by
+// `ScriptHookName` so a hook added to the types fails to compile here until both
+// maps gain an entry (`satisfies` exhaustiveness — the type is derived from the
+// canonical `SCRIPT_HOOK_NAMES`). The hook list is read off these keys rather
+// than imported as a runtime value: the types package is type-only and not
+// node-ESM-runnable, so the CLI bundle must not resolve it at runtime. `init` is
+// special-cased by the body builders (it carries the return placeholder, not a
+// `self` param), so its signature entry is unused but still required for
+// exhaustiveness.
+const 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.",
+} satisfies Record<ScriptHookName, string>;
+
+const 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",
+} satisfies Record<ScriptHookName, string>;
+
+const SNIPPET_HOOK_ORDER = Object.keys(HOOK_SIGNATURES) as ScriptHookName[];
+
+// Emit every hook except `init` (the caller writes it with its return
+// placeholder) as a commented `name(sig) {$N},` line. Render scripts pass
+// includeOnInput=false because `RenderScriptHooks` omits `on_input`. Tab stops
+// run sequentially from `startTabStop` across the hooks actually emitted.
+function hookLines(includeOnInput: boolean, startTabStop: number): string[] {
+  const lines: string[] = [];
+  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;
+}
+
 // Whole-file TS scaffolds mirroring the Defold editor's empty script/gui/render
 // templates over the lifecycle factories. Two self-typing variants per kind:
 // inline-self (TSelf inferred from `init`'s return) and typed-self (an explicit
 // dummy `Self` placeholder). Hook order mirrors the Lua templates; render omits
 // `on_input` because `RenderScriptHooks` does. The final `$0` lands inside `init`.
 function inlineSnippetBody(factory: string, includeOnInput: boolean): string[] {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     `export const script = ${factory}({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init() {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$1},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$2},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$3},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$4},",
+    ...hookLines(includeOnInput, 1),
+    "});",
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$5},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$6},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$7},");
-  lines.push("});");
-  return lines;
 }
 
 function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
-  const lines = [
+  return [
     `import { ${factory} } from "@defold-typescript/types";`,
     "",
     "type Self = {",
@@ -133,29 +174,13 @@ function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
     "};",
     "",
     `export const script = ${factory}<Self>({`,
-    "  // Initialize the component and return its state.",
+    `  // ${HOOK_COMMENTS.init}`,
     "  init(): Self {",
     "    return { $0 };",
     "  },",
-    "  // Update the component every frame; `dt` is the time step.",
-    "  update(self, dt) {$2},",
-    "  // Update at the fixed physics time step.",
-    "  fixed_update(self, dt) {$3},",
-    "  // Update every frame after `update`.",
-    "  late_update(self, dt) {$4},",
-    "  // Handle an incoming message.",
-    "  on_message(self, message_id, message, sender) {$5},",
+    ...hookLines(includeOnInput, 2),
+    "});",
   ];
-  if (includeOnInput) {
-    lines.push("  // Handle input once input focus is acquired.");
-    lines.push("  on_input(self, action_id, action) {$6},");
-  }
-  lines.push("  // Clean up when the component is deleted.");
-  lines.push("  final(self) {$7},");
-  lines.push("  // React to a hot reload of this script.");
-  lines.push("  on_reload(self) {$8},");
-  lines.push("});");
-  return lines;
 }
 
 const VSCODE_SNIPPETS_CONTENT: Record<string, VscodeSnippet> = {
@@ -244,27 +269,31 @@ function typesVersionSpec(): string {
   }
 }
 
-// Only @defold-typescript/types ships into the consumer (type-only, for the
-// editor). The transpiler is a dependency of the CLI itself, pulled in when the
-// user runs `build`/`watch`; the scaffold must not duplicate it. Pin types to
-// this CLI's own version so the coordinated-release set stays in lockstep.
-const SCAFFOLD_DEV_DEPS: Record<string, string> = {
+// @defold-typescript/types (type-only, for the editor) and @defold-typescript/cli
+// (the local bin the managed `bunx --no-install defold-typescript` mise tasks
+// resolve) both ship into the consumer. The transpiler must NOT be a direct
+// consumer dep — it arrives transitively through the CLI. Pin both managed deps
+// to this CLI's own version so the coordinated-release set stays in lockstep.
+export const SCAFFOLD_DEV_DEPS: Record<string, string> = {
   "@defold-typescript/types": typesVersionSpec(),
+  "@defold-typescript/cli": typesVersionSpec(),
   "@biomejs/biome": "^2.2.0",
 };
 
-// Older scaffolds wrote both managed `@defold-typescript/*` devDeps as
+// Older scaffolds wrote the managed `@defold-typescript/*` devDeps as
 // `workspace:*`, which only resolves inside this monorepo and breaks
 // `bun install` in consumers. The additive merge in `writeTsSurface` never
 // repairs an entry it didn't itself create, so repair them explicitly: the
 // transpiler is CLI-internal and must not be a consumer dep at all, and a
-// `workspace:` types pin must become a concrete published version. A concrete
-// user-chosen types pin is left alone unless `force` is set, the explicit
-// opt-in to refresh the managed pin (and only that pin) to the CLI's version.
+// `workspace:` types/cli pin must become a concrete published version. A
+// concrete user-chosen pin is left alone unless `force` is set, the explicit
+// opt-in to refresh the managed pins (and only those) to the CLI's version.
 function repairManagedDevDeps(devDeps: Record<string, string>, force = false): void {
   delete devDeps["@defold-typescript/transpiler"];
-  if (force || devDeps["@defold-typescript/types"]?.startsWith("workspace:")) {
-    devDeps["@defold-typescript/types"] = typesVersionSpec();
+  for (const name of ["@defold-typescript/types", "@defold-typescript/cli"]) {
+    if (force || devDeps[name]?.startsWith("workspace:")) {
+      devDeps[name] = typesVersionSpec();
+    }
   }
 }
 
@@ -297,6 +326,13 @@ function writeBiome(cwd: string, written: string[]): void {
   written.push("biome.json");
 }
 
+function writeMiseTasks(cwd: string, written: string[]): void {
+  const misePath = path.join(cwd, "mise.toml");
+  const existing = existsSync(misePath) ? readFileSync(misePath, "utf8") : undefined;
+  writeFileSync(misePath, mergeMiseToml(existing));
+  written.push("mise.toml");
+}
+
 // Strip `//` line comments, `/* */` block comments, and trailing commas so a
 // hand-edited JSONC `.vscode` file parses with `JSON.parse`. The walk tracks
 // string state so a `//` or comma inside a value (e.g. a URL) is preserved.
@@ -438,6 +474,41 @@ function writeVscodeSnippets(cwd: string, written: string[]): void {
   written.push(".vscode/defold-typescript.code-snippets");
 }
 
+function writeVscodeLaunch(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "launch.json");
+  const ours = debugLaunchConfig();
+  if (existsSync(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;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeJson(filePath, VSCODE_LAUNCH_CONTENT);
+  written.push(".vscode/launch.json");
+}
+
+function writeVscodeDebugLauncher(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "defold-debug.ts");
+  if (existsSync(filePath)) {
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, DEBUG_LAUNCHER_SOURCE);
+  written.push(".vscode/defold-debug.ts");
+}
+
 function writeTsSurface(cwd: string, written: string[], force = false): ScriptKind | null {
   mkdirSync(path.join(cwd, "src"), { recursive: true });
   writeFileSync(path.join(cwd, "src", "main.ts"), MAIN_TS_CONTENT);
@@ -483,10 +554,13 @@ function writeTsSurface(cwd: string, written: string[], force = false): ScriptKi
   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);
 }

package/src/materialize.ts

@@ -65,8 +65,8 @@ export function materializeApiSurface(
   // surface silently drops those globals. Skipped when the source has no
   // sibling `src/` (e.g. synthetic test fixtures).
   const srcDir = path.resolve(sourceGeneratedDir, "..", "src");
-  const overloads = ["msg-overloads.d.ts", "go-overloads.d.ts"].filter((file) =>
-    existsSync(path.join(srcDir, file)),
+  const overloads = ["msg-overloads.d.ts", "message-guard.d.ts", "go-overloads.d.ts"].filter(
+    (file) => existsSync(path.join(srcDir, file)),
   );
   const coreTypesSrc = path.join(srcDir, "core-types.ts");
   const includeCoreTypes = overloads.length > 0 && existsSync(coreTypesSrc);
@@ -148,12 +148,21 @@ export function ensureMaterializedReference(cwd: string, materializedDir: string
       compilerOptions?: Record<string, unknown>;
       [key: string]: unknown;
     };
-    tsconfig.compilerOptions = {
-      ...(tsconfig.compilerOptions ?? {}),
-      typeRoots: [MATERIALIZED_ROOT],
-      types: [surfaceId],
-    };
-    writeJson(tsconfigPath, tsconfig);
+    const current = tsconfig.compilerOptions ?? {};
+    // Skip the write when already repointed so the file keeps its existing
+    // formatting (a consumer's Biome/Prettier shape) instead of churning to
+    // JSON.stringify's layout on every build.
+    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],
+      };
+      writeJson(tsconfigPath, tsconfig);
+    }
   }
 
   ensureGitignoreLine(cwd, `${MATERIALIZED_ROOT}/`);

package/src/mise-scaffold.ts

@@ -0,0 +1,62 @@
+// The repo has no TOML parser and must not add one for three tasks, so the
+// managed block is emitted as a literal string and merged line-aware. Every
+// managed task is fronted by this marker so a re-merge can locate and refresh
+// the block without disturbing user-authored `[tools]`/`[tasks.*]` content.
+const MANAGED_MARKER = "# managed by @defold-typescript";
+
+// `bunx --no-install` resolves only the locally installed binary and never
+// fetches from the registry — that is the installed-version contract the types
+// pin upholds, while staying cross-platform (the bare `node_modules/.bin` path
+// is `.cmd`-shimmed on Windows). `:upgrade` is the deliberate `@latest` pull
+// that re-pins `@defold-typescript/types` via `init --force` + reinstall.
+export const 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"]
+`;
+
+// Drop every managed block (marker line through the next blank line or EOF),
+// leaving all other lines byte-identical, so a refresh strips the stale block
+// before the fresh one is re-appended.
+function stripManagedBlocks(text: string): string {
+  const lines = text.split("\n");
+  const out: string[] = [];
+  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("\n");
+}
+
+export function mergeMiseToml(existing?: string): string {
+  if (existing === undefined) {
+    return MISE_TASKS_TOML;
+  }
+  const userContent = stripManagedBlocks(existing).replace(/\s*$/, "");
+  if (userContent === "") {
+    return MISE_TASKS_TOML;
+  }
+  return `${userContent}\n\n${MISE_TASKS_TOML}`;
+}