@defold-typescript/cli 0.1.0

package/dist/init.d.ts

@@ -0,0 +1,11 @@
+import { type ScriptKind } from "./script-kind";
+export interface RunInitOptions {
+    readonly cwd: string;
+    readonly force?: boolean;
+}
+export interface RunInitResult {
+    readonly written: string[];
+    readonly scriptKind: ScriptKind | null;
+}
+export declare function runNewProjectInit(cwd: string, force?: boolean): RunInitResult;
+export declare function runInit(opts: RunInitOptions): RunInitResult;

package/dist/json-output.d.ts

@@ -0,0 +1,11 @@
+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 declare function renderResult(input: RenderResultInput): string;

package/dist/materialize.d.ts

@@ -0,0 +1,29 @@
+import { type RegistryTarget } from "./api-registry";
+import type { SelectedApiSurface } from "./api-surface";
+import { type ScriptKind } from "./script-kind";
+export interface MaterializeApiSurfaceOptions {
+    readonly cwd: string;
+    readonly surface: SelectedApiSurface;
+    readonly sourceGeneratedDir: string | null;
+    readonly scriptKind?: ScriptKind | null;
+}
+export interface MaterializeApiSurfaceResult {
+    readonly materializedDir: string | null;
+    readonly active: string | null;
+}
+export declare function materializeApiSurface(opts: MaterializeApiSurfaceOptions): MaterializeApiSurfaceResult;
+export declare function ensureMaterializedReference(cwd: string, materializedDir: string | null): void;
+export declare function resolveCurrentSurfaceGeneratedDir(): string | null;
+export interface RefDocResolveOptions {
+    readonly cacheDir?: string;
+    readonly download?: (version: string) => Promise<Uint8Array>;
+    readonly readZip?: (zipPath: string) => unknown;
+}
+export interface MaterializeRefDocSurfaceOptions {
+    readonly cwd: string;
+    readonly surfaceId: string;
+    readonly resolveOpts?: RefDocResolveOptions;
+    readonly scriptKind?: ScriptKind | null;
+    readonly registry?: readonly RegistryTarget[];
+}
+export declare function materializeRefDocSurface(opts: MaterializeRefDocSurfaceOptions): Promise<MaterializeApiSurfaceResult>;

package/dist/ref-doc-test-fixture.d.ts

@@ -0,0 +1,18 @@
+import type { RegistryTarget } from "./api-registry";
+interface FakeZip {
+    has: (entry: string) => boolean;
+    read: (entry: string) => string;
+}
+export declare const noDownload: () => Promise<Uint8Array>;
+export declare function labelRefDocResolveOpts(): {
+    cacheDir: string;
+    readZip: () => FakeZip;
+    download: typeof noDownload;
+};
+export declare function multiKindRefDocResolveOpts(): {
+    cacheDir: string;
+    readZip: () => FakeZip;
+    download: typeof noDownload;
+};
+export declare function multiKindRefDocTarget(): RegistryTarget;
+export {};

package/dist/scan.d.ts

@@ -0,0 +1 @@
+export declare function scanFilesSync(cwd: string, pattern: string): string[];

package/dist/script-kind.d.ts

@@ -0,0 +1,8 @@
+export type ScriptKind = "script" | "gui-script" | "render-script";
+export declare const DEFAULT_TYPES_ENTRYPOINT = "@defold-typescript/types";
+export declare function isSkipped(relPath: string): boolean;
+export declare function isComponentPath(relPath: string): boolean;
+export declare function detectScriptKinds(cwd: string): Set<ScriptKind>;
+export declare function selectScriptKind(kinds: Set<ScriptKind>): ScriptKind | null;
+export declare function selectScriptKindEntrypoint(kinds: Set<ScriptKind>): string;
+export declare function excludedModulesForKind(kind: ScriptKind | null): Set<string>;

package/dist/watch.d.ts

@@ -0,0 +1,24 @@
+export interface WatchEvent {
+    readonly kind: "change" | "rename";
+    readonly path: string;
+}
+export interface Watcher {
+    close(): void;
+}
+export type WatcherFactory = (srcDir: string, onEvent: (e: WatchEvent) => void) => Watcher;
+export interface RunWatchOptions {
+    readonly cwd: string;
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly debounceMs?: number;
+    readonly watcherFactory?: WatcherFactory;
+    readonly syncSurface?: () => void;
+    readonly componentWatcherFactory?: WatcherFactory;
+}
+export interface RunWatchHandle {
+    readonly stop: () => void;
+    readonly done: Promise<number>;
+    readonly waitForIdle: () => Promise<void>;
+}
+export declare const recursiveWatcherFactory: WatcherFactory;
+export declare function runWatch(opts: RunWatchOptions): RunWatchHandle;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@defold-typescript/cli",
+  "version": "0.1.0",
+  "description": "End-user CLI for scaffolding and building Defold projects written in TypeScript.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "defold-typescript": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts src/bin.ts --target=node --format=esm --packages=external --outdir=dist && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@defold-typescript/transpiler": "0.1.0",
+    "@defold-typescript/types": "0.1.0"
+  }
+}

package/src/api-registry.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+
+export interface RegistryTargetSource {
+  readonly kind: string;
+  readonly version: string;
+}
+
+export interface RegistryTarget {
+  readonly id: string;
+  readonly default?: boolean;
+  readonly coreTypesImport?: string;
+  readonly source?: RegistryTargetSource | null;
+  readonly [key: string]: unknown;
+}
+
+function findPackageRoot(start: string): string | null {
+  let dir = start;
+  for (;;) {
+    if (existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+export function resolveTypesPackageRoot(): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const entry = require.resolve("@defold-typescript/types");
+    return findPackageRoot(path.dirname(entry));
+  } catch {
+    return null;
+  }
+}
+
+export function loadApiTargetsRegistry(): RegistryTarget[] {
+  const root = resolveTypesPackageRoot();
+  if (root === null) {
+    return [];
+  }
+  const registryPath = path.join(root, "api-targets.json");
+  if (!existsSync(registryPath)) {
+    return [];
+  }
+  try {
+    const { targets } = JSON.parse(readFileSync(registryPath, "utf8")) as {
+      targets: RegistryTarget[];
+    };
+    return targets;
+  } catch {
+    return [];
+  }
+}
+
+export function findRefDocTarget(version: string): RegistryTarget | undefined {
+  return loadApiTargetsRegistry().find(
+    (target) => target.source?.kind === "ref-doc" && target.source.version === version,
+  );
+}

package/src/api-surface.ts

@@ -0,0 +1,18 @@
+import { loadApiTargetsRegistry } from "./api-registry";
+import { CURRENT_STABLE_DEFOLD_VERSION } from "./defold-version";
+
+export const CURRENT_STABLE_SURFACE_ID = `defold-${CURRENT_STABLE_DEFOLD_VERSION}`;
+
+export interface SelectedApiSurface {
+  readonly surfaceId: string | null;
+  readonly available: boolean;
+}
+
+export function selectApiSurface(resolvedVersion: string): SelectedApiSurface {
+  const id = `defold-${resolvedVersion}`;
+  const target = loadApiTargetsRegistry().find((t) => t.id === id);
+  if (target) {
+    return { surfaceId: target.id, available: true };
+  }
+  return { surfaceId: null, available: false };
+}

package/src/bin.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { dispatch } from "./dispatch";
+
+const code = await dispatch(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+});
+process.exit(code);

package/src/build-output.ts

@@ -0,0 +1,106 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import type { TranspileDiagnostic } from "@defold-typescript/transpiler";
+
+export interface BuildConfig {
+  readonly outDir: string | undefined;
+  readonly include: string[];
+}
+
+interface TsConfig {
+  compilerOptions?: {
+    outDir?: string;
+  };
+  include?: string[];
+}
+
+const DEFAULT_INCLUDE = ["src/**/*.ts"];
+const PROJECT_BUCKET = "<project>";
+
+export function toPosix(p: string, sep: string = path.sep): string {
+  return p.split(sep).join("/");
+}
+
+export function readBuildConfig(cwd: string): BuildConfig {
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  let raw: string;
+  try {
+    raw = readFileSync(tsconfigPath, "utf8");
+  } catch {
+    throw new Error(
+      `defold-typescript build: no tsconfig.json at ${cwd}; run 'defold-typescript init' first.`,
+    );
+  }
+
+  const tsconfig = JSON.parse(raw) as TsConfig;
+  const outDir = tsconfig.compilerOptions?.outDir;
+  const include = tsconfig.include?.length ? tsconfig.include : DEFAULT_INCLUDE;
+  return { outDir, include };
+}
+
+function stripIncludeBase(pattern: string): string {
+  const firstWildcard = pattern.search(/[*?[]/);
+  if (firstWildcard === -1) {
+    return pattern.endsWith("/") ? pattern : `${path.posix.dirname(pattern)}/`;
+  }
+  const upToWildcard = pattern.slice(0, firstWildcard);
+  const lastSlash = upToWildcard.lastIndexOf("/");
+  return lastSlash === -1 ? "" : upToWildcard.slice(0, lastSlash + 1);
+}
+
+export function computeLuaRel(rel: string, config: BuildConfig): string {
+  const { outDir, include } = config;
+  if (outDir === undefined || outDir === "" || outDir === ".") {
+    return rel.replace(/\.ts$/, ".lua");
+  }
+  const includeBase =
+    include
+      .map(stripIncludeBase)
+      .filter((base) => rel.startsWith(base))
+      .sort((a, b) => b.length - a.length)[0] ?? "";
+  const relUnderBase = rel.slice(includeBase.length);
+  return path.posix.join(outDir, relUnderBase.replace(/\.ts$/, ".lua"));
+}
+
+export function collectFailures(
+  diagnostics: readonly TranspileDiagnostic[],
+): Map<string, string[]> {
+  const failures = new Map<string, string[]>();
+  for (const diag of diagnostics) {
+    const bucket = diag.file ?? PROJECT_BUCKET;
+    const list = failures.get(bucket);
+    if (list) {
+      list.push(diag.message);
+    } else {
+      failures.set(bucket, [diag.message]);
+    }
+  }
+  return failures;
+}
+
+export function throwIfFailures(failures: ReadonlyMap<string, string[]>): void {
+  if (failures.size === 0) {
+    return;
+  }
+  const formatted = [...failures.entries()]
+    .map(([file, messages]) => `  ${file}: ${messages.join("; ")}`)
+    .join("\n");
+  throw new Error(`defold-typescript build: ${failures.size} file(s) failed:\n${formatted}`);
+}
+
+export function writeLuaFile(
+  cwd: string,
+  luaRel: string,
+  lua: string,
+  map: string | undefined,
+): void {
+  const luaAbs = path.join(cwd, luaRel);
+  mkdirSync(path.dirname(luaAbs), { recursive: true });
+  if (map) {
+    const mapBasename = `${path.posix.basename(luaRel)}.map`;
+    writeFileSync(`${luaAbs}.map`, map);
+    writeFileSync(luaAbs, `${lua}\n--# sourceMappingURL=${mapBasename}\n`);
+  } else {
+    writeFileSync(luaAbs, lua);
+  }
+}

package/src/build-session.ts

@@ -0,0 +1,98 @@
+import { readFileSync, rmSync } from "node:fs";
+import * as path from "node:path";
+import {
+  createTranspileSession,
+  type TranspileProjectResult,
+  type TranspileSession,
+} from "@defold-typescript/transpiler";
+import {
+  type BuildConfig,
+  collectFailures,
+  computeLuaRel,
+  readBuildConfig,
+  throwIfFailures,
+  toPosix,
+  writeLuaFile,
+} from "./build-output";
+import { scanFilesSync } from "./scan";
+
+export interface CreateBuildSessionOptions {
+  readonly cwd: string;
+}
+
+export interface BuildResult {
+  readonly written: string[];
+}
+
+export interface BuildSession {
+  buildAll(): BuildResult;
+  applyEvents(changed: string[], removed: string[]): BuildResult;
+}
+
+export function createBuildSession(opts: CreateBuildSessionOptions): BuildSession {
+  const { cwd } = opts;
+  const config: BuildConfig = readBuildConfig(cwd);
+  const session: TranspileSession = createTranspileSession();
+
+  function writeOutputs(result: TranspileProjectResult, keys: readonly string[]): BuildResult {
+    const failures = collectFailures(result.diagnostics);
+    const written: string[] = [];
+    for (const rel of keys) {
+      if (failures.has(rel)) {
+        continue;
+      }
+      const lua = result.lua[rel];
+      if (lua === undefined) {
+        continue;
+      }
+      const luaRel = computeLuaRel(rel, config);
+      writeLuaFile(cwd, luaRel, lua, result.sourceMaps[rel]);
+      written.push(luaRel);
+    }
+    throwIfFailures(failures);
+    return { written };
+  }
+
+  function buildAll(): BuildResult {
+    const seen = new Set<string>();
+    for (const pattern of config.include) {
+      for (const match of scanFilesSync(cwd, pattern)) {
+        seen.add(toPosix(match));
+      }
+    }
+    const sources = [...seen].sort();
+    if (sources.length === 0) {
+      return { written: [] };
+    }
+
+    const files: Record<string, string> = {};
+    for (const rel of sources) {
+      files[rel] = readFileSync(path.join(cwd, rel), "utf8");
+    }
+
+    const result = session.update(files);
+    return writeOutputs(result, sources);
+  }
+
+  function applyEvents(changed: string[], removed: string[]): BuildResult {
+    const changes: Record<string, string | null> = {};
+    for (const rel of changed) {
+      changes[rel] = readFileSync(path.join(cwd, rel), "utf8");
+    }
+    for (const rel of removed) {
+      changes[rel] = null;
+    }
+
+    const result = session.update(changes);
+
+    for (const rel of removed) {
+      const luaAbs = path.join(cwd, computeLuaRel(rel, config));
+      rmSync(luaAbs, { force: true });
+      rmSync(`${luaAbs}.map`, { force: true });
+    }
+
+    return writeOutputs(result, changed);
+  }
+
+  return { buildAll, applyEvents };
+}

package/src/build.ts

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { transpileProject } from "@defold-typescript/transpiler";
+import {
+  collectFailures,
+  computeLuaRel,
+  readBuildConfig,
+  throwIfFailures,
+  toPosix,
+  writeLuaFile,
+} from "./build-output";
+import { scanFilesSync } from "./scan";
+
+export interface RunBuildOptions {
+  readonly cwd: string;
+}
+
+export interface RunBuildResult {
+  readonly written: string[];
+}
+
+export function runBuild(opts: RunBuildOptions): RunBuildResult {
+  const { cwd } = opts;
+  const config = readBuildConfig(cwd);
+
+  const seen = new Set<string>();
+  for (const pattern of config.include) {
+    for (const match of scanFilesSync(cwd, pattern)) {
+      seen.add(toPosix(match));
+    }
+  }
+  const sources = [...seen].sort();
+
+  if (sources.length === 0) {
+    return { written: [] };
+  }
+
+  const files: Record<string, string> = {};
+  for (const rel of sources) {
+    files[rel] = readFileSync(path.join(cwd, rel), "utf8");
+  }
+
+  const result = transpileProject({ files });
+  const failures = collectFailures(result.diagnostics);
+
+  const written: string[] = [];
+  for (const rel of sources) {
+    if (failures.has(rel)) {
+      continue;
+    }
+    const lua = result.lua[rel];
+    if (!lua) {
+      continue;
+    }
+    const luaRel = computeLuaRel(rel, config);
+    writeLuaFile(cwd, luaRel, lua, result.sourceMaps[rel]);
+    written.push(luaRel);
+  }
+
+  throwIfFailures(failures);
+  return { written };
+}

package/src/defold-version.ts

@@ -0,0 +1,30 @@
+export const CURRENT_STABLE_DEFOLD_VERSION = "1.12.4";
+
+export type DefoldVersionSource = "flag" | "pin" | "default";
+
+export interface ResolvedDefoldVersion {
+  readonly version: string;
+  readonly source: DefoldVersionSource;
+}
+
+export function readDefoldVersionPin(pkg: unknown): string | undefined {
+  if (typeof pkg !== "object" || pkg === null) {
+    return undefined;
+  }
+  const namespace = (pkg as Record<string, unknown>)["defold-typescript"];
+  if (typeof namespace !== "object" || namespace === null) {
+    return undefined;
+  }
+  const version = (namespace as Record<string, unknown>)["defold-version"];
+  return typeof version === "string" ? version : undefined;
+}
+
+export function resolveDefoldVersion(opts: { flag?: string; pin?: string }): ResolvedDefoldVersion {
+  if (opts.flag !== undefined) {
+    return { version: opts.flag, source: "flag" };
+  }
+  if (opts.pin !== undefined) {
+    return { version: opts.pin, source: "pin" };
+  }
+  return { version: CURRENT_STABLE_DEFOLD_VERSION, source: "default" };
+}