typescript-sdk.dang

enum Runtime {
  NODE
  BUN
  DENO
}

type TypescriptSdk {
  # Matches a legacy dagger.json declaring the TypeScript SDK, in either
  # spelling: the object form `"sdk": { "source": "typescript" }` and the older
  # bare string `"sdk": "typescript"` are both valid pre-1.0 config, and a
  # module written the second way is one this SDK owns just as much.
  let tsPattern = "\"sdk\"\\s*:\\s*(\"typescript\"|\\{[^}]*\"source\"\\s*:\\s*\"typescript\")"

  # Matches a `[runtime]` table with `source = "typescript"` in a CLI 1.0
  # dagger-module.toml. [^\[]* keeps the match inside the runtime table (it stops
  # at the next [section]).
  let tsTomlPattern = "\\[runtime\\][^\\[]*source\\s*=\\s*\"typescript\""

  """
  JavaScript runtime for the code this SDK generates: "node", "bun" or "deno".

  Empty detects it from the config files already in the scope — deno.json for
  Deno, a bun lockfile for Bun, otherwise Node — so a scope keeps the runtime it
  was created with. Setting it moves the scope to that runtime on the next
  generation.
  """
  runtime: String! = ""

  """
  Starter to materialize when a scope has no module yet: `default` for a small
  working module, `empty` for a bare @object class.
  """
  template: String! = "default"

  """Write selected Git commits as manifest pins."""
  lock: Boolean! = false

  """
  Declare a module entrypoint instead of a legacy runtime.

  Experimental, and engine-gated: only an engine carrying dagger/dagger#14038
  loads a module this way. The setting selects the whole loading path, not just
  the manifest: an entrypoint module gets an `[entrypoint]` manifest,
  entrypoint/main.dang and the __dagger.dispatch.ts that program shells out to,
  while a `[runtime]` module gets none of those and keeps the
  __dagger.entrypoint.ts its runtime execs. No module is generated with both
  halves.

  Turning it on is not free. The manifest comes out with an `[entrypoint]` table
  and no `[runtime]`, and `engineVersion`, `source` and `[[dependencies]]` are
  fields of the runtime the module no longer declares — so a module that had
  them loses them. Leave it off unless you are testing the entrypoint path.

  A scope's clients still work. With no `[[dependencies]]` to declare them in,
  the dispatcher serves them into its own session at run time instead — see
  serveBoundModules in the generated __dagger.dispatch.ts.
  """
  entrypoint: Boolean! = false

  """
  packageManager pin for package.json, as `name@version` or just `name`. Empty
  writes no field. Node only; Bun and Deno bundle their own.
  """
  packageManager: String! = ""

  """
  Base container image modules build on. Empty keeps the SDK default. Written to
  deno.json for the Deno runtime, package.json otherwise.
  """
  baseImage: String! = ""

  """
  Marker filename that stops generation for the tree it sits in.

  Found with findUp from the scope, so one file disables generation for
  everything beneath it — which is the point, and what no per-scope config
  expresses. A scope can stay recorded while `dagger generate` writes nothing into it.

  A setting, so a caller that has to generate a marked tree anyway can say so:
  empty means no marker, and the e2e checks use that to exercise generation on
  the very fixtures the marker keeps `dagger generate` out of.
  """
  skipGenerateFilename: String! = ".typescript-ignore-generate"

  """
  Files that mark a TypeScript project root, and so a scope this SDK can manage.
  """
  let scopeMarkers: [String!]! = ["package.json", "deno.json", "deno.jsonc", "tsconfig.json"]

  """
  Engine release the committed library bundle is built for.

  This SDK ships the library rather than letting the engine build it, so the
  pairing is ours to state: checks drive their harness at this release, and
  every fixture module in the repo targets it. Bumping the bundle means bumping
  this, and the fixture check fails until they agree.
  """
  targetEngineVersion: String! = "1.0.0-beta.11"

  """
  Directory holding the generated Dang entrypoint, relative to the module root.

  Outside sdk/ on purpose: that tree is mounted as the @dagger.io/dagger package,
  and a Dang program has no business inside a node package. The manifest names it
  with a leading "./" so the engine classifies it as a local path outright rather
  than falling through to a directory probe.
  """
  let dangEntrypointDir: String! = "entrypoint"

  """
  The dispatcher the engine's builtin TypeScript runtime loads.

  Only written for a module that still declares a `[runtime]`: under an
  entrypoint nothing reads it, and a stale copy left beside the real dispatcher
  is an invitation to edit the wrong file.
  """
  let legacyEntrypointFile: String! = "__dagger.entrypoint.ts"

  """
  The dispatcher a generated entrypoint shells out to: one JSON request on
  stdin, one JSON result on stdout.

  The mirror of legacyEntrypointFile, and only written for a module that
  declares an `[entrypoint]`: nothing else loads it, and a copy left behind in a
  `[runtime]` module sits beside __dagger.entrypoint.ts under a name close
  enough to invite editing the wrong one.
  """
  let dispatchFile: String! = "__dagger.dispatch.ts"

  """
  Starter used by init when none is named.
  """
  let defaultTemplate: String! = "default"

  """
  Find the TypeScript project containing the workspace cwd.

  The engine calls this to decide which scope a `dagger module client add`
  belongs to, and which SDK owns it: every installed SDK is asked, and the
  deepest answer wins. Answering null means this SDK manages nothing here, so a
  directory with no TypeScript project is left to another SDK rather than
  claimed.

  The result is workspace-root-relative and must contain the cwd; the engine
  rejects anything else.
  """
  findClientRoot(ws: Workspace!): String {
    # Deepest marker wins, regardless of which filename found it: a package.json
    # beside the cwd describes the cwd's project, an ancestor's describes the
    # monorepo above it.
    let found = scopeMarkers.reduce(null) { acc, marker =>
      let hit = ws.findUp(marker)
      if (configHitDepth(hit) > configHitDepth(acc)) { hit } else { acc }
    }

    if (found == null) { null } else { dirOf(found) }
  }

  """
  Generate every file this SDK owns in one scope.

  The engine sets the workspace cwd to the scope, hands over the scope's
  complete desired state, and diffs whatever workspace comes back — so this both
  creates a module that does not exist yet and refreshes one that does. What
  tells them apart is a module config: a scope with neither
  `dagger-module.toml` nor `dagger.json` gets the starter laid down first.

  `name` comes from the workspace config, not from the module on disk. It is the
  scope's identity, so a module is named by what the user asked for even before
  any file exists to read a name out of.
  """
  generateScope(
    ws: Workspace!,
    """
    Whether this scope holds a module, as opposed to only generated clients.
    """
    isModule: Boolean!,
    """
    The scope's recorded name. Used as the module's name when isModule.
    """
    name: String!,
    """
    Every module this scope generates a client for. The complete desired set:
    a target that has been removed is simply absent, and its files go with it.
    """
    clients: [ModuleSource!]!,
  ): Workspace! {
    let scope = scopePath(ws)

    if (hasSkipMarker(ws)) {
      # Nothing to write, and nothing to say: an unchanged workspace is an empty
      # changeset, which is what a generated-file check needs to stay green.
      ws
    } else if (isModule) {
      # One path serves init, migration and every later generation, and which
      # config the scope arrived with is what separates them: a manifest means
      # generate it as it stands, only a dagger.json means migrate it first,
      # neither means lay down the starter.
      let hasToml = hasScopeFile(ws, scope, "dagger-module.toml")
      let hasJSON = hasScopeFile(ws, scope, "dagger.json")
      # Everything below addresses the workspace from its root, and the engine
      # requires that of one thing in particular: it resolves a module's local
      # [[dependencies]] to workspace-root-relative paths and then reads them
      # relative to Workspace.cwd (ResolveDepToSource), so at the scope's own
      # cwd a dependency is looked for underneath the module that declares it.
      let rooted = ws.withWorkdir(".")
      # Seeding detects from the scope because there is no manifest yet to
      # resolve a `source` out of — and a scope with no module is its own source
      # directory anyway.
      let seeded = if (hasToml or hasJSON) {
        rooted
      } else {
        seedModule(rooted, scope, name, effectiveRuntime(rooted, scope))
      }
      # The entrypoint manifest is written on every run rather than only when the
      # scope has none: rewriting one that exists is what lets an existing module
      # be flipped onto an entrypoint by turning the setting on.
      let configured = if (entrypoint) {
        withEntrypointManifest(seeded, scope, name, hasToml)
      } else if (hasToml) {
        seeded
      } else {
        withModuleManifest(seeded, scope, name, hasJSON)
      }
      # A module's files follow its manifest's `source`, which migration can aim
      # away from the directory holding the manifest. The config the runtime is
      # detected from moves with them, so `source` has to be resolved before the
      # runtime is: a split-layout Deno module keeps its deno.json beside its
      # code, and detecting at the manifest's directory would regenerate it as
      # Node and leave it unable to resolve @dagger.io/dagger at all.
      # An entrypoint manifest has no `source` field to aim anywhere else — it
      # goes with the `[runtime]` it hangs off — so a module's files are simply
      # its scope. Asking the engine gives the wrong answer
      # rather than no answer: sourceSubpath comes back unset, moduleSourcePath
      # reads that as ".", and generation then looks for src/ at the workspace
      # root instead of inside the module.
      let source = if (entrypoint) { scope } else { moduleSourcePath(configured, scope) }
      let rt = effectiveRuntime(configured, source)
      # The same targets feed the module's runtime dependencies and its clients/
      # directory — the per-module client files its own source imports and any
      # caller outside it installs.
      let targets = clientTargets(ws, clients)
      # Before the schema is read: a target that is not a dependency yet is not
      # in the schema the bindings are generated from.
      #
      # Skipped entirely under an entrypoint, where there is no [runtime] for a
      # dependency to belong to: the builder rejects one on its own
      # ("legacy runtime is required when legacy fields are set"), so upserting
      # would not add a dependency, it would fail the generation. The
      # consequence is real and has no workaround here: a module with an
      # entrypoint cannot serve a client yet.
      let served = if (entrypoint) {
        configured
      } else {
        withClientDependencies(configured, scope, clients)
      }

      # The module's own path among the recorded clients is `dagger module
      # client add .`: the opt-in for the self client. It renders through the
      # same per-module packaging as any target, so it leaves the target set
      # here and comes back as the second pass's self.
      let selfRecorded = targets.filter { t => t.isLocal and t.path == scope }.length > 0
      let externalTargets = targets.filter { t => (t.isLocal and t.path == scope) == false }

      # First pass, staged on a workspace nothing reads back. Its only job is to
      # make the module loadable, which is what the self target needs; its
      # bindings are not the ones that belong on disk, so `served` — not this —
      # is what the result is written onto.
      let firstPass = moduleGenerated(served, scope, source, name, rt, externalTargets)
      let staged = stagedModule(served, source, firstPass)
      # Under an entrypoint the self client exists only when asked for. Since
      # the ask is explicit and the SDK owns the module's config, the dep is
      # wired too — the user runs `npm install` and calls themselves. The
      # embedded `[runtime]` layout keeps its always-generated self client, a
      # loose clients/ file reached by tsconfig alias — that path predates the
      # opt-in and stays as it was. A module that cannot load yet contributes
      # nothing; its next generation repairs it.
      let selfTargets = if (entrypoint == false or selfRecorded) { selfClientTarget(staged, scope, name) } else { [] }
      let withSelf = externalTargets + selfTargets
      let complete = moduleFiles(
        served,
        source,
        withSelfBindings(staged, scope, name, firstPass, withSelf, selfTargets, rt, existingModuleConfig(served, source)),
        # An embedded module's second pass runs whenever the staged module
        # loads, so an empty self set there means it did not — and a run that
        # could not read the module's client set has no business pruning
        # bindings it could not re-render. The entrypoint path loads through the
        # Dang literals and is never in that position.
        entrypoint or selfTargets.length > 0,
      )

      # The workspace-level .dagger/core an earlier layout shared is gone: every
      # scope carries its own clients/dagger now, so the old copy is pruned by
      # whichever scope generates first.
      let migrated = withoutLegacyWorkspaceCore(complete, configDir(ws))

      # Back to the cwd the engine set: it rejects a generateScope that returns
      # a workspace standing somewhere else.
      migrated.withWorkdir(scope)
    } else {
      # A client-only scope: clients/<module> packages under the scope, with the
      # scope's own clients/dagger beside them, wired through its package.json.
      withoutLegacyWorkspaceCore(clientScope(ws, scope, clientTargets(ws, clients)), configDir(ws))
    }
  }

  """
  Whether the generate skip marker sits at or above the scope.
  """
  let hasSkipMarker(ws: Workspace!): Boolean! {
    if (skipGenerateFilename == "") {
      false
    } else {
      ws.findUp(skipGenerateFilename) != null
    }
  }

  """
  The scope the engine is asking about, as a workspace-root-relative path.

  Every helper here addresses the workspace from its root, so the cwd the engine
  set is read once and converted, rather than threading two path conventions
  through generation.
  """
  let scopePath(ws: Workspace!): String! {
    let cwd = ws.cwd.trimPrefix("/").trimSuffix("/")
    if (cwd == "") { "." } else { cwd }
  }

  """
  Directory holding a workspace-absolute file path, "." at the root.
  """
  let dirOf(path: String!): String! {
    let dir = path.trimPrefix("/").split("/").dropLast(1).join("/")
    if (dir == "") { "." } else { dir }
  }

  """
  Join a scope-relative filename onto a workspace-root-relative scope path.
  """
  let scopeFile(scope: String!, name: String!): String! {
    if (scope == ".") { name } else { scope + "/" + name }
  }

  """
  Directory holding the workspace's dagger.toml, workspace-root-relative — "."
  when there is none. Everything this SDK shares across scopes anchors here,
  where the engine keeps .dagger/modules; found from the cwd because the config
  may sit below the workspace root, where a search from the root never looks.
  """
  let configDir(ws: Workspace!): String! {
    let found = ws.findUp("dagger.toml")
    if (found == null) { "." } else { dirOf(found) }
  }

  """
  The @dagger.io/dagger package a scope's clients/dagger holds: the shipped
  bundle plus the scope's own core bindings, completed into a real npm package.
  Every scope carries its own copy — one resolution context, one core — and
  every other package in the scope's clients/ depends on it by file:../dagger.
  It stands in for a published @dagger.io/dagger; the swap later is a specifier
  change, nothing regenerates.
  """
  let corePackage(bindings: Directory!): Directory! {
    moduleSdkDirectory(bindings).withNewFile("package.json", corePackageJSON)
  }

  """
  The core package's manifest: @dagger.io/dagger, entry at the hand-written
  index.ts (which re-exports the runtime and the generated core bindings),
  telemetry as its one sub-path. Spelled three ways because a resolver reads one
  of them — `exports` is what node honours, `main`/`types` are what a
  classic-resolution tsconfig and a publish need.
  """
  let corePackageJSON: String! {
    "{\n" +
      "  \"name\": \"@dagger.io/dagger\",\n" +
      "  \"version\": \"0.0.0\",\n" +
      "  \"type\": \"module\",\n" +
      "  \"main\": \"./index.ts\",\n" +
      "  \"types\": \"./index.ts\",\n" +
      "  \"exports\": {\n" +
      "    \".\": \"./index.ts\",\n" +
      "    \"./telemetry\": \"./telemetry.ts\"\n" +
      "  }\n" +
      "}\n"
  }

  """
  Take the workspace-level .dagger/core an earlier layout shared across scopes:
  every scope carries its own clients/dagger now. A no-op once it is gone.
  """
  let withoutLegacyWorkspaceCore(ws: Workspace!, cfg: String!): Workspace! {
    let old = scopeFile(cfg, ".dagger/core")
    if (existingDir(ws, old).entries.length == 0) {
      ws
    } else {
      ws.withoutDirectory("/" + old)
    }
  }

  """
  Depth of the directory holding a find-up config hit (a workspace-absolute path).
  A deeper hit is nearer the search origin; a null (no hit) ranks below any hit,
  so ranking by this picks the nearest enclosing config regardless of which
  filename found it.
  """
  let configHitDepth(hit: String): Int! {
    if (hit == null) {
      -1
    } else {
      let dir = hit.split("/").dropLast(1).join("/").trimPrefix("/")
      if (dir == "") { 0 } else { dir.split("/").length }
    }
  }

  """
  Whether the module config at `configPath` (workspace-root-relative) declares the
  TypeScript runtime — an `"sdk"` naming typescript in a dagger.json, or a
  `[runtime]` table with `source = "typescript"` in a dagger-module.toml. The
  filename picks which pattern to match.
  """
  let isTypescriptConfig(ws: Workspace!, configPath: String!): Boolean! {
    let pattern = if (configPath.trimSuffix("dagger-module.toml") != configPath) { tsTomlPattern } else { tsPattern }
    ws
      .directory("/", include: [configPath])
      .file(configPath)
      .search(
        pattern: pattern,
        multiline: true,
        dotall: true,
        limit: 1,
      )
      .{{id}}
      .length > 0
  }

  """
  Whether the JSON config at `configPath` (workspace-root-relative) mentions the
  named field.

  Matched as a key — `"name":` — rather than as a bare substring, so a
  dependency named "blueprint" does not read as a blueprint field.
  """
  let configDeclaresKey(ws: Workspace!, configPath: String!, key: String!): Boolean! {
    ws
      .directory("/", include: [configPath])
      .file(configPath)
      .search(
        pattern: "\"" + key + "\"\\s*:",
        multiline: true,
        dotall: true,
        limit: 1,
      )
      .{{id}}
      .length > 0
  }

  """
  Whether a scope holds the named file.
  """
  let hasScopeFile(ws: Workspace!, scope: String!, name: String!): Boolean! {
    let path = scopeFile(scope, name)
    ws.directory("/", include: [path]).exists(path)
  }

  """
  Give a scope the `dagger-module.toml` it does not have yet: a fresh manifest
  for a scope with no module, or a pre-1.0 `dagger.json` loaded, re-emitted as
  TOML and then removed.

  Migrating is the whole reason this is not folded back into seeding. Leaving
  both files behind would leave the module with two manifests free to disagree,
  and the manifest schema round-trips through the builder, so what the
  `dagger.json` carried — `source`, `include`, `[[dependencies]]`, its engine
  pin — comes out the other side. Only a scope the workspace records is ever
  generated, so migration reaches a module because someone asked for it.

  A scope that already has a manifest does not come through here at all;
  reconciling its clients into it is `withClientDependencies`, which runs for
  every module scope rather than only the ones being created.
  """
  let withModuleManifest(ws: Workspace!, scope: String!, name: String!, hasJSON: Boolean!): Workspace! {
    let configPath = scopeFile(scope, "dagger.json")
    let jsonPath = "/" + configPath

    let existing = if (hasJSON) {
      # Migration deletes the dagger.json, so anything the manifest cannot carry
      # is gone for good. The builder validates `toolchains` and `blueprint` on
      # load and then emits neither — dagger-module.toml has no table for them —
      # so migrating such a module would silently drop what it declared. Refuse
      # instead: raising writes nothing, and the dagger.json stays where it is.
      if (configDeclaresKey(ws, configPath, "toolchains")) {
        raise "cannot migrate " + configPath + " to dagger-module.toml: \"toolchains\" has no equivalent there"
      } else if (configDeclaresKey(ws, configPath, "blueprint")) {
        raise "cannot migrate " + configPath + " to dagger-module.toml: \"blueprint\" has no equivalent there"
      } else if (isTypescriptConfig(ws, configPath) == false) {
        # The builder copies whatever `sdk` says straight into `[runtime]`, so a
        # scope mistakenly recorded as TypeScript over a Go or Python module
        # would have its config rewritten, deleted, and then run through
        # TypeScript codegen.
        raise "cannot migrate " + configPath + ": it does not use the TypeScript SDK"
      }

      sdkHelpers.moduleManifest(loadJson: ws.file(jsonPath))
    } else {
      # Pin the engine version to the release this SDK's committed bundle was
      # built for, rather than letting it default to whichever engine happens to
      # be running: the generated files come from the bundle, so that is the
      # pairing the module actually has.
      sdkHelpers.moduleManifest.withLegacyTypescriptRuntime(engineVersion: "v" + targetEngineVersion)
    }

    existing.withName(name: name)
      .generate(ws.withWorkdir(scope), lock: lock, legacyJson: false)
      .withWorkdir(".")
  }

  """
  Write the manifest that selects the generated module entrypoint.

  Through the sdk-helpers builder, like every other manifest this SDK writes.
  The builder emits no `manifestVersion`, because the schema it implements has
  no such field: an `[entrypoint]` table is simply one more table a manifest may
  carry, and an engine that does not understand it reads the rest.

  The legacy fields go rather than sitting beside it, which that schema would
  allow. An entrypoint module's tree has no __dagger.entrypoint.ts, so a
  `[runtime]` left in the file would only point an older engine at a file that
  is not there — better to be unloadable than half-loadable.

  Rewriting rather than merging is what makes flipping an existing module onto
  an entrypoint work at all. It is a one-way trip: `engineVersion`, `source` and
  `[[dependencies]]` cannot outlive the `[runtime]` they hang off.
  """
  let withEntrypointManifest(ws: Workspace!, scope: String!, name: String!, hasToml: Boolean!): Workspace! {
    let existing = if (hasToml) {
      sdkHelpers.moduleManifest(loadToml: ws.file("/" + scopeFile(scope, "dagger-module.toml")))
    } else {
      sdkHelpers.moduleManifest
    }

    existing.withName(name: name)
      .withoutLegacyFields
      .withDangEntrypoint(source: "./" + dangEntrypointDir)
      .generate(ws.withWorkdir(scope), lock: lock, legacyJson: false)
      .withWorkdir(".")
  }

  """
  Record the scope's client targets as the module's runtime dependencies.

  This is what makes a client callable rather than merely typed. A module's
  session serves what its manifest lists; a scope's clients live in dagger.toml,
  which only the engine reads. Without this the bindings generate, type-check,
  and then fail at run time with `Cannot query field "<target>" on type "Query"`.

  It also has to happen before the module's schema is read, because the schema is
  what the bindings are generated from: a target that is not a dependency yet is
  not in it.

  Dependencies are upserted, never pruned. A manifest may carry entries nobody
  here put there — written by hand, or migrated from a pre-1.0 dagger.json — and
  they are indistinguishable from ours, so removing the ones that are missing
  from `clients` would take those with them. The cost is that dropping a client
  leaves its dependency behind, serving a module whose bindings are gone.
  Generation also applies the lock setting when there are no clients.

  The manifest is re-emitted every run and comes out the same nearly every time,
  so the result is kept only when it differs. Everything the builder records
  lands in that one file, which makes comparing it enough to say the run changed
  nothing — and a workspace that wrote a file is a workspace that reports it,
  identical bytes or not.
  """
  let withClientDependencies(ws: Workspace!, scope: String!, clients: [ModuleSource!]!): Workspace! {
    let tomlPath = "/" + scopeFile(scope, "dagger-module.toml")
    let updated = clients.reduce(sdkHelpers.moduleManifest(loadToml: ws.file(tomlPath))) { manifest, client =>
      manifest.withLegacyRuntimeDependency(module: client)
    }.generate(ws.withWorkdir(scope), lock: lock, legacyJson: false).withWorkdir(".")

    if (updated.file(tomlPath).digest(excludeMetadata: true) == ws.file(tomlPath).digest(excludeMetadata: true)) {
      ws
    } else {
      updated
    }
  }

  """
  The runtime a scope generates for: the `runtime` setting when set, otherwise
  whatever the files already there imply.

  Detection is the default so that adopting this SDK, or regenerating a module
  created before the setting existed, does not silently move a Bun or Deno
  project onto Node.
  """
  let effectiveRuntime(ws: Workspace!, scope: String!): Runtime! {
    if (runtime == "") {
      ModConfig(sourcePath: scope, ws: ws).runtime
    } else if (runtime == "node" or runtime == "NODE") {
      Runtime.NODE
    } else if (runtime == "bun" or runtime == "BUN") {
      Runtime.BUN
    } else if (runtime == "deno" or runtime == "DENO") {
      Runtime.DENO
    } else {
      raise "unknown runtime: \"" + runtime + "\"; expected node, bun or deno"
    }
  }

  """
  The package manager a scope's dependencies are installed with, as
  `name@version`.

  Only an entrypoint module needs this. Under a `[runtime]` the engine detects
  it and runs the install itself; under an entrypoint the generated recipe is
  ours, so the answer is baked into it at generation like every other value the
  container is built from.

  The `packageManager` setting wins where it is set, because a caller passing it
  to an existing module never reaches the package.json seeding that would
  otherwise record it.
  """
  let effectivePackageManager(ws: Workspace!, scope: String!, rt: Runtime!): String! {
    if (packageManager != "" and rt == Runtime.NODE) {
      packageManager
    } else {
      ModConfig(sourcePath: scope, ws: ws).packageManagerFor(rt)
    }
  }

  """
  Lay down the files a brand-new module needs: the rendered starter and the
  config files its runtime is detected from. The manifest that makes it a
  module is withModuleManifest's, written right after this.

  Merge, never replace. A scope is a directory the user may already work in — an
  existing package.json / tsconfig.json / deno.json keeps its scripts, path
  aliases and unstable flags, and everything else in the directory is left alone.
  """
  let seedModule(ws: Workspace!, scope: String!, name: String!, rt: Runtime!): Workspace! {
    # An empty setting means "the default", not the templates/ directory itself —
    # which exists, so it would pass the check below and render every starter as
    # a subdirectory of the new module.
    let starter = if (template == "") { defaultTemplate } else { template }

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

      let rendered = renderedTemplate(name, starter, rt, existing, scope)
      let configured = configuredTemplate(rendered, rt, packageManager, baseImage)

      ws.withDirectory("/" + scope, configured)
    }
  }

  """
  Existing contents of a workspace directory, empty when it does not exist yet.
  """
  let existingDir(ws: Workspace!, path: String!): Directory! {
    if (path == ".") {
      ws.directory("/")
    } else {
      let filtered = ws.directory("/", include: [path + "/**"])
      if (filtered.exists(path)) {
        filtered.directory(path)
      } else {
        directory
      }
    }
  }

  """
  Return init templates tracked by this module.

  Templates live under templates/<name> and are materialized into the new
  module. Init picks one by name, or the module default when none is named.
  """
  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 templates/<template> starter with the requested module name and runtime.

  Seeds index.ts from the template, then layers in runtime-specific config
  files via the config-updater helper. The config-updater 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 renderedTemplate(name: String!, template: String!, runtime: Runtime!, existing: Directory!, modPath: String!): Directory! {
    let existingPrefix = if (modPath == ".") { "/existing/" } else { "/existing/" + modPath + "/" }
    let wsPrefix = if (modPath == ".") { "" } else { modPath + "/" }

    # Two helpers in one container, layered onto the shared config-updater build
    # so it is computed once for both this and configUpdaterBuilder.
    let builder = configUpdaterBuilder
      .withDirectory("/render-template", currentModule.source.directory("helpers/render-template"))
      .withWorkdir("/render-template")
      .withExec(["go", "build", "-o", "/usr/local/bin/render-template", "."])
      .withDirectory("/template", currentModule.source.directory("templates/" + template))
      .withDirectory("/existing", existing)
      .withExec(["render-template", name, "/template", "/rendered"])

    let withConfig = if (runtime == Runtime.NODE) {
      builder
        .withExec(["config-updater", "package-json", existingPrefix + "package.json", "/rendered/package.json"])
        .withExec(["config-updater", "tsconfig", existingPrefix + "tsconfig.json", "/rendered/tsconfig.json", "", "clients"])
    } 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: init layers the template onto the existing
      # directory, so writing it here would truncate the user's lockfile.
      let nodeConfig = builder
        .withExec(["config-updater", "package-json", existingPrefix + "package.json", "/rendered/package.json"])
        .withExec(["config-updater", "tsconfig", existingPrefix + "tsconfig.json", "/rendered/tsconfig.json", "", "clients"])
      if (existing.exists(wsPrefix + "bun.lock")) {
        nodeConfig
      } else {
        nodeConfig.withExec(["touch", "/rendered/bun.lock"])
      }
    } else {
      builder
        .withExec(["config-updater", "deno-config", existingPrefix + "deno.json", "/rendered/deno.json", "", "clients"])
    }

    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 Go helper at helpers/<name> compiled and on PATH at
  /usr/local/bin/<name>.

  The helpers differ only in which directory they build, so they share one
  recipe: a copy per helper is a copy per helper of the toolchain version, the
  cache mounts and the output path, each free to drift from the others.
  """
  let goHelper(name: String!): 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/" + name))
      .withWorkdir("/helper")
      .withExec(["go", "build", "-o", "/usr/local/bin/" + name, "."])
  }

  """
  Container with the module-config helper compiled and on PATH.

  Shared by init's template configuration (configuredTemplate) and ModConfig's
  package-manager reader (ModConfig.tool).
  """
  let moduleConfigBuilder: Container! {
    goHelper("module-config")
  }

  """
  Container with the TypeScript bindings generator compiled and on PATH.
  Engine-free: it turns an introspection schema into generated bindings, either
  for a module (`codegen module`) or for a standalone client bound to one
  (`codegen client`).
  """
  let codegenBuilder: Container! {
    goHelper("codegen")
  }

  """
  Container with the config-updater helper compiled and on PATH.
  """
  let configUpdaterBuilder: Container! {
    goHelper("config-updater")
  }

  """
  The prebuilt TypeScript library this SDK ships: core.js and its declarations,
  the module-facing index.ts/telemetry.ts wrappers, the module introspector, and
  the compiler version the introspector must be run with.

  Built from the vendored library sources by .dagger/modules/packager and
  committed, so generating a module needs no bun toolchain and no network.
  """
  let tsBundle: Directory! {
    currentModule.source.directory("library/bundle")
  }

  """
  A file from the prebuilt library this SDK ships, so callers can tell what a
  generated module was built against.
  """
  libraryBundleFile(name: String!): File! {
    tsBundle.file(name)
  }

  """
  Generate a module's own bindings: client.gen.ts holding core types, one
  <module>.gen.ts client per manifest dependency and per recorded target, and
  the loader.gen.ts the entrypoints load ID-carrying values through.

  Each module's file is a self-contained client — its own root Client, its own
  dag, its own entrypoint functions — reached from the module's source through
  @dagger.io/<module>. The standalone package under `clients/` renders
  the same shape for code outside the module; what still separates the two is
  where they live and how they resolve the runtime, not what they contain.

  Engine-free: the schemas arrive as data, so this is a plain container exec.
  """
  let generateModuleBindings(schemaJSON: String!, moduleName: String!, targets: [ClientTarget!]!, repoURL: String!): Directory! {
    let base = codegenBuilder.withNewFile("/schema.json", schemaJSON)
    let withTargets = if (targets.length == 0) { base } else { stageTargets(base, targets) }

    let clientMetaArgs = if (targets.length == 0) {
      []
    } else {
      ["--client-meta-path", "/meta.json"]
    }
    # Under an entrypoint each client nests in its own package directory and the
    # loader imports it relatively; the embedded [runtime] layout keeps the flat
    # clients/<m>.gen.ts files its tsconfig aliases point at.
    let layoutArgs = if (entrypoint) { ["--packaged-clients"] } else { ["--flat-clients"] }

    withTargets
      .withExec([
        "codegen", "module",
        "--introspection-json-path", "/schema.json",
        "--module-name", moduleName,
        "--output", "/out",
        "--workspace-repo-url", repoURL,
      ] + clientMetaArgs + layoutArgs)
      .directory("/out")
  }

  """
  The Git repository the workspace itself was loaded from, or "" for a local one.

  Dagger Cloud runs checks against a workspace loaded by address
  (`github.com/org/repo@<sha>`), and the engine then loads the workspace's own
  modules as Git sources and stamps their source maps with URLs carrying that
  commit. Codegen drops those and keeps the module-relative filename, so a
  generated file reads the same whichever way the workspace was loaded — which
  is what a committed-output check needs.

  Read off any module the workspace can load at `path`; every module in a
  workspace shares its repository, so one answer serves them all. A path with no
  module, or a workspace that is not Git-backed, has nothing to strip.
  """
  let workspaceRepoURL(ws: Workspace!, path: String!): String! {
    {
      let source = ws.moduleSource("/" + path)
      if (source.kind == ModuleSourceKind.GIT_SOURCE) { source.htmlRepoURL } else { "" }
    } rescue ""
  }

  """
  The same, for a scope that may not be a module itself.

  A client-only scope has no module at its own path, so the repository is read
  off the first target that is one. Targets outside the workspace answer "" and
  are skipped — and they are the ones whose URLs must survive anyway.
  """
  let scopeRepoURL(ws: Workspace!, scope: String!, targets: [ClientTarget!]!): String! {
    let own = workspaceRepoURL(ws, scope)
    if (own != "") {
      own
    } else {
      let seed: String! = ""
      targets.reduce(seed) { found, target =>
        if (found != "") { found } else { workspaceRepoURL(ws, target.path) }
      }
    }
  }

  """
  Stage every target's schema in the codegen container, plus the meta file that
  names them. Shared by both generators: the module one folds the targets into
  the module's bindings, the client one renders the package from them.
  """
  let targetsMetaJSON(targets: [ClientTarget!]!): String! {
    let modulesJSON = targets.map { target =>
      "{\"name\":" + JSON.encode(target.name) +
      ",\"schemaPath\":" + JSON.encode(schemaPath(target.name)) +
      ",\"kind\":" + target.kindJSON +
      ",\"path\":" + JSON.encode(target.path) +
      ",\"ref\":" + JSON.encode(target.ref) +
      ",\"pin\":" + JSON.encode(target.pin) +
      ",\"self\":" + (if (target.isSelf) { "true" } else { "false" }) + "}"
    }.join(",")

    "{\"engineVersion\":" + JSON.encode(targetEngineVersion) + ",\"modules\":[" + modulesJSON + "]}"
  }

  let stageTargets(builder: Container!, targets: [ClientTarget!]!): Container! {
    targets
      .reduce(builder) { container, target =>
        container.withNewFile(schemaPath(target.name), target.schemaJSON)
      }
      .withNewFile("/meta.json", targetsMetaJSON(targets))
  }

  """
  Project the engine-resolved client targets into the pieces both generators
  read, in one pass rather than a round-trip per field per module.
  """
  let clientTargets(ws: Workspace!, clients: [ModuleSource!]!): [ClientTarget!]! {
    clients
      .{{ moduleOriginalName, kind, pin, asString, sourceRootSubpath, clientSchemaIntrospectionJSON.{{ contents }} }}
      .map { module =>
        let local = if (JSON.encode(module.kind) != "\"GIT_SOURCE\"") {
          true
        } else {
          # A Git workspace loads its own modules as Git sources, and one the
          # workspace resolves back to the same source belongs to it. Serving
          # such a target by ref would pin the generated client to the commit it
          # was generated at; by path it renders the same either way.
          {
            ws.moduleSource("/" + module.sourceRootSubpath).asString == module.asString
          } rescue false
        }

        ClientTarget(
          name: module.moduleOriginalName,
          schemaJSON: module.clientSchemaIntrospectionJSON.contents,
          kindJSON: if (local) { JSON.encode(ModuleSourceKind.LOCAL_SOURCE) } else { JSON.encode(module.kind) },
          isLocal: local,
          # Local kinds serve by resolving this against the workspace; git
          # kinds ignore it and serve from ref+pin instead.
          path: module.sourceRootSubpath,
          ref: if (local) { "" } else { module.asString },
          pin: if (local) { "" } else { module.pin },
          isSelf: false,
        )
      }
  }

  """
  Assemble a module's sdk/ directory: the shipped bundle plus the core
  bindings. Nothing module-specific: sdk/ *is* the @dagger.io/dagger library,
  and the per-module clients live in clients/, apart from it, so it can one day
  be pulled as an npm package instead of generated.

  This directory is what the engine runtime mounts as
  node_modules/@dagger.io/dagger, so its layout is the runtime's contract, not
  ours: index.ts re-exports the decorators from core.js and `export *`s
  client.gen.ts, which has to sit beside it.
  """
  let moduleSdkDirectory(bindings: Directory!): Directory! {
    # One filtered copy rather than four file reads: naming each file
    # individually is four `Directory.file` lookups and four `withFile` nodes
    # per module, for a set that is fixed and always copied together. The
    # include list is explicit so the bundle's other contents — the
    # introspector and the compiler pin, which belong to generation rather than
    # to the module — still stay out.
    #
    # Only client.gen.ts comes from the generated bindings: the module clients
    # and the loader are the caller's to place, not part of the library.
    directory
      .withDirectory(".", tsBundle, include: ["core.js", "core.d.ts", "index.ts", "telemetry.ts"])
      .withFile("client.gen.ts", bindings.file("client.gen.ts"))
  }

  """
  The embedded [runtime] layout's sdk/: the library plus every generated client
  file and the loader, flat beside client.gen.ts. sdk/ is the one directory the
  builtin runtime mounts into node_modules, so the clients must live inside it —
  the runtime cannot be told to mount anything else, which is what confines the
  packaged clients/ layout to entrypoint modules.
  """
  let embeddedSdkDirectory(bindings: Directory!): Directory! {
    directory
      .withDirectory(".", tsBundle, include: ["core.js", "core.d.ts", "index.ts", "telemetry.ts"])
      .withDirectory(".", bindings)
  }

  """
  The per-module clients an entrypoint module scope generates, apart from the
  library: one client package per dependency and per recorded target, plus the
  loader the entrypoints resolve ID-carrying values through. Codegen already
  nests them under clients/, so this is just that subdirectory.
  """
  let moduleClientsDirectory(bindings: Directory!): Directory! {
    bindings.directory("clients")
  }

  """
  Render a module's static dispatch entrypoint.

  Two steps: the introspector scans the module's own TypeScript into a typedef
  JSON, then codegen renders the dispatcher from it. The scan is the only part
  of module generation that reads the user's source rather than the schema —
  the dispatcher imports each @object class from the file it was declared in,
  which only the scan knows.

  The compiler is installed beside the introspector rather than in the module
  tree: a bare import resolves from the importing file's directory, so putting
  it next to the module would leave the scanner unable to find it.
  """
  """
  The scanner, ready to run: the introspector beside the compiler version it was
  built against.

  Nothing in here depends on the module being scanned, so it is assembled once
  rather than inside generateModuleEntrypoint. Built per module it is the same
  container described N times — N copies of the compiler pin read, the image
  pull and the `bun add` — which the engine dedupes by digest but still walks,
  and which fills the trace with N identical chains. As one node it is one span
  and one cache entry however many modules the workspace has.
  """
  let introspector: Container! {
    let tsVersion = tsBundle.file("typescript-version.txt").contents.trimSuffix("\n")

    container
      .from("oven/bun:1.3.0-alpine@sha256:37e6b1cbe053939bccf6ae4507977ed957eaa6e7f275670b72ad6348e0d2c11f")
      .withoutEntrypoint
      .withMountedCache("/root/.bun/install/cache", cacheVolume("bun-install"))
      .withWorkdir("/introspector")
      .withFile("/introspector/introspector.js", tsBundle.file("introspector.js"))
      .withExec(["bun", "add", "--no-save", "typescript@" + tsVersion])
  }

  """
  Scan the user's source into the typedef JSON every generated dispatch file is
  rendered from.

  Split out from the renderers because all three read it and the scan is the
  expensive half: one node, one cache entry, however many files come out of it.
  """
  let moduleTypedefJSON(moduleName: String!, source: Directory!, sdk: Directory!, clients: Directory!): String! {
    # The introspector resolves a dependency type a user function references
    # (e.g. returning a Hello) by name across the generated files it is handed.
    # It derives that set from the *.gen.ts siblings of client.gen.ts, so the
    # client files are staged flat beside it — packaged clients flattened out of
    # their package directories. This tree is a throwaway; only typedef.json is
    # read back.
    let staged = if (entrypoint) {
      packagedClientNames(clients).reduce(sdk) { acc, name =>
        acc.withFile(name + ".gen.ts", clients.file(name + "/" + name + ".gen.ts"))
      }
    } else {
      # The embedded sdk/ already carries the client files flat.
      sdk
    }

    introspector
      .withWorkdir("/work")
      .withDirectory("/work/src", source)
      .withDirectory("/work/sdk", staged)
      .withEnvVariable("EMIT_TYPEDEF_JSON_FILE", "/work/typedef.json")
      .withExec(["bun", "/introspector/introspector.js", moduleName, "src", "sdk/client.gen.ts"])
      .file("/work/typedef.json")
      .contents
  }

  let entrypointCodegen(typedef: String!): Container! {
    codegenBuilder.withNewFile("/typedef.json", typedef)
  }

  let generateModuleEntrypoint(typedef: String!): File! {
    # The embedded layout ships the loader inside sdk/, beside the clients the
    # runtime mounts with it, so the entrypoint imports it from there.
    entrypointCodegen(typedef)
      .withExec([
        "codegen", "entrypoint",
        "--typedef-json-path", "/typedef.json",
        "--output", "/out",
        "--module-root", "/work",
        "--source-dir", "src",
        "--loader-import", "sdk/loader.gen.js",
      ])
      .file("/out/__dagger.entrypoint.ts")
  }

  """
  The manifest-v2 dispatcher: one JSON request on stdin, one JSON result on
  stdout, and no register().

  Written only for a module that declares an `[entrypoint]`, in place of the
  __dagger.entrypoint.ts the builtin runtime execs — the two are the same half
  of two different loading paths, and a module is on one of them.
  """
  let generateModuleDispatcher(typedef: String!): File! {
    # The dispatcher serves nothing: each generated client serves its own module
    # before the first query that reaches it — a `dag.<module>()` call through
    # the client's served context, or a received value loaded through the loader,
    # which sits under clients/ beside the packages it imports.
    entrypointCodegen(typedef)
      .withExec([
        "codegen", "entrypoint", "--dispatch",
        "--typedef-json-path", "/typedef.json",
        "--output", "/out",
        "--module-root", "/work",
        "--source-dir", "src",
      ])
      .file("/out/" + dispatchFile)
  }

  """
  The Dang program an engine loads under a manifest `[entrypoint]` table: the
  module's typedefs as literals, plus the container recipe that runs a call.

  `sourcePath` is baked into that recipe as the container workdir. It cannot be
  read at call time: the entrypoint is handed the *caller's* workspace, whose cwd
  is wherever the caller happened to be. `pkgManager` is baked the same way, and
  for the same reason the engine's builtin runtime detects one: the module's
  dependencies have to be installed before a call can run, and nothing else
  installs them under an entrypoint.
  """
  let generateDangEntrypoint(
    typedef: String!,
    moduleName: String!,
    sourcePath: String!,
    rt: Runtime!,
    pkgManager: String!,
  ): File! {
    entrypointCodegen(typedef)
      .withExec([
        "codegen", "dang-entrypoint",
        "--typedef-json-path", "/typedef.json",
        "--output", "/out",
        "--module-name", moduleName,
        "--runtime", runtimeName(rt),
        "--module-path", sourcePath,
        "--package-manager", pkgManager,
      ])
      .file("/out/entrypoint/main.dang")
  }

  """
  The runtime's name as the codegen CLI spells it.
  """
  let runtimeName(rt: Runtime!): String! {
    if (rt == Runtime.BUN) {
      "bun"
    } else if (rt == Runtime.DENO) {
      "deno"
    } else {
      "node"
    }
  }

  """
  Build the complete set of generated files for a module: its sdk/ library, its
  clients/, the file a call is dispatched into it through, and the config the
  runtime reads.

  `existing` supplies the module's current config files so user settings
  survive; `runtime` selects which config files are written. The result is
  rooted at the module's source directory.

  Which dispatch file that is comes from the `entrypoint` setting, because a
  module is loaded one way or the other and never both: an `[entrypoint]` module
  gets entrypoint/main.dang and the __dagger.dispatch.ts it shells out to, a
  `[runtime]` module gets the __dagger.entrypoint.ts that runtime execs. sdk/
  and clients/ are common to both — the library and the per-module bindings the
  module's own source imports, whichever way it is loaded.
  """
  let moduleDirectory(
    schemaJSON: String!,
    moduleName: String!,
    sourcePath: String!,
    source: Directory!,
    existing: Directory!,
    runtime: Runtime!,
    packageManager: String!,
    targets: [ClientTarget!]!,
    repoURL: String!,
  ): Directory! {
    let bindings = generateModuleBindings(schemaJSON, moduleName, targets, repoURL)
    # The embedded layout's sdk/ carries the client files and the loader flat
    # beside client.gen.ts: sdk/ is the one directory the builtin runtime mounts
    # into node_modules, and it cannot be told to mount anything else.
    let sdk = if (entrypoint) { moduleSdkDirectory(bindings) } else { embeddedSdkDirectory(bindings) }
    let clients = if (entrypoint) { moduleClientsDirectory(bindings) } else { directory }
    let typedef = moduleTypedefJSON(moduleName, source, sdk, clients)
    let clientNames = bindingAliasModules(bindings)

    # Two layouts. Under an entrypoint every client is a self-contained package
    # in clients/<name>/, with the scope's own @dagger.io/dagger beside them as
    # clients/dagger/ — the identical shape a client-only scope generates — and
    # the loader among them. The embedded [runtime] layout ships everything
    # inside sdk/, resolved by tsconfig alias.
    let base = if (entrypoint) {
      directory
        .withDirectory("clients", withClientPackageManifests(clients, clientNames))
        .withDirectory("clients/dagger", corePackage(bindings))
        .withFile(dispatchFile, generateModuleDispatcher(typedef))
        .withFile(
          dangEntrypointDir + "/main.dang",
          generateDangEntrypoint(typedef, moduleName, sourcePath, runtime, packageManager),
        )
    } else {
      directory
        .withDirectory("sdk", sdk)
        .withFile(legacyEntrypointFile, generateModuleEntrypoint(typedef))
    }

    # The config the module's source resolves its clients through. Entrypoint:
    # package.json file: deps — core installed by default, each client too.
    # Embedded: tsconfig path aliases; the module's own name rides along
    # speculatively so a module whose source imports its own client can load,
    # and the second pass corrects the set to what exists.
    let aliasModules = clientNames.filter { m => m != moduleName } + [moduleName]
    base.withDirectory(".", moduleConfigDirectory(existing, runtime, aliasModules, clientNames))
  }

  """
  Complete each generated client package with its manifest: codegen nests the
  files (clients/<name>/<name>.gen.ts, loader.gen.ts beside them), and this adds
  the package.json that makes each directory npm-installable.
  """
  let withClientPackageManifests(clients: Directory!, clientNames: [String!]!): Directory! {
    clientNames.reduce(clients) { acc, name =>
      acc.withNewFile(name + "/package.json", clientPackageJSON(name, clientNames))
    }
  }

  """
  The names each generated module client is aliased under, with the loader —
  which is not a module — left out. Packaged clients are the directories under
  clients/ holding a <name>.gen.ts; the embedded layout's are the flat files
  beside client.gen.ts in the bindings root.
  """
  let bindingAliasModules(bindings: Directory!): [String!]! {
    if (entrypoint) {
      packagedClientNames(moduleClientsDirectory(bindings))
    } else {
      bindings.entries
        .filter { entry => entry.trimSuffix(".gen.ts") != entry }
        .map { entry => entry.trimSuffix(".gen.ts") }
        .filter { name => name != "loader" and name != "client" }
    }
  }

  """
  The package names in a directory of packaged clients: one per <name>/ holding
  its <name>.gen.ts, the loader and any stray file left out.
  """
  let packagedClientNames(clients: Directory!): [String!]! {
    clients.glob("*/*.gen.ts")
      .map { path => path.split("/").takeFirst(1).join("") }
      .filter { name => name != "dagger" }
  }

  """
  A scope's config files. Under an entrypoint, package.json is the resolver:
  the module's own clients/dagger and each generated client — the self client
  included, since it only exists when the user asked for it — are file:
  dependencies. The embedded layout keeps its tsconfig path aliases. Callers
  derive the name set from the bindings of the pass they are writing.
  """
  let moduleConfigDirectory(existing: Directory!, runtime: Runtime!, aliasModules: [String!]!, clientNames: [String!]!): Directory! {
    let configUpdater = configUpdaterBuilder
      .withDirectory("/existing", existing)
      .withDirectory("/out", directory)
    let clientPairs = clientNames.map { name => name + "=./clients/" + name }

    if (runtime == Runtime.DENO) {
      # Deno resolves through its import map, so under an entrypoint the map
      # points at the packages: core at ./clients/dagger, each client in its
      # package directory (the trailing slash selects that form).
      let denoCore = if (entrypoint) { "./clients/dagger" } else { "" }
      let denoClientsDir = if (entrypoint) { "clients/" } else { "sdk" }
      configUpdater
        .withExec(["config-updater", "deno-config", "/existing/deno.json", "/out/deno.json", denoCore, denoClientsDir] + aliasModules)
        .directory("/out")
    } else if (entrypoint) {
      # package.json is the link: node/bun resolve every @dagger.io/* package
      # through node_modules after an install, so the tsconfig carries no path
      # alias at all — "-" writes none and removes one an earlier layout left.
      configUpdater
        .withExec(["config-updater", "shared-deps", "/existing/package.json", "/out/package.json", "./clients/dagger"] + clientPairs)
        .withExec(["config-updater", "tsconfig", "/existing/tsconfig.json", "/out/tsconfig.json", "-", "clients"])
        .directory("/out")
    } else {
      # The embedded layout's clients live inside sdk/, so each alias points
      # there — the same directory the @dagger.io/dagger alias already names.
      configUpdater
        .withExec(["config-updater", "package-json", "/existing/package.json", "/out/package.json"])
        .withExec(["config-updater", "tsconfig", "/existing/tsconfig.json", "/out/tsconfig.json", "", "sdk"] + aliasModules)
        .directory("/out")
    }
  }

  """
  Read a module's current config files so regeneration preserves user settings
  rather than resetting them. Filtered from the workspace root so a module
  without any of them simply yields an empty directory.
  """
  let existingModuleConfig(ws: Workspace!, sourcePath: String!): Directory! {
    let prefix = if (sourcePath == ".") { "" } else { sourcePath + "/" }
    let filtered = ws.directory("/", include: [
      prefix + "package.json",
      prefix + "tsconfig.json",
      prefix + "deno.json",
    ])
    if (sourcePath == ".") {
      filtered
    } else if (filtered.exists(sourcePath)) {
      filtered.directory(sourcePath)
    } else {
      directory
    }
  }

  """
  A module's complete generated tree, rooted at its source directory.

  Separate from writing it because generation needs it twice over, and only the
  second one may be written: the first pass exists to make the module loadable
  so its own client schema can be read, and its bindings differ from the ones
  that end up on disk.
  """
  let moduleGenerated(ws: Workspace!, scope: String!, sourcePath: String!, name: String!, rt: Runtime!, targets: [ClientTarget!]!): Directory! {
    let sourcePrefix = if (sourcePath == ".") { "" } else { sourcePath + "/" }
    # Only the entrypoint recipe installs anything, and detection reads
    # package.json through a container — so a `[runtime]` module does not pay
    # for an answer nothing would bake.
    let pkgManager = if (entrypoint) { effectivePackageManager(ws, sourcePath, rt) } else { "" }

    moduleDirectory(
      ws.moduleSource("/" + scope).introspectionSchemaJSON.contents,
      name,
      sourcePath,
      ws.directory("/" + sourcePrefix + "src"),
      existingModuleConfig(ws, sourcePath),
      rt,
      pkgManager,
      targets,
      workspaceRepoURL(ws, scope),
    )
  }

  """
  Stage a generated tree over a module's existing one, for a workspace nothing
  reads back.

  Whole-directory write, which is the cheap way to get a loadable module and the
  wrong way to produce a result: the engine's changeset carries every file
  written, so a workspace built this way reports the whole tree. Only
  `moduleFiles` is allowed to reach the caller.

  The existing bindings stay in, deliberately. Loading a [runtime] module
  executes its TypeScript, and a source that imports its own client resolves it
  to the previous generation's <self>.gen.ts — which this first pass has not
  rendered yet, so removing the existing copy is what makes the staged module
  unloadable and the second pass impossible. A binding that has gone stale the
  other way — a dropped dependency's file — is inert at load time as long as
  nothing imports it; the write path prunes it once the module has loaded.
  """
  let stagedModule(ws: Workspace!, sourcePath: String!, generated: Directory!): Workspace! {
    ws.withNewDirectory("/" + sourcePath, existingDir(ws, sourcePath).withDirectory(".", generated))
  }

  """
  Write a module's generated tree into its source directory, one file at a time,
  skipping every file whose content is already what we would write.

  Skipping is the whole point, and it is not an optimization. The changeset the
  engine hands back records what was *written*, not what changed — a file
  rewritten with its own bytes is in it just the same, and then reads as a whole
  new file against a base that was sized from the paths that really changed. One
  added function reported both binding files, 18k unchanged lines, as brand new.

  Compared on content alone: the default digest covers metadata too, and two
  renders of the same bytes differ there every time.

  Written with withFile rather than withNewFile so the generated files keep the
  permissions they were rendered with.
  """
  let moduleFiles(ws: Workspace!, sourcePath: String!, generated: Directory!, pruneStale: Boolean!): Workspace! {
    if (entrypoint) {
      # clients/ is fully generated under an entrypoint, so anything in it this
      # run does not render is stale and removed. Earlier layouts are taken with
      # it: the embedded sdk/, a loader or client packages left at the module
      # root, whichever a previous generation wrote.
      let base = prunedClientPackages(
        prunedRootLoader(prunedEmbeddedSdk(prunedInactiveDispatch(ws, sourcePath), sourcePath), sourcePath),
        sourcePath,
        [],
      )
      writeChanged(
        prunedDirFiles(base, moduleClientsPath(sourcePath), generated.directory("clients")),
        sourcePath,
        generated,
      )
    } else {
      # An embedded module's clients live inside sdk/ now; a clients/ directory
      # an earlier layout left is taken with the move. Stale bindings are pruned
      # only when the module loaded: a run that could not read the client set
      # would otherwise delete the self client — the very file whose absence in
      # the staged tree can be why the load failed — and leave the module more
      # broken than it found it.
      let pruned = if (pruneStale) { prunedBindings(ws, sourcePath, generated) } else { ws }
      writeChanged(
        prunedEmbeddedClientsDir(prunedInactiveDispatch(pruned, sourcePath), sourcePath),
        sourcePath,
        generated,
      )
    }
  }

  """
  Remove the clients/ directory an earlier embedded layout kept beside sdk/:
  its files are inside sdk/ now, where the builtin runtime's one mount reaches
  them. A no-op when there is none.
  """
  let prunedEmbeddedClientsDir(ws: Workspace!, sourcePath: String!): Workspace! {
    let clientsPath = moduleClientsPath(sourcePath)
    if (existingDir(ws, clientsPath).entries.length == 0) {
      ws
    } else {
      ws.withoutDirectory("/" + clientsPath)
    }
  }

  """
  Remove the loader an earlier layout left at the module root; it lives under
  clients/ beside the packages it imports.
  """
  let prunedRootLoader(ws: Workspace!, sourcePath: String!): Workspace! {
    let path = scopeFile(sourcePath, "loader.gen.ts")
    if (ws.directory("/", include: [path]).exists(path)) {
      ws.withoutFile("/" + path)
    } else {
      ws
    }
  }

  """
  Drop the files in a fully generated directory that this run does not render.
  Writing file by file can only add, so removals are explicit; node_modules is
  left alone — a user's install, not rendered content.

  A package directory whose last file goes is taken whole — withoutFile leaves
  the emptied directory behind otherwise, a husk of a removed client.
  """
  let prunedDirFiles(ws: Workspace!, dir: String!, generated: Directory!): Workspace! {
    let kept = generated.glob("**")
    let keptDirs = generated.entries.filter { e => e.trimSuffix("/") != e }.map { e => e.trimSuffix("/") }

    let withoutFiles = filePaths(existingDir(ws, dir))
      .filter { path => path.hasPrefix("node_modules/") == false and path.split("/node_modules/").length == 1 }
      .filter { path => kept.filter { name => name == path }.length == 0 }
      .reduce(ws) { acc, path => acc.withoutFile("/" + dir + "/" + path) }

    existingDir(ws, dir).entries
      .filter { e => e.trimSuffix("/") != e }
      .map { e => e.trimSuffix("/") }
      .filter { name => name != "node_modules" and keptDirs.filter { k => k == name }.length == 0 }
      .reduce(withoutFiles) { acc, name => acc.withoutDirectory("/" + dir + "/" + name) }
  }

  """
  Take the dispatch machinery of the loading path this module is not on.

  Writing stops on its own — moduleDirectory renders one path's files, not both
  — but writing is all that stops. A module generated under the other setting
  keeps what is already on disk: a legacy __dagger.entrypoint.ts beside a real
  dispatcher with almost the same name, or a dispatcher and an entrypoint/
  carrying a whole call recipe that nothing loads. Deleting is explicit here for
  the same reason stale bindings are: what is no longer generated is not removed
  by not generating it.

  entrypoint/ goes wholesale: the directory exists to hold the generated Dang
  program, and nothing in it is the user's.
  """
  let prunedInactiveDispatch(ws: Workspace!, sourcePath: String!): Workspace! {
    let existing = existingDir(ws, sourcePath)
    let prefix = if (sourcePath == ".") { "/" } else { "/" + sourcePath + "/" }

    if (entrypoint) {
      if (existing.exists(legacyEntrypointFile)) {
        ws.withoutFile(prefix + legacyEntrypointFile)
      } else {
        ws
      }
    } else {
      let withoutDispatcher = if (existing.exists(dispatchFile)) {
        ws.withoutFile(prefix + dispatchFile)
      } else {
        ws
      }
      if (existing.exists(dangEntrypointDir)) {
        withoutDispatcher.withoutDirectory(prefix + dangEntrypointDir)
      } else {
        withoutDispatcher
      }
    }
  }

  """
  Every file in a directory, as paths relative to it, directories left out.
  """
  let filePaths(dir: Directory!): [String!]! {
    dir.glob("**").filter { path => path.trimSuffix("/") == path }
  }

  """
  Write a generated tree into a workspace directory, one file at a time, and
  skip every file whose content is already what we would write.

  Skipping is the whole point, and it is not an optimization. The changeset the
  engine hands back records what was *written*, not what changed — a file
  rewritten with its own bytes is in it just the same, and then reads as a whole
  new file against a base that was sized from the paths that really changed. One
  added function reported both binding files, 18k unchanged lines, as brand new.

  Compared on content alone: the default digest covers metadata too, and two
  renders of the same bytes differ there every time.

  withFile rather than withNewFile, so what lands keeps the permissions it was
  rendered with.
  """
  let writeChanged(ws: Workspace!, dirPath: String!, generated: Directory!): Workspace! {
    let prefix = if (dirPath == ".") { "/" } else { "/" + dirPath + "/" }

    filePaths(generated).reduce(ws) { acc, path =>
      let target = prefix + path
      let current = acc.file(target).digest(excludeMetadata: true) rescue {
        # Nothing there yet, so nothing to compare against and nothing to skip.
        err: Error => ""
      }
      if (current == generated.file(path).digest(excludeMetadata: true)) {
        acc
      } else {
        acc.withFile(target, generated.file(path))
      }
    }
  }

  """
  Drop the `*.gen.ts` files in a module's clients/ that this run does not
  generate.

  Regeneration owns that set: a dependency that has left the module's closure
  must lose its file, or it goes on exporting an API against a module no longer
  served and a default tsc rejects it. Writing file by file can only add, so the
  removals are made explicitly here — the whole-directory write this replaced
  got them for free by replacing everything.
  """
  let prunedBindings(ws: Workspace!, sourcePath: String!, generated: Directory!): Workspace! {
    let sdkPath = moduleSdkPath(sourcePath)
    let kept = generated.directory("sdk").entries

    moduleBindings(ws, sourcePath)
      .filter { entry => kept.filter { name => name == entry }.length == 0 }
      .reduce(ws) { acc, entry => acc.withoutFile("/" + sdkPath + "/" + entry) }
  }

  """
  The first pass's tree with its bindings replaced by ones carrying the module's
  own API.

  The second of generation's two passes. A module's own API is not in the schema
  its bindings come from, and reading the schema that does carry it means loading
  the module — which is what the first pass is staged for. Both passes run every
  time, from the same inputs, so the result does not depend on what was on disk
  when the run started.

  Only the clients — and the config aliases derived from them — are redone:
  the library (sdk/) is core-only and identical between passes, and everything
  else in the tree comes through from the first pass. The entrypoint is the
  expensive half and it comes from scanning the user's source, which the self
  types do not change. The config is re-run because the second pass adds the
  module's own client file, and that file's @dagger.io/<module> alias has
  to exist for the module's source to import it; the first pass's config files
  serve as the existing input, so user keys merged there carry through.

  A Directory rather than a Workspace, because the first pass's clients must
  never be written to the workspace the engine diffs. They differ from these —
  that is the entire reason for a second pass — so writing them would put every
  client file in the changeset on every run that touches the module's source,
  long after the files themselves stopped changing.
  """
  let withSelfBindings(staged: Workspace!, scope: String!, name: String!, generated: Directory!, targets: [ClientTarget!]!, selfTargets: [ClientTarget!]!, rt: Runtime!, existing: Directory!): Directory! {
    if (selfTargets.length == 0) {
      # No self client recorded, so the first pass's clients are the whole set.
      generated
    } else {
      let bindings = generateModuleBindings(
        staged.moduleSource("/" + scope).introspectionSchemaJSON.contents,
        name,
        targets,
        workspaceRepoURL(staged, scope),
      )
      let clientNames = bindingAliasModules(bindings)
      let aliasModules = clientNames.filter { m => m != name } + [name]

      # Add the self client and re-render the loader — the second pass's set is
      # a superset of the first's, so replacing the client tree adds the self
      # and rewrites the loader. The config re-runs against the user's ORIGINAL
      # files, not the first pass's output, so nothing the first pass — which
      # does not know the self client's name — decided about the config sticks.
      if (entrypoint) {
        let clients = moduleClientsDirectory(bindings)
        generated
          .withoutDirectory("clients")
          .withDirectory("clients", withClientPackageManifests(clients, clientNames))
          .withDirectory("clients/dagger", corePackage(bindings))
          .withDirectory(".", moduleConfigDirectory(existing, rt, aliasModules, clientNames))
      } else {
        generated
          .withoutDirectory("sdk")
          .withDirectory("sdk", embeddedSdkDirectory(bindings))
          .withDirectory(".", moduleConfigDirectory(existing, rt, aliasModules, clientNames))
      }
    }
  }

  """
  The module itself, as a target to fold into its own bindings — or nothing,
  when it cannot be loaded yet.

  Reading a module's client-facing schema means loading it, and a module built
  from committed files cannot be loaded until they exist. So the first
  generation of a brand-new module has no self bindings and the one after it
  does. That is the same shape the engine's own generators have: a module that
  could not load before a run loads with the run's changes applied.
  """
  let selfClientTarget(ws: Workspace!, scope: String!, name: String!): [ClientTarget!]! {
    let selfSource = ws.moduleSource("/" + scope).{{ clientSchemaIntrospectionJSON.{{ contents }} }} rescue {
      err: Error => null
    }

    if (selfSource == null) {
      []
    } else {
      # A local module like any other from the package's point of view: the
      # generated bootstrap serves it by resolving `scope` against the workspace,
      # so a caller outside the module reaches it the same way it reaches a
      # target that was added on purpose.
      #
      # Never a dependency, though — a module does not depend on itself, and the
      # engine already serves it into its own session.
      #
      # Local by construction rather than by asking: a Git workspace — Dagger
      # Cloud's checkout of a commit — loads its own modules as Git sources, and
      # serving this one by that ref would pin the generated client to the commit
      # it was generated at, so no committed client could ever match.
      [ClientTarget(
        name: name,
        schemaJSON: selfSource.clientSchemaIntrospectionJSON.contents,
        kindJSON: JSON.encode(ModuleSourceKind.LOCAL_SOURCE),
        isLocal: true,
        path: scope,
        ref: "",
        pin: "",
        isSelf: true,
      )]
    }
  }

  """
  Take a module's embedded sdk/ with the switch to the shared core: the library
  lives at .dagger/core/typescript now, and the copy under the module is the
  duplication this layout removes. A no-op when there is none.
  """
  let prunedEmbeddedSdk(ws: Workspace!, sourcePath: String!): Workspace! {
    let sdkPath = moduleSdkPath(sourcePath)
    if (existingDir(ws, sdkPath).entries.length == 0) {
      ws
    } else {
      ws.withoutDirectory("/" + sdkPath)
    }
  }

  """
  Where a module's files belong: its scope, unless its manifest points `source`
  somewhere else.

  Workspace migration writes a config to .dagger/modules/<name>/ with `source`
  aimed back at the code it wrapped, so the directory the runtime reads is not
  always the directory holding the manifest. Resolved through the engine rather
  than assumed equal to the scope.
  """
  let moduleSourcePath(ws: Workspace!, scope: String!): String! {
    let subpath = ws.moduleSource("/" + scope).sourceSubpath
    if (subpath == "" or subpath == ".") { "." } else { subpath }
  }

  """
  Workspace-relative path of a module's generated sdk/ directory (the library).
  """
  let moduleSdkPath(sourcePath: String!): String! {
    if (sourcePath == ".") { "sdk" } else { sourcePath + "/sdk" }
  }

  """
  Workspace-relative path of a module's generated clients/ directory, where the
  per-module client files and the loader live.
  """
  let moduleClientsPath(sourcePath: String!): String! {
    if (sourcePath == ".") { "clients" } else { sourcePath + "/clients" }
  }

  """
  The `*.gen.ts` files sitting in an embedded module's sdk/ directory, by name.

  Regeneration owns that set and nothing else: a dependency that has left the
  module's closure must lose its file, while the bundle files beside them are
  rewritten in place every time and never go stale.

  Taken out of the baseline the generated tree is layered onto, which is the
  only place it has to happen: layering keeps the module's own source and config
  in the changeset, but it can only add, so a file we stop generating would
  otherwise be left behind — a dependency dropped from the config keeping its
  <dep>.gen.ts, exporting an API against a module no longer served, which a
  default tsc rejects. client.gen.ts is in the set and always in the generated
  tree, so it is staged out and rewritten rather than ever pruned.
  """
  let moduleBindings(ws: Workspace!, sourcePath: String!): [String!]! {
    existingDir(ws, moduleSdkPath(sourcePath)).entries
      .filter { entry => entry.trimSuffix(".gen.ts") != entry }
  }

  """
  Generate a standalone client scope's bindings: one client.gen.ts holding the
  core API (the vendored library's bindings), plus one flat <module>.gen.ts
  client per target.

  Rendered exactly like a module's clients — each is a self-contained client
  that serves its own module on use (git by ref+pin, local by workspace path) —
  so the two converge. The only differences are layout: flat, and no entrypoint
  loader. Each target contributes its client-facing schema (core plus that one
  module); codegen merges them so the core API is emitted once.
  """
  let generateClientBindings(targets: [ClientTarget!]!, repoURL: String!): Directory! {
    stageTargets(codegenBuilder, targets)
      .withExec([
        "codegen", "client",
        "--client-meta-path", "/meta.json",
        "--packaged-clients",
        "--output", "/out",
        "--workspace-repo-url", repoURL,
      ])
      .directory("/out")
  }

  """
  Where a target's schema is staged inside the codegen container.
  """
  let schemaPath(name: String!): String! {
    "/schemas/" + name + ".json"
  }

  """
  Build a client-only scope's clients/ directory: one npm-installable package per
  target, with the scope's own @dagger.io/dagger package beside them.

  ```
  <scope>/clients/
    dagger/          the scope's @dagger.io/dagger package
    <module>/        one package per target, named @dagger.io/<module>
  ```

  The identical shape a module scope's clients/ gets — these packages resolve
  through npm and can be installed and used anywhere: the scope's own code,
  another project, a module. Each declares its dependencies as file: links, so
  installing a client pulls the core (and any sibling it references) along.
  """
  let clientDirectory(bindings: Directory!): Directory! {
    let modules = packagedClientNames(bindings)

    withClientPackageManifests(
      modules.reduce(directory) { acc, name => acc.withDirectory(name, bindings.directory(name)) },
      modules,
    ).withDirectory("dagger", corePackage(bindings))
  }

  """
  A client package's manifest: named @dagger.io/<module> — the specifier the
  code imports, and the name it would publish under — with a file: dependency
  on the sibling dagger/ core package and on every sibling client, so
  installing one client links everything it can reference. The version is a
  placeholder npm requires for a file: dependency to resolve at all.
  """
  let clientPackageJSON(name: String!, modules: [String!]!): String! {
    let deps = ["  \"@dagger.io/dagger\": \"file:../dagger\""] +
      modules
        .filter { sibling => sibling != name }
        .map { sibling => "  \"@dagger.io/" + sibling + "\": \"file:../" + sibling + "\"" }

    # main/types beside exports for the same reason the core package carries
    # them: a module's tsconfig resolves with the classic `node` setting, which
    # ignores `exports` — without a main/types a bare `@dagger.io/<name>` import
    # resolves to nothing and the editor cannot find the module.
    "{\n" +
      "  \"name\": \"@dagger.io/" + name + "\",\n" +
      "  \"version\": \"0.0.0\",\n" +
      "  \"type\": \"module\",\n" +
      "  \"main\": \"./" + name + ".gen.ts\",\n" +
      "  \"types\": \"./" + name + ".gen.ts\",\n" +
      "  \"exports\": {\n" +
      "    \".\": \"./" + name + ".gen.ts\"\n" +
      "  },\n" +
      "  \"dependencies\": {\n  " +
      deps.join(",\n  ") + "\n" +
      "  }\n" +
      "}\n"
  }

  """
  Generate a client-only scope: its clients/ directory of installable packages,
  the scope's own core among them, wired through the scope's package.json.

  clients/ is fully generated, so anything in it this run does not render is
  removed; the rest of the scope is the user's and untouched. A scope whose last
  client leaves loses the directory and its file: deps with it.
  """
  let clientScope(ws: Workspace!, base: String!, targets: [ClientTarget!]!): Workspace! {
    let dir = scopeFile(base, "clients")

    if (targets.length == 0) {
      let cleared = if (existingDir(ws, dir).entries.length == 0) { ws } else { ws.withoutDirectory("/" + dir) }
      withScopeClientDeps(withoutLegacyScopeClients(prunedClientPackages(cleared, base, []), base), base, [])
    } else {
      let generated = clientDirectory(generateClientBindings(targets, scopeRepoURL(ws, base, targets)))
      let modules = packagedClientNames(generated)
      # What earlier layouts left behind moves under clients/ with the
      # regeneration: packages directly in the scope (the marker scan) and the
      # .dagger/clients directory of the layout before that.
      let migrated = withoutLegacyScopeClients(prunedClientPackages(ws, base, []), base)
      let written = writeChanged(prunedDirFiles(migrated, dir, generated), dir, generated)
      # package.json is the link: the scope's manifest names its core and each
      # client as file: dependencies, so `npm install` in the scope wires them.
      withScopeClientDeps(written, base, modules)
    }
  }

  """
  Take the .dagger/clients directory an earlier layout kept beneath a client
  scope: it was fully generated, and the packages live under clients/ now.
  """
  let withoutLegacyScopeClients(ws: Workspace!, scope: String!): Workspace! {
    let old = scopeFile(scope, ".dagger/clients")
    if (existingDir(ws, old).entries.length == 0) {
      ws
    } else {
      ws.withoutDirectory("/" + old)
    }
  }

  """
  Wire a client-only scope's package.json to its clients/dagger core and each
  generated client, all as file: dependencies. Preserves the rest of the user's
  manifest; with no clients left, the SDK's own deps are pruned instead.
  """
  let withScopeClientDeps(ws: Workspace!, scope: String!, modules: [String!]!): Workspace! {
    let pkgPath = scopeFile(scope, "package.json")
    let existing = ws.directory("/", include: [pkgPath])
    let core = if (modules.length == 0) { "-" } else { "./clients/dagger" }
    let pairs = modules.map { name => name + "=./clients/" + name }

    let updated = configUpdaterBuilder
      .withDirectory("/existing", if (existing.exists(scope)) { existing.directory(scope) } else { directory })
      .withDirectory("/out", directory)
      .withExec(["config-updater", "shared-deps", "/existing/package.json", "/out/package.json", core] + pairs)
      .file("/out/package.json")

    writeChanged(ws, scope, directory.withFile("package.json", updated))
  }

  """
  Remove the generated client package dirs an earlier layout left directly in a
  scope — module or client-only — leaving the user's own files untouched. A
  stale package is a top-level dir, other than clients/, that carries the
  <name>.gen.ts a generated client is known by.
  """
  let prunedClientPackages(ws: Workspace!, scope: String!, modules: [String!]!): Workspace! {
    existingDir(ws, scope).entries
      .map { entry => entry.trimSuffix("/") }
      .filter { name => name != "clients" and modules.filter { m => m == name }.length == 0 }
      .filter { name => existingDir(ws, scopeFile(scope, name)).exists(name + ".gen.ts") }
      .reduce(ws) { acc, name => acc.withoutDirectory("/" + scopeFile(scope, name)) }
  }

}

"""
One module a scope generates a client for: its client-facing schema plus the
provenance the generated bootstrap needs to serve it at runtime.

Projected off a ModuleSource rather than passed as one, so the whole target set
resolves in a single pass instead of a round-trip per field per module.
"""
type ClientTarget {
  """
  The target module's name, which names its generated bindings file.
  """
  let name: String!

  """
  The target's client-facing introspection schema: core plus this one module.
  """
  let schemaJSON: String!

  """
  JSON-encoded source kind, deciding how the generated bootstrap serves it.
  Encoded at projection time because the engine types it as an enum.
  """
  let kindJSON: String!

  """
  Whether this target is a local module, and so addressed by path rather than by
  a canonical ref.
  """
  let isLocal: Boolean!

  """
  Whether this target is the module being generated. Its own types are folded
  into its bindings differently, and it is never a dependency or a package entry.
  """
  let isSelf: Boolean!

  """
  Workspace-root-relative path, for local kinds.
  """
  let path: String!

  """
  Canonical ref, for git kinds.
  """
  let ref: String!

  """
  Pinned version, for git kinds.
  """
  let pin: String!
}