@defold-typescript/cli 0.5.5 → 0.6.0

package/src/setup-debug.ts

@@ -0,0 +1,422 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { resolveBootPathScripts } from "./boot-path";
+import { normalizeScannedPath, scanFilesSync } from "./scan";
+import { isSkipped } from "./script-kind";
+
+// Our pinned release URL, mirrored from `docs/guide/debugging.md`. The
+// `lldebugger-url` leak guard forbids the upstream ts-defold URL, so this must
+// stay equal to the guide's snapshot URL.
+export const LLDEBUGGER_URL =
+  "https://github.com/king8fisher/defold-typescript/releases/download/lldebugger-v1/lldebugger.zip";
+
+// The prior step shipped a single skip-marker block with the `declare module`
+// inline. That form fails `tsc` under `moduleResolution: Bundler` (Bug 08), so
+// the declaration moved to an ambient `.d.ts`. The marker is kept only as the
+// legacy-detection needle for the upgrade path below.
+export const LEGACY_BOOTSTRAP_MARKER =
+  "// lldebugger-bootstrap: debug entry, inert in release builds";
+
+// The ambient `.d.ts` regenerated by `setup-debug`. `@noResolution` keeps TSTL
+// from rewriting the literal module path so the emit stays
+// `require("lldebugger.debug")`; in a `.d.ts` the declaration type-checks clean
+// (the inline form in a `.ts` did not — Bug 08).
+export const AMBIENT_DTS_REL = "src/lldebugger.debug.d.ts";
+
+export const AMBIENT_DECLARATION = `/** @noResolution */
+declare module "lldebugger.debug" {
+  export function start(): void;
+}
+`;
+
+// Managed-block sentinels. A re-run locates the single BEGIN…END pair and
+// refreshes the enclosed text if it drifted, so wording changes self-heal.
+// They are `//` line comments, stripped by TSTL, so they never reach the
+// emitted `.ts.script`.
+export const BLOCK_BEGIN = "// defold-typescript:setup-debug BEGIN — managed block, do not edit";
+export const BLOCK_END = "// defold-typescript:setup-debug END";
+
+// The canonical managed block: import + gated start, marker-free, no
+// `declare module` (that lives in the ambient `.d.ts`). Mirrors the snippet in
+// `docs/guide/debugging.md` exactly; a guide-comparison test locks the two.
+// The blank line before END keeps Biome's organizeImports assist from gluing
+// the END comment onto a following import as its leading comment (which would
+// then demand a blank line before the whole group). With blank lines on both
+// sides of END, an import injected above the user's own imports stays clean.
+const MANAGED_BLOCK = `${BLOCK_BEGIN}
+import * as lldebugger from "lldebugger.debug";
+
+if (sys.get_engine_info().is_debug) {
+  lldebugger.start();
+}
+
+${BLOCK_END}`;
+
+const FACTORY_NAMES = ["defineScript", "defineGuiScript", "defineRenderScript"] as const;
+
+const MANUAL_STEPS: readonly string[] = [
+  "Install the Local Lua Debugger extension (tomblind.local-lua-debugger-vscode) in VS Code.",
+  "Run Project -> Fetch Libraries in the Defold editor to download the lldebugger module.",
+];
+
+function isProjectHeader(line: string): boolean {
+  return line.trim() === "[project]";
+}
+
+function isSectionHeader(line: string): boolean {
+  return /^\[.+\]\s*$/.test(line.trim());
+}
+
+// Line-aware INI edit: find the max `dependencies#N` under `[project]` and
+// append `#(N+1)`; skip when the URL already appears. Deliberately no TOML/INI
+// parser — `game.project` is a flat INI the engine writes itself.
+export function addLldebuggerDependency(gameProjectText: string): string {
+  const lines = gameProjectText.split("\n");
+  if (!lines.some(isProjectHeader)) {
+    throw new Error(
+      "defold-typescript setup-debug: game.project has no [project] section; this is not a Defold project.",
+    );
+  }
+  if (gameProjectText.includes(LLDEBUGGER_URL)) {
+    return gameProjectText;
+  }
+
+  let inProject = false;
+  let maxIndex = -1;
+  let lastDepLine = -1;
+  let lastProjectLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (isSectionHeader(line)) {
+      inProject = isProjectHeader(line);
+      if (inProject) {
+        lastProjectLine = i;
+      }
+      continue;
+    }
+    if (inProject && line.trim() !== "") {
+      lastProjectLine = i;
+      const dep = line.match(/^dependencies#(\d+)\s*=/);
+      if (dep?.[1] !== undefined) {
+        const n = Number(dep[1]);
+        if (n > maxIndex) {
+          maxIndex = n;
+        }
+        lastDepLine = i;
+      }
+    }
+  }
+
+  const newLine = `dependencies#${maxIndex + 1} = ${LLDEBUGGER_URL}`;
+  const insertAt = (lastDepLine >= 0 ? lastDepLine : lastProjectLine) + 1;
+  lines.splice(insertAt, 0, newLine);
+  return lines.join("\n");
+}
+
+// The exact text the prior step prepended (snippet + its trailing newline);
+// matched verbatim so a legacy block is upgraded in place rather than stacked.
+const LEGACY_BLOCK = `${LEGACY_BOOTSTRAP_MARKER}
+/** @noResolution */
+declare module "lldebugger.debug" {
+  export function start(): void;
+}
+
+import * as lldebugger from "lldebugger.debug";
+
+if (sys.get_engine_info().is_debug) {
+  lldebugger.start();
+}
+`;
+
+export type FileAction = "injected" | "refreshed" | "unchanged" | "removed";
+
+export interface UpsertResult {
+  readonly text: string;
+  readonly action: FileAction;
+}
+
+function occurrences(haystack: string, needle: string): number {
+  return haystack.split(needle).length - 1;
+}
+
+// Locate the single managed BEGIN…END pair and act on its three states:
+// absent (inject or legacy-upgrade), canonical (no-op), drifted (splice-
+// replace). A malformed region (lone or duplicate / out-of-order sentinels)
+// is refused so the tool never deletes user code by guessing the extent.
+export function upsertManagedBlock(source: string): UpsertResult {
+  const begins = occurrences(source, BLOCK_BEGIN);
+  const ends = occurrences(source, BLOCK_END);
+
+  if (begins !== ends || begins > 1) {
+    throw new Error(
+      "defold-typescript setup-debug: malformed managed block (mismatched, duplicate, or out-of-order sentinels); refusing to edit.",
+    );
+  }
+
+  if (begins === 1) {
+    const beginAt = source.indexOf(BLOCK_BEGIN);
+    const endAt = source.indexOf(BLOCK_END);
+    if (endAt < beginAt) {
+      throw new Error(
+        "defold-typescript setup-debug: malformed managed block (END before BEGIN); refusing to edit.",
+      );
+    }
+    const regionEnd = endAt + BLOCK_END.length;
+    const region = source.slice(beginAt, regionEnd);
+    if (region === MANAGED_BLOCK) {
+      return { text: source, action: "unchanged" };
+    }
+    const text = source.slice(0, beginAt) + MANAGED_BLOCK + source.slice(regionEnd);
+    return { text, action: "refreshed" };
+  }
+
+  if (source.includes(LEGACY_BLOCK)) {
+    return { text: source.replace(LEGACY_BLOCK, `${MANAGED_BLOCK}\n`), action: "refreshed" };
+  }
+
+  return { text: `${MANAGED_BLOCK}\n\n${source}`, action: "injected" };
+}
+
+export function injectDebugBootstrap(source: string): string {
+  return upsertManagedBlock(source).text;
+}
+
+export interface StripResult {
+  readonly text: string;
+  readonly removed: boolean;
+}
+
+// Remove the single managed BEGIN…END pair (and the blank lines the inject
+// prepended) so the block survives in exactly the chosen entry script. A file
+// with no block is left untouched; a malformed region is refused, mirroring
+// `upsertManagedBlock`, so the tool never guesses the extent and deletes code.
+export function stripManagedBlock(source: string): StripResult {
+  const begins = occurrences(source, BLOCK_BEGIN);
+  const ends = occurrences(source, BLOCK_END);
+
+  if (begins === 0 && ends === 0) {
+    return { text: source, removed: false };
+  }
+  if (begins !== ends || begins > 1) {
+    throw new Error(
+      "defold-typescript setup-debug: malformed managed block (mismatched, duplicate, or out-of-order sentinels); refusing to edit.",
+    );
+  }
+
+  const beginAt = source.indexOf(BLOCK_BEGIN);
+  const endAt = source.indexOf(BLOCK_END);
+  if (endAt < beginAt) {
+    throw new Error(
+      "defold-typescript setup-debug: malformed managed block (END before BEGIN); refusing to edit.",
+    );
+  }
+  const regionEnd = endAt + BLOCK_END.length;
+  const after = source.slice(regionEnd).replace(/^\n{1,2}/, "");
+  return { text: source.slice(0, beginAt) + after, removed: true };
+}
+
+function hasFactoryCall(text: string): boolean {
+  return FACTORY_NAMES.some((name) => text.includes(`${name}(`));
+}
+
+type ProjectScanner = (cwd: string, pattern: string) => string[];
+
+export function findEntryScriptCandidates(
+  cwd: string,
+  scanner: ProjectScanner = scanFilesSync,
+): string[] {
+  const srcDir = path.join(cwd, "src");
+  if (!existsSync(srcDir)) {
+    return [];
+  }
+  return scanner(cwd, "src/**/*.ts")
+    .map(normalizeScannedPath)
+    .filter((rel) => !isSkipped(rel))
+    .filter((rel) => hasFactoryCall(readFileSync(path.join(cwd, rel), "utf8")))
+    .sort();
+}
+
+export interface SetupDebugOptions {
+  readonly cwd: string;
+  readonly script?: string;
+  readonly json?: boolean;
+  readonly chooseScript?: (candidates: string[]) => Promise<string>;
+  readonly scanFiles?: ProjectScanner;
+}
+
+export interface SetupDebugResult {
+  readonly ok: boolean;
+  readonly written: string[];
+  readonly actions: Record<string, FileAction>;
+  readonly manualSteps: readonly string[];
+  readonly error?: string;
+  readonly addedTo?: string;
+  readonly removedFrom?: string[];
+  readonly bootPath?: string[];
+}
+
+interface ResolvedTarget {
+  readonly target: string;
+  readonly bootPath: string[];
+}
+
+function failure(error: string): SetupDebugResult {
+  return { ok: false, written: [], actions: {}, manualSteps: MANUAL_STEPS, error };
+}
+
+async function defaultChooseScript(candidates: string[]): Promise<string> {
+  const { select } = await import("@inquirer/prompts");
+  return select({
+    message: "Select the entry script to receive the debugger bootstrap:",
+    choices: candidates.map((candidate) => ({ name: candidate, value: candidate })),
+  });
+}
+
+async function pickCandidate(
+  candidates: string[],
+  opts: SetupDebugOptions,
+): Promise<string | SetupDebugResult> {
+  if (candidates.length === 1) {
+    return candidates[0] as string;
+  }
+  const chooser = opts.chooseScript ?? (opts.json ? undefined : defaultChooseScript);
+  if (chooser === undefined) {
+    return failure(
+      `defold-typescript setup-debug: multiple entry scripts found (${candidates.join(", ")}); pass --script to choose one.`,
+    );
+  }
+  return chooser(candidates);
+}
+
+// Prefer a script on the Defold boot path (game.project -> collections ->
+// `.ts.script`); fall back to today's `src/` factory-call scan only when the
+// boot path reaches no script. `--script` always wins, carrying the boot-path
+// trace for the report when the named file is itself on the path.
+async function resolveTargetScript(
+  opts: SetupDebugOptions,
+): Promise<ResolvedTarget | SetupDebugResult> {
+  const { cwd } = opts;
+  const script = opts.script === undefined ? undefined : normalizeScannedPath(opts.script);
+  const bootCandidates = resolveBootPathScripts(cwd).filter((entry) =>
+    existsSync(path.join(cwd, entry.candidate)),
+  );
+
+  if (script !== undefined) {
+    if (!existsSync(path.join(cwd, script))) {
+      return failure(`defold-typescript setup-debug: script not found: ${script}`);
+    }
+    const onPath = bootCandidates.find((entry) => entry.candidate === script);
+    return { target: script, bootPath: onPath?.trace ?? [] };
+  }
+
+  if (bootCandidates.length > 0) {
+    const picked = await pickCandidate(
+      bootCandidates.map((entry) => entry.candidate),
+      opts,
+    );
+    if (typeof picked !== "string") {
+      return picked;
+    }
+    const onPath = bootCandidates.find((entry) => entry.candidate === picked);
+    return { target: picked, bootPath: onPath?.trace ?? [] };
+  }
+
+  const scanned = findEntryScriptCandidates(cwd, opts.scanFiles);
+  if (scanned.length === 0) {
+    return failure(
+      "defold-typescript setup-debug: no entry script with a lifecycle factory call found under src/.",
+    );
+  }
+  const picked = await pickCandidate(scanned, opts);
+  if (typeof picked !== "string") {
+    return picked;
+  }
+  return { target: picked, bootPath: [] };
+}
+
+export async function runSetupDebug(opts: SetupDebugOptions): Promise<SetupDebugResult> {
+  const { cwd } = opts;
+  const gameProjectPath = path.join(cwd, "game.project");
+  if (!existsSync(gameProjectPath)) {
+    return failure(
+      "defold-typescript setup-debug: no game.project here; this is not a Defold project.",
+    );
+  }
+
+  const resolved = await resolveTargetScript(opts);
+  if (!("target" in resolved)) {
+    return resolved;
+  }
+  const { target, bootPath } = resolved;
+
+  const written: string[] = [];
+  const actions: Record<string, FileAction> = {};
+
+  const dtsPath = path.join(cwd, AMBIENT_DTS_REL);
+  mkdirSync(path.dirname(dtsPath), { recursive: true });
+  const existingDts = existsSync(dtsPath) ? readFileSync(dtsPath, "utf8") : null;
+  if (existingDts === null) {
+    writeFileSync(dtsPath, AMBIENT_DECLARATION);
+    actions[AMBIENT_DTS_REL] = "injected";
+  } else if (existingDts !== AMBIENT_DECLARATION) {
+    writeFileSync(dtsPath, AMBIENT_DECLARATION);
+    actions[AMBIENT_DTS_REL] = "refreshed";
+  } else {
+    actions[AMBIENT_DTS_REL] = "unchanged";
+  }
+  written.push(AMBIENT_DTS_REL);
+
+  const scriptPath = path.join(cwd, target);
+  const source = readFileSync(scriptPath, "utf8");
+  const { text: injected, action: scriptAction } = upsertManagedBlock(source);
+  if (injected !== source) {
+    writeFileSync(scriptPath, injected);
+  }
+  actions[target] = scriptAction;
+  written.push(target);
+
+  const gameProjectText = readFileSync(gameProjectPath, "utf8");
+  const updated = addLldebuggerDependency(gameProjectText);
+  if (updated !== gameProjectText) {
+    writeFileSync(gameProjectPath, updated);
+    actions["game.project"] = "injected";
+  } else {
+    actions["game.project"] = "unchanged";
+  }
+  written.push("game.project");
+
+  // Keep the bootstrap in exactly one script: strip a stale managed block from
+  // every other `src/` script. A malformed block elsewhere is left alone (the
+  // strip refuses it) rather than aborting the wiring of the chosen target.
+  const removedFrom: string[] = [];
+  for (const scannedRel of (opts.scanFiles ?? scanFilesSync)(cwd, "src/**/*.ts")) {
+    const rel = normalizeScannedPath(scannedRel);
+    if (isSkipped(rel) || rel === target) {
+      continue;
+    }
+    const otherPath = path.join(cwd, rel);
+    const otherSource = readFileSync(otherPath, "utf8");
+    let stripped: StripResult;
+    try {
+      stripped = stripManagedBlock(otherSource);
+    } catch {
+      continue;
+    }
+    if (stripped.removed) {
+      writeFileSync(otherPath, stripped.text);
+      actions[rel] = "removed";
+      removedFrom.push(rel);
+    }
+  }
+  removedFrom.sort();
+
+  return {
+    ok: true,
+    written,
+    actions,
+    manualSteps: MANUAL_STEPS,
+    addedTo: target,
+    removedFrom,
+    bootPath,
+  };
+}

package/src/wall-interactive.ts

@@ -0,0 +1,60 @@
+import type { DirectoryWall } from "./directory-walls";
+import { groupSourceScriptKindsByDirectory } from "./directory-walls";
+import { selectScriptKind } from "./script-kind";
+import { applyWallSelection, currentWalledDirs } from "./wall";
+
+export interface WallChoice {
+  readonly value: string;
+  readonly name: string;
+  readonly checked?: boolean;
+  readonly disabled?: string | false;
+}
+
+// Injected so the dispatch route and tests can substitute a fake; the default is
+// `@inquirer/prompts`'s `checkbox`, imported lazily so the prompt module never
+// loads on the non-interactive paths.
+export type CheckboxPrompt = (opts: {
+  message: string;
+  choices: WallChoice[];
+}) => Promise<string[]>;
+
+export interface WallInteractiveDeps {
+  readonly checkbox?: CheckboxPrompt;
+}
+
+// One choice per source directory: a single-kind dir is selectable and
+// pre-checked to its current walled state; a mixed-kind dir is shown disabled
+// with its competing kinds, since no single narrowing applies.
+export function buildWallChoices(cwd: string): WallChoice[] {
+  const current = new Set(currentWalledDirs(cwd));
+  const choices: WallChoice[] = [];
+  for (const [dir, kinds] of groupSourceScriptKindsByDirectory(cwd)) {
+    const kind = selectScriptKind(kinds);
+    if (kind === null) {
+      choices.push({ value: dir, name: dir, disabled: `mixed: ${[...kinds].sort().join(", ")}` });
+    } else {
+      choices.push({ value: dir, name: `${dir} (${kind})`, checked: current.has(dir) });
+    }
+  }
+  return choices.sort((a, b) => (a.value < b.value ? -1 : a.value > b.value ? 1 : 0));
+}
+
+async function defaultCheckbox(): Promise<CheckboxPrompt> {
+  const { checkbox } = await import("@inquirer/prompts");
+  return (opts) => checkbox({ message: opts.message, choices: opts.choices });
+}
+
+// Presentation only: the checkbox selection is the desired wall set, reconciled
+// to disk through the slice E engine (check = add, uncheck = remove), so the
+// interactive and flag paths can never diverge.
+export async function runWallInteractive(
+  cwd: string,
+  deps: WallInteractiveDeps = {},
+): Promise<DirectoryWall[]> {
+  const checkbox = deps.checkbox ?? (await defaultCheckbox());
+  const selection = await checkbox({
+    message: "Select the source directories to wall (space toggles, enter confirms):",
+    choices: buildWallChoices(cwd),
+  });
+  return applyWallSelection(cwd, selection);
+}

package/src/wall.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import * as path from "node:path";
+import {
+  type DirectoryWall,
+  planSourceDirectoryWalls,
+  wireWallReferences,
+  writeDirectoryWallTsconfigs,
+} from "./directory-walls";
+
+function sortDirs<T extends { dir: string }>(items: T[]): T[] {
+  return items.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+}
+
+// The directories the root tsconfig currently walls — its managed `references`
+// set, which `wireWallReferences` keeps in lockstep with the walls on disk.
+export function currentWalledDirs(cwd: string): string[] {
+  const rootPath = path.join(cwd, "tsconfig.json");
+  if (!existsSync(rootPath)) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(rootPath, "utf8")) as {
+      references?: Array<{ path: string }>;
+    };
+    return (parsed.references ?? [])
+      .map((ref) => ref.path)
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  } catch {
+    return [];
+  }
+}
+
+// The single-kind source directories that can be walled, each with its detected
+// kind. Mixed-kind directories are absent (no single narrowing applies).
+export function eligibleWalls(cwd: string): DirectoryWall[] {
+  return planSourceDirectoryWalls(cwd);
+}
+
+// Reconcile the on-disk wall set to `desiredDirs`: write a composite tsconfig for
+// each desired wall, delete the child tsconfig of every currently-walled dir not
+// desired, and re-wire the root references/exclude/files to exactly the desired
+// set. Idempotent and total — the same engine backs `wall <dir...>`,
+// `wall --remove <dir...>`, and the interactive checkbox.
+export function applyWallSelection(cwd: string, desiredDirs: readonly string[]): DirectoryWall[] {
+  const byDir = new Map(eligibleWalls(cwd).map((wall) => [wall.dir, wall]));
+  const desired: DirectoryWall[] = [];
+  const desiredSet = new Set<string>();
+  for (const dir of desiredDirs) {
+    if (desiredSet.has(dir)) {
+      continue;
+    }
+    const wall = byDir.get(dir);
+    if (wall === undefined) {
+      throw new Error(
+        `defold-typescript wall: ${dir} is not a single-kind source directory that can be walled`,
+      );
+    }
+    desired.push(wall);
+    desiredSet.add(dir);
+  }
+
+  for (const dir of currentWalledDirs(cwd)) {
+    if (!desiredSet.has(dir)) {
+      rmSync(path.join(cwd, dir, "tsconfig.json"), { force: true });
+    }
+  }
+
+  writeDirectoryWallTsconfigs(cwd, desired);
+  wireWallReferences(cwd, desired);
+  return sortDirs(desired);
+}

package/src/watch.ts

@@ -2,6 +2,7 @@ import { existsSync, watch as fsWatch } from "node:fs";
 import * as path from "node:path";
 import { isTranspilerSource, toPosix } from "./build-output";
 import { type BuildSession, createBuildSession } from "./build-session";
+import { renderWatchEvent } from "./json-output";
 import { isComponentPath, isSkipped } from "./script-kind";
 
 export interface WatchEvent {
@@ -23,6 +24,7 @@ export interface RunWatchOptions {
   readonly watcherFactory?: WatcherFactory;
   readonly syncSurface?: () => void;
   readonly componentWatcherFactory?: WatcherFactory;
+  readonly json?: boolean;
 }
 
 export interface RunWatchHandle {
@@ -69,7 +71,9 @@ export function runWatch(opts: RunWatchOptions): RunWatchHandle {
     opts.syncSurface?.();
     session = createBuildSession({ cwd });
     const { written } = session.buildAll();
-    stdout.write(formatBuildLine(written));
+    stdout.write(
+      opts.json ? renderWatchEvent({ event: "build", written }) : formatBuildLine(written),
+    );
   } catch (err) {
     rejectDone(rewrapInitError(err));
     return {
@@ -112,10 +116,18 @@ export function runWatch(opts: RunWatchOptions): RunWatchHandle {
     }
     try {
       const { written } = session.applyEvents(changed, removed);
-      stdout.write(formatBuildLine(written));
+      stdout.write(
+        opts.json
+          ? renderWatchEvent({ event: "rebuild", written, changed, removed })
+          : formatBuildLine(written),
+      );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      stderr.write(`${message}\n`);
+      if (opts.json) {
+        stdout.write(renderWatchEvent({ event: "rebuild", error: message }));
+      } else {
+        stderr.write(`${message}\n`);
+      }
     }
     rebuildBusy = false;
     notifyIdle();