@dagger.io/dagger 0.18.2 → 0.18.4

package/dist/src/api/client.gen.js

@@ -145,16 +145,20 @@ export var TypeDefKind;
 })(TypeDefKind || (TypeDefKind = {}));
 export class Binding extends BaseClient {
     _id = undefined;
+    _asString = undefined;
     _digest = undefined;
+    _isNull = undefined;
     _name = undefined;
     _typeName = undefined;
     /**
      * Constructor is used for internal usage only, do not create object from it.
      */
-    constructor(ctx, _id, _digest, _name, _typeName) {
+    constructor(ctx, _id, _asString, _digest, _isNull, _name, _typeName) {
         super(ctx);
         this._id = _id;
+        this._asString = _asString;
         this._digest = _digest;
+        this._isNull = _isNull;
         this._name = _name;
         this._typeName = _typeName;
     }
@@ -267,6 +271,17 @@ export class Binding extends BaseClient {
         const ctx = this._ctx.select("asSocket");
         return new Socket(ctx);
     };
+    /**
+     * The binding's string value
+     */
+    asString = async () => {
+        if (this._asString) {
+            return this._asString;
+        }
+        const ctx = this._ctx.select("asString");
+        const response = await ctx.execute();
+        return response;
+    };
     /**
      * The digest of the binding value
      */
@@ -278,6 +293,17 @@ export class Binding extends BaseClient {
         const response = await ctx.execute();
         return response;
     };
+    /**
+     * Returns true if the binding is null
+     */
+    isNull = async () => {
+        if (this._isNull) {
+            return this._isNull;
+        }
+        const ctx = this._ctx.select("isNull");
+        const response = await ctx.execute();
+        return response;
+    };
     /**
      * The binding name
      */
@@ -383,8 +409,6 @@ export class Container extends BaseClient {
      * If empty, the container's default command is used.
      * @param opts.useEntrypoint If the container has an entrypoint, prepend it to the args.
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
      * @param opts.expand Replace "${VAR}" or "$VAR" in the args according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      * @param opts.noInit If set, skip the automatic init process injected into containers by default.
@@ -396,7 +420,7 @@ export class Container extends BaseClient {
         return new Service(ctx);
     };
     /**
-     * Returns a File representing the container serialized to a tarball.
+     * Package the container state as an OCI image, and return it as a tar archive
      * @param opts.platformVariants Identifiers for other platform specific containers.
      *
      * Used for multi-platform images.
@@ -426,13 +450,16 @@ export class Container extends BaseClient {
      * They will be mounted at /run/secrets/[secret-name] in the build container
      *
      * They can be accessed in the Dockerfile using the "secret" mount type and mount path /run/secrets/[secret-name], e.g. RUN --mount=type=secret,id=my-secret curl [http://example.com?token=$(cat /run/secrets/my-secret)](http://example.com?token=$(cat /run/secrets/my-secret))
+     * @param opts.noInit If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
      */
     build = (context, opts) => {
         const ctx = this._ctx.select("build", { context, ...opts });
         return new Container(ctx);
     };
     /**
-     * Retrieves default arguments for future commands.
+     * Return the container's default arguments.
      */
     defaultArgs = async () => {
         const ctx = this._ctx.select("defaultArgs");
@@ -440,7 +467,7 @@ export class Container extends BaseClient {
         return response;
     };
     /**
-     * Retrieves a directory at the given path.
+     * Retrieve a directory from the container's root filesystem
      *
      * Mounts are included.
      * @param path The path of the directory to retrieve (e.g., "./src").
@@ -451,7 +478,7 @@ export class Container extends BaseClient {
         return new Directory(ctx);
     };
     /**
-     * Retrieves entrypoint to be prepended to the arguments of all commands.
+     * Return the container's OCI entrypoint.
      */
     entrypoint = async () => {
         const ctx = this._ctx.select("entrypoint");
@@ -479,9 +506,9 @@ export class Container extends BaseClient {
         return response.map((r) => new Client(ctx.copy()).loadEnvVariableFromID(r.id));
     };
     /**
-     * The exit code of the last executed command.
+     * The exit code of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     exitCode = async () => {
         if (this._exitCode) {
@@ -570,10 +597,8 @@ export class Container extends BaseClient {
         return new File(ctx);
     };
     /**
-     * Initializes this container from a pulled base image.
-     * @param address Image's address from its registry.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").
+     * Download a container image, and apply it to the container state. All previous state will be lost.
+     * @param address Address of the container image to download, in standard OCI ref format. Example:"registry.dagger.io/engine:latest"
      */
     from = (address) => {
         const ctx = this._ctx.select("from", { address });
@@ -639,14 +664,12 @@ export class Container extends BaseClient {
         return response;
     };
     /**
-     * Publishes this container as a new image to the specified address.
+     * Package the container state as an OCI image, and publish it to a registry
      *
-     * Publish returns a fully qualified ref.
+     * Returns the fully qualified address of the published image, with digest
+     * @param address The OCI address to publish to
      *
-     * It can also publish platform variants.
-     * @param address Registry's address to publish the image to.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").
+     * Same format as "docker push". Example: "registry.example.com/user/repo:tag"
      * @param opts.platformVariants Identifiers for other platform specific containers.
      *
      * Used for multi-platform image.
@@ -655,7 +678,7 @@ export class Container extends BaseClient {
      * If this is unset, then if a layer already has a compressed blob in the engine's cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine's cache, then it will be compressed using Gzip.
      * @param opts.mediaTypes Use the specified media types for the published image's layers.
      *
-     * Defaults to OCI, which is largely compatible with most recent registries, but Docker may be needed for older registries without OCI support.
+     * Defaults to "OCI", which is compatible with most recent registries, but "Docker" may be needed for older registries without OCI support.
      */
     publish = async (address, opts) => {
         if (this._publish) {
@@ -674,16 +697,16 @@ export class Container extends BaseClient {
         return response;
     };
     /**
-     * Retrieves this container's root filesystem. Mounts are not included.
+     * Return a snapshot of the container's root filesystem. The snapshot can be modified then written back using withRootfs. Use that method for filesystem modifications.
      */
     rootfs = () => {
         const ctx = this._ctx.select("rootfs");
         return new Directory(ctx);
     };
     /**
-     * The error stream of the last executed command.
+     * The buffered standard error stream of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     stderr = async () => {
         if (this._stderr) {
@@ -694,9 +717,9 @@ export class Container extends BaseClient {
         return response;
     };
     /**
-     * The output stream of the last executed command.
+     * The buffered standard output stream of the last executed command
      *
-     * Returns an error if no command was set.
+     * Returns an error if no command was executed
      */
     stdout = async () => {
         if (this._stdout) {
@@ -720,8 +743,6 @@ export class Container extends BaseClient {
      * Opens an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).
      * @param opts.cmd If set, override the container's default terminal command and invoke these command arguments instead.
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
      */
     terminal = (opts) => {
@@ -741,8 +762,6 @@ export class Container extends BaseClient {
      * If empty, the container's default command is used.
      * @param opts.useEntrypoint If the container has an entrypoint, prepend it to the args.
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
      * @param opts.expand Replace "${VAR}" or "$VAR" in the args according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      * @param opts.noInit If set, skip the automatic init process injected into containers by default.
@@ -777,7 +796,7 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Configures default arguments for future commands.
+     * Configures default arguments for future commands. Like CMD in Dockerfile.
      * @param args Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).
      */
     withDefaultArgs = (args) => {
@@ -788,8 +807,6 @@ export class Container extends BaseClient {
      * Set the default command to invoke for the container's terminal API.
      * @param args The args of the command.
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
      */
     withDefaultTerminalCmd = (args, opts) => {
@@ -797,7 +814,7 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container plus a directory written at the given path.
+     * Return a new container snapshot, with a directory added to its filesystem
      * @param path Location of the written directory (e.g., "/tmp/directory").
      * @param directory Identifier of the directory to write
      * @param opts.exclude Patterns to exclude in the written directory (e.g. ["node_modules/**", ".gitignore", ".git/"]).
@@ -814,18 +831,18 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container but with a different command entrypoint.
-     * @param args Entrypoint to use for future executions (e.g., ["go", "run"]).
-     * @param opts.keepDefaultArgs Don't remove the default arguments when setting the entrypoint.
+     * Set an OCI-style entrypoint. It will be included in the container's OCI configuration. Note, withExec ignores the entrypoint by default.
+     * @param args Arguments of the entrypoint. Example: ["go", "run"].
+     * @param opts.keepDefaultArgs Don't reset the default arguments when setting the entrypoint. By default it is reset, since entrypoint and default args are often tightly coupled.
      */
     withEntrypoint = (args, opts) => {
         const ctx = this._ctx.select("withEntrypoint", { args, ...opts });
         return new Container(ctx);
     };
     /**
-     * Retrieves this container plus the given environment variable.
-     * @param name The name of the environment variable (e.g., "HOST").
-     * @param value The value of the environment variable. (e.g., "localhost").
+     * Set a new environment variable in the container.
+     * @param name Name of the environment variable (e.g., "HOST").
+     * @param value Value of the environment variable. (e.g., "localhost").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value according to the current environment variables defined in the container (e.g. "/opt/bin:$PATH").
      */
     withEnvVariable = (name, value, opts) => {
@@ -833,23 +850,25 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container after executing the specified command inside it.
-     * @param args Command to run instead of the container's default command (e.g., ["go", "run", "main.go"]).
+     * Execute a command in the container, and return a new snapshot of the container state after execution.
+     * @param args Command to execute. Must be valid exec() arguments, not a shell command. Example: ["go", "run", "main.go"].
      *
-     * If empty, the container's default command is used.
-     * @param opts.useEntrypoint If the container has an entrypoint, prepend it to the args.
-     * @param opts.stdin Content to write to the command's standard input before closing (e.g., "Hello world").
-     * @param opts.redirectStdout Redirect the command's standard output to a file in the container (e.g., "/tmp/stdout").
-     * @param opts.redirectStderr Redirect the command's standard error to a file in the container (e.g., "/tmp/stderr").
+     * To run a shell command, execute the shell and pass the shell command as argument. Example: ["sh", "-c", "ls -l | grep foo"]
+     *
+     * Defaults to the container's default arguments (see "defaultArgs" and "withDefaultArgs").
+     * @param opts.useEntrypoint Apply the OCI entrypoint, if present, by prepending it to the args. Ignored by default.
+     * @param opts.stdin Content to write to the command's standard input. Example: "Hello world")
+     * @param opts.redirectStdout Redirect the command's standard output to a file in the container. Example: "./stdout.txt"
+     * @param opts.redirectStderr Like redirectStdout, but for standard error
      * @param opts.expect Exit codes this command is allowed to exit with without error
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
+     * @param opts.insecureRootCapabilities Execute the command with all root capabilities. Like --privileged in Docker
      *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
-     * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
+     * DANGER: this grants the command full access to the host system. Only use when 1) you trust the command being executed and 2) you specifically need this level of access.
      * @param opts.expand Replace "${VAR}" or "$VAR" in the args according to the current environment variables defined in the container (e.g. "/$VAR/foo").
-     * @param opts.noInit If set, skip the automatic init process injected into containers by default.
+     * @param opts.noInit Skip the automatic init process injected into containers by default.
      *
-     * This should only be used if the user requires that their exec process be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
+     * Only use this if you specifically need the command to be pid 1 in the container. Otherwise it may result in unexpected behavior. If you're not sure, you don't need this.
      */
     withExec = (args, opts) => {
         const metadata = {
@@ -863,16 +882,16 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Expose a network port.
+     * Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support)
      *
      * Exposed ports serve two purposes:
      *
      * - For health checks and introspection, when running services
      *
      * - For setting the EXPOSE OCI field when publishing the container
-     * @param port Port number to expose
-     * @param opts.protocol Transport layer network protocol
-     * @param opts.description Optional port description
+     * @param port Port number to expose. Example: 8080
+     * @param opts.protocol Network protocol. Example: "tcp"
+     * @param opts.description Port description. Example: "payment API endpoint"
      * @param opts.experimentalSkipHealthcheck Skip the health check when run as a service.
      */
     withExposedPort = (port, opts) => {
@@ -887,10 +906,10 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container plus the contents of the given file copied to the given path.
-     * @param path Location of the copied file (e.g., "/tmp/file.txt").
-     * @param source Identifier of the file to copy.
-     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     * Return a container snapshot with a file added
+     * @param path Path of the new file. Example: "/path/to/new-file.txt"
+     * @param source File to add
+     * @param opts.permissions Permissions of the new file. Example: 0600
      * @param opts.owner A user:group to set for the file.
      *
      * The user and group can either be an ID (1000:1000) or a name (foo:bar).
@@ -1017,10 +1036,10 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container plus a new file written at the given path.
-     * @param path Location of the written file (e.g., "/tmp/file.txt").
-     * @param contents Content of the file to write (e.g., "Hello world!").
-     * @param opts.permissions Permission given to the written file (e.g., 0600).
+     * Return a new container snapshot, with a file added to its filesystem with text content
+     * @param path Path of the new file. May be relative or absolute. Example: "README.md" or "/etc/profile"
+     * @param contents Contents of the new file. Example: "Hello world!"
+     * @param opts.permissions Permissions of the new file. Example: 0600
      * @param opts.owner A user:group to set for the file.
      *
      * The user and group can either be an ID (1000:1000) or a name (foo:bar).
@@ -1033,12 +1052,10 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with a registry authentication for a given address.
-     * @param address Registry's address to bind the authentication to.
-     *
-     * Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
-     * @param username The username of the registry's account (e.g., "Dagger").
-     * @param secret The API key, password or token to authenticate to this registry.
+     * Attach credentials for future publishing to a registry. Use in combination with publish
+     * @param address The image address that needs authentication. Same format as "docker push". Example: "registry.dagger.io/dagger:latest"
+     * @param username The username to authenticate with. Example: "alice"
+     * @param secret The API key, password or token to authenticate to this registry
      */
     withRegistryAuth = (address, username, secret) => {
         const ctx = this._ctx.select("withRegistryAuth", {
@@ -1049,32 +1066,32 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves the container with the given directory mounted to /.
-     * @param directory Directory to mount.
+     * Change the container's root filesystem. The previous root filesystem will be lost.
+     * @param directory The new root filesystem.
      */
     withRootfs = (directory) => {
         const ctx = this._ctx.select("withRootfs", { directory });
         return new Container(ctx);
     };
     /**
-     * Retrieves this container plus an env variable containing the given secret.
-     * @param name The name of the secret variable (e.g., "API_SECRET").
-     * @param secret The identifier of the secret value.
+     * Set a new environment variable, using a secret value
+     * @param name Name of the secret variable (e.g., "API_SECRET").
+     * @param secret Identifier of the secret value.
      */
     withSecretVariable = (name, secret) => {
         const ctx = this._ctx.select("withSecretVariable", { name, secret });
         return new Container(ctx);
     };
     /**
-     * Establish a runtime dependency on a service.
+     * Establish a runtime dependency on a from a container to a network service.
      *
      * The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.
      *
      * The service will be reachable from the container via the provided hostname alias.
      *
      * The service dependency will also convey to any files or directories produced by the container.
-     * @param alias A name that can be used to reach the service from the container
-     * @param service Identifier of the service container
+     * @param alias Hostname that will resolve to the target service (only accessible from within this container)
+     * @param service The target service
      */
     withServiceBinding = (alias, service) => {
         const ctx = this._ctx.select("withServiceBinding", { alias, service });
@@ -1104,7 +1121,7 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with a different working directory.
+     * Change the container's working directory. Like WORKDIR in Dockerfile.
      * @param path The path to set as the working directory (e.g., "/app").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of path according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      */
@@ -1121,14 +1138,14 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with unset default arguments for future commands.
+     * Remove the container's default arguments.
      */
     withoutDefaultArgs = () => {
         const ctx = this._ctx.select("withoutDefaultArgs");
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with the directory at the given path removed.
+     * Return a new container snapshot, with a directory removed from its filesystem
      * @param path Location of the directory to remove (e.g., ".github/").
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of path according to the current environment variables defined in the container (e.g. "/$VAR/foo").
      */
@@ -1137,7 +1154,7 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with an unset command entrypoint.
+     * Reset the container's OCI entrypoint.
      * @param opts.keepDefaultArgs Don't remove the default arguments when unsetting the entrypoint.
      */
     withoutEntrypoint = (opts) => {
@@ -1178,8 +1195,8 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with the files at the given paths removed.
-     * @param paths Location of the files to remove (e.g., ["/file.txt"]).
+     * Return a new container spanshot with specified files removed
+     * @param paths Paths of the files to remove. Example: ["foo.txt, "/root/.ssh/config"
      * @param opts.expand Replace "${VAR}" or "$VAR" in the value of paths according to the current environment variables defined in the container (e.g. "/$VAR/foo.txt").
      */
     withoutFiles = (paths, opts) => {
@@ -1240,7 +1257,7 @@ export class Container extends BaseClient {
         return new Container(ctx);
     };
     /**
-     * Retrieves this container with an unset working directory.
+     * Unset the container's working directory.
      *
      * Should default to "/".
      */
@@ -1362,7 +1379,7 @@ export class Directory extends BaseClient {
         return response;
     };
     /**
-     * Converts this directory into a git repository
+     * Converts this directory to a local git repository
      */
     asGit = () => {
         const ctx = this._ctx.select("asGit");
@@ -1389,8 +1406,8 @@ export class Directory extends BaseClient {
         return new ModuleSource(ctx);
     };
     /**
-     * Gets the difference between this directory and an another directory.
-     * @param other Identifier of the directory to compare.
+     * Return the difference between this directory and an another directory. The difference is encoded as a directory.
+     * @param other The directory to compare against
      */
     diff = (other) => {
         const ctx = this._ctx.select("diff", { other });
@@ -1409,14 +1426,14 @@ export class Directory extends BaseClient {
     };
     /**
      * Retrieves a directory at the given path.
-     * @param path Location of the directory to retrieve (e.g., "/src").
+     * @param path Location of the directory to retrieve. Example: "/src"
      */
     directory = (path) => {
         const ctx = this._ctx.select("directory", { path });
         return new Directory(ctx);
     };
     /**
-     * Builds a new Docker container from this directory.
+     * Use Dockerfile compatibility to build a container from this directory. Only use this function for Dockerfile compatibility. Otherwise use the native Container type directly, it is feature-complete and supports all Dockerfile features.
      * @param opts.platform The platform to build.
      * @param opts.dockerfile Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
      * @param opts.target Target build stage to build.
@@ -1424,6 +1441,9 @@ export class Directory extends BaseClient {
      * @param opts.secrets Secrets to pass to the build.
      *
      * They will be mounted at /run/secrets/[secret-name].
+     * @param opts.noInit If set, skip the automatic init process injected into containers created by RUN statements.
+     *
+     * This should only be used if the user requires that their exec processes be the pid 1 process in the container. Otherwise it may result in unexpected behavior.
      */
     dockerBuild = (opts) => {
         const ctx = this._ctx.select("dockerBuild", { ...opts });
@@ -1452,7 +1472,7 @@ export class Directory extends BaseClient {
         return response;
     };
     /**
-     * Retrieves a file at the given path.
+     * Retrieve a file at the given path.
      * @param path Location of the file to retrieve (e.g., "README.md").
      */
     file = (path) => {
@@ -1460,9 +1480,9 @@ export class Directory extends BaseClient {
         return new File(ctx);
     };
     /**
-     * Retrieves this directory as per exclude/include filters.
-     * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
-     * @param opts.include Include only artifacts that match the given pattern (e.g., ["app/", "package.*"]).
+     * Return a snapshot with some paths included or excluded
+     * @param opts.exclude If set, paths matching one of these glob patterns is excluded from the new snapshot. Example: ["node_modules/", ".git*", ".env"]
+     * @param opts.include If set, only paths matching one of these glob patterns is included in the new snapshot. Example: (e.g., ["app/", "package.*"]).
      */
     filter = (opts) => {
         const ctx = this._ctx.select("filter", { ...opts });
@@ -1500,8 +1520,6 @@ export class Directory extends BaseClient {
      * Opens an interactive terminal in new container with this directory mounted inside.
      * @param opts.cmd If set, override the container's default terminal command and invoke these command arguments instead.
      * @param opts.experimentalPrivilegedNesting Provides Dagger access to the executed command.
-     *
-     * Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
      * @param opts.insecureRootCapabilities Execute the command with all root capabilities. This is similar to running a command with "sudo" or executing "docker run" with the "--privileged" flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.
      * @param opts.container If set, override the default container used for the terminal.
      */
@@ -1510,7 +1528,7 @@ export class Directory extends BaseClient {
         return new Directory(ctx);
     };
     /**
-     * Retrieves this directory plus a directory written at the given path.
+     * Return a snapshot with a directory added
      * @param path Location of the written directory (e.g., "/src/").
      * @param directory Identifier of the directory to copy.
      * @param opts.exclude Exclude artifacts that match the given pattern (e.g., ["node_modules/", ".git*"]).
@@ -1550,10 +1568,10 @@ export class Directory extends BaseClient {
         return new Directory(ctx);
     };
     /**
-     * Retrieves this directory plus a new file written at the given path.
-     * @param path Location of the written file (e.g., "/file.txt").
-     * @param contents Content of the written file (e.g., "Hello world!").
-     * @param opts.permissions Permission given to the copied file (e.g., 0600).
+     * Return a snapshot with a new file added
+     * @param path Path of the new file. Example: "foo/bar.txt"
+     * @param contents Contents of the new file. Example: "Hello world!"
+     * @param opts.permissions Permissions of the new file. Example: 0600
      */
     withNewFile = (path, contents, opts) => {
         const ctx = this._ctx.select("withNewFile", { path, contents, ...opts });
@@ -1570,24 +1588,24 @@ export class Directory extends BaseClient {
         return new Directory(ctx);
     };
     /**
-     * Retrieves this directory with the directory at the given path removed.
-     * @param path Location of the directory to remove (e.g., ".github/").
+     * Return a snapshot with a subdirectory removed
+     * @param path Path of the subdirectory to remove. Example: ".github/workflows"
      */
     withoutDirectory = (path) => {
         const ctx = this._ctx.select("withoutDirectory", { path });
         return new Directory(ctx);
     };
     /**
-     * Retrieves this directory with the file at the given path removed.
-     * @param path Location of the file to remove (e.g., "/file.txt").
+     * Return a snapshot with a file removed
+     * @param path Path of the file to remove (e.g., "/file.txt").
      */
     withoutFile = (path) => {
         const ctx = this._ctx.select("withoutFile", { path });
         return new Directory(ctx);
     };
     /**
-     * Retrieves this directory with the files at the given paths removed.
-     * @param paths Location of the file to remove (e.g., ["/file.txt"]).
+     * Return a snapshot with files removed
+     * @param paths Paths of the files to remove (e.g., ["/file.txt"]).
      */
     withoutFiles = (paths) => {
         const ctx = this._ctx.select("withoutFiles", { paths });
@@ -2381,6 +2399,7 @@ export class Env extends BaseClient {
      * Create or update an input value of type string
      * @param name The name of the binding
      * @param value The string value to assign to the binding
+     * @param description The description of the input
      */
     withStringInput = (name, value, description) => {
         const ctx = this._ctx.select("withStringInput", {
@@ -2390,6 +2409,15 @@ export class Env extends BaseClient {
         });
         return new Env(ctx);
     };
+    /**
+     * Create or update an input value of type string
+     * @param name The name of the binding
+     * @param description The description of the output
+     */
+    withStringOutput = (name, description) => {
+        const ctx = this._ctx.select("withStringOutput", { name, description });
+        return new Env(ctx);
+    };
     /**
      * Call the provided function with current Env.
      *
@@ -3377,6 +3405,7 @@ export class Host extends BaseClient {
      * The file is limited to a size of 512000 bytes.
      * @param name The user defined name for this secret.
      * @param path Location of the file to set as a secret.
+     * @deprecated setSecretFile is superceded by use of the secret API with file:// URIs
      */
     setSecretFile = (name, path) => {
         const ctx = this._ctx.select("setSecretFile", { name, path });
@@ -3714,6 +3743,13 @@ export class LLM extends BaseClient {
         const ctx = this._ctx.select("withSystemPrompt", { prompt });
         return new LLM(ctx);
     };
+    /**
+     * Disable the default system prompt
+     */
+    withoutDefaultSystemPrompt = () => {
+        const ctx = this._ctx.select("withoutDefaultSystemPrompt");
+        return new LLM(ctx);
+    };
     /**
      * Call the provided function with current LLM.
      *
@@ -4480,6 +4516,14 @@ export class ModuleSource extends BaseClient {
         const ctx = this._ctx.select("withUpdateDependencies", { dependencies });
         return new ModuleSource(ctx);
     };
+    /**
+     * Remove a client from the module source.
+     * @param path The path of the client to remove.
+     */
+    withoutClient = (path) => {
+        const ctx = this._ctx.select("withoutClient", { path });
+        return new ModuleSource(ctx);
+    };
     /**
      * Remove the provided dependencies from the module source's dependency list.
      * @param dependencies The dependencies to remove.
@@ -4695,10 +4739,10 @@ export class Client extends BaseClient {
         return new CacheVolume(ctx);
     };
     /**
-     * Creates a scratch container.
+     * Creates a scratch container, with no image or metadata.
      *
-     * Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
-     * @param opts.platform Platform to initialize the container with.
+     * To pull an image, follow up with the "from" function.
+     * @param opts.platform Platform to initialize the container with. Defaults to the native platform of the current engine
      */
     container = (opts) => {
         const ctx = this._ctx.select("container", { ...opts });
@@ -4753,6 +4797,8 @@ export class Client extends BaseClient {
     /**
      * Initialize a new environment
      * @param opts.privileged Give the environment the same privileges as the caller: core API including host access, current module, and dependencies
+     * @param opts.writable Allow new outputs to be declared and saved in the environment
+     * @experimental
      */
     env = (opts) => {
         const ctx = this._ctx.select("env", { ...opts });
@@ -4818,6 +4864,7 @@ export class Client extends BaseClient {
      * Initialize a Large Language Model (LLM)
      * @param opts.model Model to use
      * @param opts.maxAPICalls Cap the number of API calls for this LLM
+     * @experimental
      */
     llm = (opts) => {
         const ctx = this._ctx.select("llm", { ...opts });
@@ -5096,13 +5143,6 @@ export class Client extends BaseClient {
         const ctx = this._ctx.select("loadSecretFromID", { id });
         return new Secret(ctx);
     };
-    /**
-     * Load a Secret from its Name.
-     */
-    loadSecretFromName = (name, opts) => {
-        const ctx = this._ctx.select("loadSecretFromName", { name, ...opts });
-        return new Secret(ctx);
-    };
     /**
      * Load a Service from its ID.
      */