mod.dang

"""
A Dagger module that uses the Python SDK.
"""
type Mod {
  """
  Workspace-root-relative path of this module root.
  """
  pub rootPath: String!

  """
  The workspace this module belongs to.
  """
  let ws: Workspace!

  """
  Marker filename that skips generate when found at or above this module root.
  """
  let skipGenerateFilename: String!

  """
  Module root relative to the client's cwd.
  """
  pub path: String! {
    let cwd = ws.cwd.trimPrefix("/").trimSuffix("/")
    if (rootPath == cwd) {
      "."
    } else if (cwd == "") {
      rootPath
    } else if (rootPath.trimPrefix(cwd + "/") != rootPath) {
      rootPath.trimPrefix(cwd + "/")
    } else if (rootPath == "." or cwd.trimPrefix(rootPath + "/") != cwd) {
      let depth = if (rootPath == ".") { 0 } else { rootPath.split("/").length }
      cwd.split("/").dropFirst(depth).map { segment => ".." }.join("/")
    } else {
      rootPath
    }
  }

  """
  Whether this module or an ancestor contains the configured generate skip marker.
  """
  pub skipGenerate: Boolean! {
    ws.findUp(name: skipGenerateFilename, from: "/" + rootPath) != null
  }

  """
  Manage this module's Python build configuration (pyproject.toml).
  """
  pub config: ModConfig! {
    ModConfig(path: rootPath, ws: ws)
  }

  """
  Generate this module.
  If the generate skip marker is present, the changeset is empty.
  """
  pub generate: Changeset! {
    if (skipGenerate) {
      ws.changes(ws)
    } else {
      generated.changes(ws)
    }
  }

  """
  The workspace with this module's generated files merged in. The generate skip
  marker is not applied here; `generate` applies it.
  """
  pub generated: Workspace! {
    let files = if (isModern) {
      # Generated here: the runtime generates nothing, so the engine's
      # generated context would be empty.
      vendoredDir
    } else {
      # A pre-1.0 module is still generated by the engine's builtin Python SDK.
      ws
        .moduleSource("/" + rootPath)
        .generatedContextDirectory
        .directory(rootPath)
    }

    # Merge, don't replace: the generated context holds only generated files.
    ws.withDirectory("/" + rootPath, files)
  }

  """
  Whether this module uses the 1.0 dagger-module.toml config.
  """
  let isModern: Boolean! {
    let configPath = if (rootPath == ".") { "dagger-module.toml" } else { rootPath + "/dagger-module.toml" }
    ws.directory("/", include: [configPath]).exists(configPath)
  }

  """
  The client library with the module's bindings, in a module-rooted directory
  holding only `sdk/` so it merges onto the module without touching anything else.
  """
  let vendoredDir: Directory! {
    let schemaJSON = ws.moduleSource("/" + rootPath).introspectionSchemaJSON

    directory.withDirectory(
      vendorDirName,
      library.withFile(generatedBindingsPath, bindings(schemaJSON)),
    )
  }

  """
  Bindings generated from a module's schema, straight from the synced
  environment: `uv run --isolated` built a throwaway one per module.
  """
  let bindings(schemaJSON: File!): File! {
    codegenEnv
      .withMountedFile(schemaPath, schemaJSON)
      .withExec([
        codegenPython, "-m", "codegen", "generate", "-i", schemaPath, "-o", "/gen.py",
      ])
      .file("/gen.py")
  }

  """
  The code generator's environment, synced once per SDK version and shared by
  every module that generates.
  """
  let codegenEnv: Container! {
    codegenBase.withExec(["uv", "sync", "--frozen", "--no-dev", "--package", "codegen"])
  }

  let codegenBase: Container! {
    container
      .from(codegenImage)
      .withoutEntrypoint
      .withMountedCache("/root/.cache/uv", cacheVolume("python-sdk-uv"))
      .withEnvVariable("UV_LINK_MODE", "copy")
      .withEnvVariable("UV_COMPILE_BYTECODE", "1")
      .withDirectory("/sdk", codegenSource)
      .withWorkdir("/sdk")
  }

  let codegenPython: String! = "/sdk/.venv/bin/python"

  let codegenSource: Directory! {
    currentModule.source.directory("sdk").filter(include: [
      "pyproject.toml",
      "uv.lock",
      "src/**/*.py",
      "src/**/*.typed",
      "codegen/pyproject.toml",
      "codegen/**/*.py",
    ])
  }

  """
  What a module vendors: the importable library and its license. The generator
  runs here, never in a module, and the lock pins the generator's environment.
  """
  let library: Directory! {
    currentModule.source
      .directory("sdk")
      .filter(include: [
        "LICENSE",
        "README.md",
        "src/**/*.py",
        "src/**/*.typed",
        # An optional import that provisions an engine; a module already has one.
        "!src/dagger/provisioning/**",
      ])
      .withFile("pyproject.toml", libraryPyproject)
  }

  """
  pyproject.toml without its development sections: vendored verbatim, it names
  the absent codegen workspace member and uv refuses to install the library.
  """
  let libraryPyproject: File! {
    codegenBase
      .withFile(stripScriptPath, currentModule.source.file("helpers/vendor-pyproject/strip_dev_sections.py"))
      .withExec(["python", stripScriptPath, "pyproject.toml", "/library-pyproject.toml"])
      .file("/library-pyproject.toml")
  }

  let stripScriptPath: String! = "/strip-dev-sections.py"

  let vendorDirName: String! = "sdk"
  let generatedBindingsPath: String! = "src/dagger/client/gen.py"
  let schemaPath: String! = "/schema.json"

  # musl runs the generator ~0.3s slower than glibc, but the glibc image is
  # 25 MiB larger to pull, which costs more on the first generate.
  let codegenImage: String! = "ghcr.io/astral-sh/uv:python3.14-alpine"
}