@defold-typescript/cli 0.1.0

package/src/dispatch.ts

@@ -0,0 +1,273 @@
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { RegistryTarget } from "./api-registry";
+import { CURRENT_STABLE_SURFACE_ID, selectApiSurface } from "./api-surface";
+import { runBuild } from "./build";
+import { readDefoldVersionPin, resolveDefoldVersion } from "./defold-version";
+import { runInit } from "./init";
+import { renderResult } from "./json-output";
+import {
+  ensureMaterializedReference,
+  materializeApiSurface,
+  materializeRefDocSurface,
+  type RefDocResolveOptions,
+  resolveCurrentSurfaceGeneratedDir,
+} from "./materialize";
+import { detectScriptKinds, selectScriptKind } from "./script-kind";
+import {
+  type RunWatchHandle,
+  type RunWatchOptions,
+  recursiveWatcherFactory,
+  runWatch,
+  type WatcherFactory,
+} from "./watch";
+
+export interface DispatchIo {
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+}
+
+export interface DispatchInternals {
+  readonly watcherFactory?: WatcherFactory;
+  readonly componentWatcherFactory?: WatcherFactory;
+  readonly debounceMs?: number;
+  readonly onWatchStart?: (handle: RunWatchHandle) => void;
+  readonly sourceGeneratedDir?: string;
+  readonly resolveOpts?: RefDocResolveOptions;
+  readonly refDocRegistry?: readonly RegistryTarget[];
+}
+
+const USAGE = "Usage: defold-typescript <init|build|watch> [path]\n";
+
+function parseDefoldVersionFlag(argv: string[]): { flag: string | undefined; rest: string[] } {
+  let flag: string | undefined;
+  const rest: string[] = [];
+  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: string): string | undefined {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!existsSync(pkgPath)) {
+    return undefined;
+  }
+  try {
+    return readDefoldVersionPin(JSON.parse(readFileSync(pkgPath, "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+export function dispatch(
+  argv: string[],
+  io: DispatchIo,
+  internals?: DispatchInternals,
+): number | Promise<number> {
+  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] ? path.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(", ")}\n`,
+        );
+      }
+      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}\n`);
+      }
+      return 1;
+    }
+  }
+
+  if (command === "build") {
+    const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+    const reportBuild = (written: readonly string[], materializedDir: string | null): number => {
+      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(", ")}\n`,
+        );
+      }
+      return 0;
+    };
+    const reportError = (err: unknown): number => {
+      const message = err instanceof Error ? err.message : String(err);
+      if (json) {
+        io.stdout.write(renderResult({ command: "build", error: message }));
+      } else {
+        io.stderr.write(`${message}\n`);
+      }
+      return 1;
+    };
+
+    const isRefDocSurface =
+      surface.available &&
+      surface.surfaceId !== null &&
+      surface.surfaceId !== CURRENT_STABLE_SURFACE_ID;
+
+    if (isRefDocSurface) {
+      const surfaceId = surface.surfaceId as string;
+      return (async (): Promise<number> => {
+        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\n`,
+            );
+          }
+          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: (() => void) | undefined;
+    let componentWatcherFactory: WatcherFactory | undefined;
+    if (!isRefDocSurface) {
+      const sourceGeneratedDir =
+        internals?.sourceGeneratedDir ?? resolveCurrentSurfaceGeneratedDir();
+      syncSurface = (): void => {
+        const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+        const { materializedDir } = materializeApiSurface({
+          cwd,
+          surface,
+          sourceGeneratedDir,
+          scriptKind,
+        });
+        ensureMaterializedReference(cwd, materializedDir);
+      };
+      componentWatcherFactory = internals
+        ? internals.componentWatcherFactory
+        : recursiveWatcherFactory;
+    }
+
+    const launchWatch = (): Promise<number> => {
+      const watchOpts: RunWatchOptions = {
+        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: unknown) => {
+        const message = err instanceof Error ? err.message : String(err);
+        io.stderr.write(`${message}\n`);
+        return 1;
+      });
+    };
+
+    // A pinned ref-doc surface is generated on the fly, so it has no
+    // `syncSurface`; narrow it once at startup the same way `build` does, then
+    // start the watcher. A single detected kind drops the forbidden restricted
+    // namespaces; mixed/none keeps the full surface. Live re-narrowing of
+    // ref-doc surfaces stays deferred.
+    if (isRefDocSurface) {
+      const surfaceId = surface.surfaceId as string;
+      const scriptKind = selectScriptKind(detectScriptKinds(cwd));
+      return (async (): Promise<number> => {
+        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;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export type {
+  BuildResult,
+  BuildSession,
+  CreateBuildSessionOptions,
+} from "./build-session";
+export { createBuildSession } from "./build-session";
+export type { DispatchInternals, DispatchIo } from "./dispatch";
+export { dispatch } from "./dispatch";
+export type { RunInitOptions, RunInitResult } from "./init";
+export { runInit } from "./init";
+export type {
+  RunWatchHandle,
+  RunWatchOptions,
+  WatchEvent,
+  WatcherFactory,
+} from "./watch";
+export { runWatch } from "./watch";

package/src/init.ts

@@ -0,0 +1,237 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { CURRENT_STABLE_DEFOLD_VERSION } from "./defold-version";
+import {
+  detectScriptKinds,
+  type ScriptKind,
+  selectScriptKind,
+  selectScriptKindEntrypoint,
+} from "./script-kind";
+
+export interface RunInitOptions {
+  readonly cwd: string;
+  readonly force?: boolean;
+}
+
+export interface RunInitResult {
+  readonly written: string[];
+  readonly scriptKind: ScriptKind | null;
+}
+
+const CONFLICTING_TS_CONFIGS = [
+  "tsconfig.json",
+  "defold-typescript.config.ts",
+  "defold-typescript.config.mts",
+  "defold-typescript.config.js",
+];
+
+const TSCONFIG_COMPILER_OPTIONS = {
+  target: "ES2022",
+  module: "ESNext",
+  moduleResolution: "Bundler",
+  lib: ["ES2022"],
+  strict: true,
+  skipLibCheck: true,
+};
+
+const GITIGNORE_LINES = ["src/**/*.lua", "src/**/*.lua.map"];
+
+const 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",
+    },
+  },
+};
+
+const MAIN_TS_CONTENT = `export function init(): void {
+  const start = vmath.vector3(0, 0, 0);
+  msg.post("main:/hero", "spawn", { start });
+}
+`;
+
+const 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
+`;
+
+const 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 }
+}
+`;
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  type?: string;
+  devDependencies?: Record<string, string>;
+  "defold-typescript"?: { "defold-version"?: string };
+  [key: string]: unknown;
+}
+
+const SCAFFOLD_DEV_DEPS: Record<string, string> = {
+  "@defold-typescript/transpiler": "workspace:*",
+  "@defold-typescript/types": "workspace:*",
+  "@biomejs/biome": "^2.2.0",
+};
+
+function writeJson(filePath: string, value: unknown): void {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeGitignore(cwd: string): void {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const existing = readFileSync(gitignorePath, "utf8");
+    const present = new Set(existing.split("\n").map((line) => line.trim()));
+    const missing = GITIGNORE_LINES.filter((line) => !present.has(line));
+    if (missing.length === 0) {
+      return;
+    }
+    const prefix = existing.endsWith("\n") || existing === "" ? "" : "\n";
+    writeFileSync(gitignorePath, `${existing}${prefix}${missing.join("\n")}\n`);
+  } else {
+    writeFileSync(gitignorePath, `${GITIGNORE_LINES.join("\n")}\n`);
+  }
+}
+
+function writeBiome(cwd: string, written: string[]): void {
+  const biomePath = path.join(cwd, "biome.json");
+  if (existsSync(biomePath)) {
+    return;
+  }
+  writeJson(biomePath, BIOME_JSON_CONTENT);
+  written.push("biome.json");
+}
+
+function writeTsSurface(cwd: string, written: string[]): ScriptKind | null {
+  mkdirSync(path.join(cwd, "src"), { recursive: true });
+  writeFileSync(path.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(path.join(cwd, "tsconfig.json"), tsconfig);
+  written.push("tsconfig.json");
+
+  const pkgPath = path.join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    const existing = JSON.parse(readFileSync(pkgPath, "utf8")) as PackageJson;
+    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: PackageJson = {
+      name: path.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);
+}
+
+export function runNewProjectInit(cwd: string, force = false): RunInitResult {
+  if (!existsSync(cwd)) {
+    mkdirSync(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: string[] = [];
+
+  writeFileSync(
+    path.join(cwd, "game.project"),
+    `[project]\ntitle = ${path.basename(cwd)}\nmain_collection = /main/main.collectionc\n`,
+  );
+  written.push("game.project");
+
+  mkdirSync(path.join(cwd, "main"), { recursive: true });
+  writeFileSync(path.join(cwd, "main", "main.collection"), MAIN_COLLECTION_CONTENT);
+  written.push("main/main.collection");
+  writeFileSync(path.join(cwd, "main", "main.script"), MAIN_SCRIPT_CONTENT);
+  written.push("main/main.script");
+
+  const scriptKind = writeTsSurface(cwd, written);
+
+  return { written, scriptKind };
+}
+
+export function runInit(opts: RunInitOptions): RunInitResult {
+  const { cwd, force = false } = opts;
+
+  if (!existsSync(path.join(cwd, "game.project"))) {
+    return runNewProjectInit(cwd, force);
+  }
+
+  if (!force) {
+    for (const rel of CONFLICTING_TS_CONFIGS) {
+      if (existsSync(path.join(cwd, rel))) {
+        throw new Error(
+          `defold-typescript init: refusing to overwrite existing TS config: ${rel}. Pass --force to overwrite.`,
+        );
+      }
+    }
+  }
+
+  const written: string[] = [];
+  const scriptKind = writeTsSurface(cwd, written);
+  return { written, scriptKind };
+}

package/src/json-output.ts

@@ -0,0 +1,29 @@
+export type CliCommand = "init" | "build";
+
+export interface RenderResultInput {
+  readonly command: CliCommand;
+  readonly written?: readonly string[];
+  readonly error?: string;
+  readonly defoldVersion?: string;
+  readonly apiSurface?: string | null;
+  readonly scriptKind?: string | null;
+  readonly materializedSurface?: string | null;
+}
+
+export function renderResult(input: RenderResultInput): string {
+  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)}\n`;
+}