@defold-typescript/cli 0.5.1 → 0.5.3

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"],
 };
 
@@ -81,6 +84,144 @@ const VSCODE_SETTINGS_CONTENT = {
   "Lua.workspace.ignoreDir": ["src"],
 };
 
+interface VscodeSnippet {
+  scope: string;
+  prefix: string;
+  body: string[];
+  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[] {
+  return [
+    `import { ${factory} } from "@defold-typescript/types";`,
+    "",
+    `export const script = ${factory}({`,
+    `  // ${HOOK_COMMENTS.init}`,
+    "  init() {",
+    "    return { $0 };",
+    "  },",
+    ...hookLines(includeOnInput, 1),
+    "});",
+  ];
+}
+
+function typedSnippetBody(factory: string, includeOnInput: boolean): string[] {
+  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),
+    "});",
+  ];
+}
+
+const VSCODE_SNIPPETS_CONTENT: Record<string, VscodeSnippet> = {
+  "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.",
+  },
+};
+
 const MAIN_TS_CONTENT = `export function init(): void {
   const start = vmath.vector3(0, 0, 0);
   msg.post("main:/hero", "spawn", { start });
@@ -181,6 +322,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.
@@ -301,6 +449,62 @@ function writeVscodeSettings(cwd: string, written: string[]): void {
   written.push(".vscode/settings.json");
 }
 
+function writeVscodeSnippets(cwd: string, written: string[]): void {
+  const dir = path.join(cwd, ".vscode");
+  const filePath = path.join(dir, "defold-typescript.code-snippets");
+  if (existsSync(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;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeJson(filePath, VSCODE_SNIPPETS_CONTENT);
+  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);
@@ -346,9 +550,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}`;
+}