typescript-sdk.dang

enum Runtime {
  NODE
  BUN
  DENO
}

type TypescriptSdk {
  let tsPattern = "\"sdk\"\\s*:\\s*\\{[^}]*\"source\"\\s*:\\s*\"typescript\""

  """
  Marker filename that skips generate when found at or above a TypeScript SDK module root.
  """
  pub skipGenerateFilename: String! = ".dagger-typescript-sdk-skip-generate"

  """
  Runtime source to write into modules created by this SDK.
  """
  pub targetRuntime: String! {
    "typescript"
  }

  """
  Return every legacy dagger.json Dagger module whose sdk.source is "typescript".
  """
  pub modules(ws: Workspace!): [Mod!]! {
    ws
      .directory("/", include: ["**/dagger.json"])
      .search(
        pattern: tsPattern,
        globs: ["**/dagger.json"],
        filesOnly: true,
        multiline: true,
        dotall: true,
      )
      .{{filePath}}
      .map { configPath =>
        mod(
          ws,
          if (configPath.filePath == "dagger.json") { "." } else { configPath.filePath.trimSuffix("/dagger.json") },
          findUp: false,
        )
      }
  }

  """
  Return the TypeScript SDK module at or above a workspace path.

  When `findUp` is true, `path` may point inside the module.
  """
  pub mod(ws: Workspace!, path: String! = ".", findUp: Boolean! = true): Mod! {
    let modPath = if (findUp) {
      let foundConfigPath = ws.findUp("dagger.json", path)
      if (foundConfigPath == null) {
        raise "no Dagger module found containing path: " + path
      } else {
        let configPath = foundConfigPath.trimPrefix("/")
        if (
          ws
            .directory("/", include: [configPath])
            .file(configPath)
            .search(
              pattern: tsPattern,
              multiline: true,
              dotall: true,
              limit: 1,
            )
            .{{id}}
            .length == 0
        ) {
          raise "Dagger module does not use the TypeScript SDK: " + path
        } else if (configPath == "dagger.json") {
          "."
        } else {
          configPath.trimSuffix("/dagger.json")
        }
      }
    } else {
      path.trimPrefix("/")
    }

    Mod(
      path: modPath,
      ws: ws,
      skipGenerateFilename: skipGenerateFilename,
    )
  }

  """
  Initialize TypeScript-owned files for a new Dagger module.

  The engine resolves the destination `path` and owns the module's
  `dagger.json`; this function only returns the SDK-owned files to layer onto
  `path` (the rendered template plus runtime-specific config).

  Pass `template` to materialize files from templates/<template>. The empty
  default uses this module's default template.

  Pass `packageManager` or `baseImage` to customize the generated config.
  Defaults leave the template unconfigured: no `packageManager` field is
  written, and no base image override is set. `packageManager` is only
  supported with `runtime = NODE`; Bun and Deno bundle their own.
  `packageManager` accepts the Node-standard `name@version` syntax (e.g.
  `pnpm@8.15.4`), or just the name if you want the engine's default version.
  """
  pub initModule(ws: Workspace!, name: String!, path: String!, template: String! = "minimal", runtime: Runtime! = Runtime.NODE, packageManager: String! = "", baseImage: String! = ""): Changeset! {
    let rawPath = path.trimPrefix("./").trimPrefix("/")
    let modPath = if (rawPath == "" or rawPath == ".") {
      "."
    } else if (rawPath == ".." or rawPath.trimPrefix("../") != rawPath) {
      raise "path escapes workspace: " + rawPath
    } else {
      rawPath.trimSuffix("/")
    }

    let fork = polyfill.workspace(ws).fork

    if (currentModule.source.exists("templates/" + template) == false) {
      raise "unknown init template: " + template
    } else if (packageManager != "" and runtime != Runtime.NODE) {
      raise "packageManager is only supported with --runtime NODE; Bun and Deno bundle their own"
    } else {
      let includePrefix = if (modPath == ".") { "" } else { modPath + "/" }
      let existing = ws.directory("/", include: [
        includePrefix + "package.json",
        includePrefix + "tsconfig.json",
        includePrefix + "deno.json",
        includePrefix + "bun.lock",
      ])

      let renderedSource = if (template == "minimal") {
        renderedDefaultTemplate(name, runtime, existing, modPath)
      } else {
        currentModule.source.directory("templates/" + template)
      }
      let templateSource = configuredTemplate(renderedSource, runtime, packageManager, baseImage)
      fork.withDirectory(modPath, templateSource).changes
    }
  }

  """
  Register a typed TypeScript client for `module` at `path`.

  The engine resolves `module`, records the client (generator + directory) in
  workspace config and the target `dagger.json`, and generates the client
  files itself. The SDK contributes no files of its own, so this returns an
  empty Changeset. `dev` selects the local development client instead of a
  pinned release.
  """
  pub initClient(ws: Workspace!, path: String!, module: String!, dev: Boolean! = false): Changeset! {
    polyfill.workspace(ws).fork.changes
  }

  """
  Return init templates tracked by this module.

  Templates live under templates/<name> and are materialized into the new
  module. Passing an empty template to init uses the module default.
  """
  pub templates: [Template!]! {
    if (currentModule.source.exists("templates")) {
      let root = currentModule.source.directory("templates")
      root.entries.map { name =>
        Template(
          name: name.trimSuffix("/"),
          source: root.directory(name),
        )
      }
    } else {
      directory.entries.map { name =>
        Template(
          name: name,
          source: directory,
        )
      }
    }
  }

  """
  Render the default TypeScript template with the requested module name and runtime.

  Seeds index.ts from the common template, then layers in runtime-specific
  config files via the config-updator helper. The config-updator reads
  existing user config files (rooted at modPath in `existing`) so any user
  customizations are preserved; only Dagger-required keys are added or
  refreshed.
  """
  let renderedDefaultTemplate(name: String!, runtime: Runtime!, existing: Directory!, modPath: String!): Directory! {
    let existingPrefix = if (modPath == ".") { "/existing/" } else { "/existing/" + modPath + "/" }
    let wsPrefix = if (modPath == ".") { "" } else { modPath + "/" }

    let builder = container
      .from("golang:1.25-alpine")
      .withoutEntrypoint
      .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
      .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
      .withDirectory("/helpers/render-template", currentModule.source.directory("helpers/render-template"))
      .withDirectory("/helpers/config-updator", currentModule.source.directory("helpers/config-updator"))
      .withDirectory("/template", currentModule.source.directory("templates/minimal"))
      .withDirectory("/existing", existing)
      .withWorkdir("/helpers/render-template")
      .withExec(["go", "build", "-o", "/usr/local/bin/render-template", "."])
      .withWorkdir("/helpers/config-updator")
      .withExec(["go", "build", "-o", "/usr/local/bin/config-updator", "."])
      .withExec(["render-template", name, "/template", "/rendered"])

    let withConfig = if (runtime == Runtime.NODE) {
      builder
        .withExec(["config-updator", "package-json", existingPrefix + "package.json", "/rendered/package.json"])
        .withExec(["config-updator", "tsconfig", existingPrefix + "tsconfig.json", "/rendered/tsconfig.json"])
    } else if (runtime == Runtime.BUN) {
      # The Dagger TypeScript runtime picks bun over node by spotting bun.lock,
      # so we emit an empty one for a fresh init. If the workspace already has
      # one we leave it alone (overlay semantics via init's withDirectory).
      let nodeConfig = builder
        .withExec(["config-updator", "package-json", existingPrefix + "package.json", "/rendered/package.json"])
        .withExec(["config-updator", "tsconfig", existingPrefix + "tsconfig.json", "/rendered/tsconfig.json"])
      if (existing.exists(wsPrefix + "bun.lock")) {
        nodeConfig
      } else {
        nodeConfig.withExec(["touch", "/rendered/bun.lock"])
      }
    } else {
      builder
        .withExec(["config-updator", "deno-config", existingPrefix + "deno.json", "/rendered/deno.json"])
    }

    withConfig.directory("/rendered")
  }

  """
  Apply non-default `packageManager` / `baseImage` flags to a rendered template.

  When both flags are empty the source is returned unchanged (no helper run,
  no reformatting). Otherwise the module-config helper edits the rendered
  config files in place: `packageManager` always writes to package.json,
  `baseImage` writes to deno.json for the DENO runtime and to package.json
  otherwise — matching where ModConfig later reads from.
  """
  let configuredTemplate(source: Directory!, runtime: Runtime!, packageManager: String!, baseImage: String!): Directory! {
    if (packageManager == "" and baseImage == "") {
      source
    } else {
      let baseImageFileName = if (runtime == Runtime.DENO) { "deno.json" } else { "package.json" }
      # Only edit config files the template actually ships. The module-config
      # helper treats a missing file as "{}" and would otherwise materialize a
      # brand-new package.json/deno.json that the template intentionally omitted.
      if (packageManager != "" and source.exists("package.json") == false) {
        raise "cannot configure --package-manager: template has no package.json"
      } else if (baseImage != "" and source.exists(baseImageFileName) == false) {
        raise "cannot configure --base-image: template has no " + baseImageFileName
      } else {
        let built = moduleConfigBuilder.withDirectory("/rendered", source)
        let withPm = if (packageManager == "") {
          built
        } else {
          built.withExec(["module-config", "set-package-manager", "/rendered/package.json", packageManager])
        }
        let withImg = if (baseImage == "") {
          withPm
        } else {
          withPm.withExec(["module-config", "set-base-image", "/rendered/" + baseImageFileName, baseImage])
        }
        withImg.directory("/rendered")
      }
    }
  }

  """
  Container with the module-config helper compiled and on PATH at
  /usr/local/bin/module-config.

  Shared by init's template configuration (configuredTemplate) and ModConfig's
  per-file edits (ModConfig.tool) so the Go build recipe lives in one place
  rather than being duplicated across both call sites.
  """
  let moduleConfigBuilder: Container! {
    container
      .from("golang:1.25-alpine")
      .withoutEntrypoint
      .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
      .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
      .withDirectory("/helper", currentModule.source.directory("helpers/module-config"))
      .withWorkdir("/helper")
      .withExec(["go", "build", "-o", "/usr/local/bin/module-config", "."])
  }

  """
  Generate all discovered legacy dagger.json TypeScript SDK modules.

  This discovery path is obsolete for workspace-managed modules; the engine
  owns the modules.<sdk>.as-sdk.modules source of truth.

  Modules with the generate skip marker are skipped.
  """
  pub generateAll(ws: Workspace!): Changeset! @generate {
    let pws = polyfill.workspace(ws)

    currentModule.asSDK.modules
      .{{path}}
      .map { m => Mod(path: m.path, ws: ws, skipGenerateFilename: skipGenerateFilename) }
      .filter { mod => mod.skipGenerate(ws) == false }
      .reduce(pws.fork) { fork, mod =>
        fork.merge(pws.moduleSource("/" + mod.path).generate)
      }
      .changes
  }
}