# Buildah Module

The Buildah module provides functions for working with containers and images using the Buildah tool. Buildah helps you create and manage container images.

## Image Information

### Image Properties

When working with images, you can access the following information:

- `id`: The unique identifier for the image
- `names`: A list of names/tags for the image
- `name`: The primary name of the image, or `<none>` if the image has no names
- `size`: The size of the image
- `created`: When the image was created

## Container Functions

### `bah_from(image)`

Creates a container from an image.

**Parameters:**
- `image` (string): The name or ID of the image to create the container from

**Returns:** The ID of the newly created container if successful.

**Example:**

```rhai
// Create a container from an image
let result = bah_from("alpine:latest");
let container_id = result.stdout;
print(`Created container: ${container_id}`);
```

### `bah_run(container, command)`

Runs a command in a container.

**Parameters:**
- `container` (string): The container ID or name
- `command` (string): The command to run

**Returns:** The output of the command if successful.

**Example:**
```rhai
// Run a command in a container
let result = bah_run("my-container", "echo 'Hello from container'");
print(result.stdout);
```

### `bah_run_with_isolation(container, command, isolation)`

Runs a command in a container with specified isolation.

**Parameters:**
- `container` (string): The container ID or name
- `command` (string): The command to run
- `isolation` (string): The isolation type (e.g., "chroot", "rootless", "oci")

**Returns:** The output of the command if successful.

**Example:**
```rhai
// Run a command with specific isolation
let result = bah_run_with_isolation("my-container", "ls -la", "chroot");
print(result.stdout);
```

### `bah_copy(container, source, dest)`

Copies files into a container.

**Parameters:**
- `container` (string): The container ID or name
- `source` (string): The source path on the host
- `dest` (string): The destination path in the container

**Returns:** A success message if the copy operation worked.

**Example:**
```rhai
// Copy a file into a container
bah_copy("my-container", "./app.js", "/app/app.js");
```

### `bah_add(container, source, dest)`

Adds files into a container. Similar to `bah_copy` but can also handle remote URLs.

**Parameters:**
- `container` (string): The container ID or name
- `source` (string): The source path on the host or a URL
- `dest` (string): The destination path in the container

**Returns:** A success message if the add operation worked.

**Example:**
```rhai
// Add a file from a URL into a container
bah_add("my-container", "https://example.com/file.tar.gz", "/app/");
```

### `bah_commit(container, image_name)`

Commits a container to an image.

**Parameters:**
- `container` (string): The container ID or name
- `image_name` (string): The name to give the new image

**Returns:** A success message if the commit operation worked.

**Example:**
```rhai
// Commit a container to an image
bah_commit("my-container", "my-image:latest");
```

### `bah_remove(container)`

Removes a container.

**Parameters:**
- `container` (string): The container ID or name

**Returns:** A success message if the container was removed.

**Example:**
```rhai
// Remove a container
bah_remove("my-container");
```

### `bah_list()`

Lists containers.

**Returns:** A list of containers if successful.

**Example:**
```rhai
// List containers
let result = bah_list();
print(result.stdout);
```

### `bah_new_build_options()`

Creates a new map with default build options.

**Returns:** A map with the following default options:
- `tag` (unit/null): The tag for the image (default: null)
- `context_dir` (string): The build context directory (default: ".")
- `file` (string): The Dockerfile path (default: "Dockerfile")
- `isolation` (unit/null): The isolation type (default: null)

**Example:**
```rhai
// Create build options
let options = bah_new_build_options();
```

### `bah_build(options)`

Builds an image with options specified in a map.

**Parameters:**
- `options` (map): A map of options created with `bah_new_build_options()`

**Returns:** A success message if the build operation worked.

**Example:**
```rhai
// Create and customize build options
let options = bah_new_build_options();
options.tag = "my-image:latest";
options.context_dir = "./app";
options.file = "Dockerfile.prod";
options.isolation = "chroot";

// Build an image with options
let result = bah_build(options);
```

## Image Functions

### `bah_images()`

Lists images in local storage.

**Returns:** A list of images if successful.

**Example:**
```rhai
// List images
let images = bah_images();

// Display image information
for image in images {
    print(`ID: ${image.id}, Name: ${image.name}, Size: ${image.size}, Created: ${image.created}`);
}
```


### `bah_image_remove(image)`

Removes one or more images.

**Parameters:**
- `image` (string): The image ID or name

**Returns:** A success message if the image was removed.

**Example:**
```rhai
// Remove an image
bah_image_remove("my-image:latest");
```

### `bah_image_push(image, destination, tls_verify)`

Pushes an image to a registry.

**Parameters:**
- `image` (string): The image ID or name
- `destination` (string): The destination registry/repository
- `tls_verify` (boolean): Whether to verify TLS certificates

**Returns:** A success message if the image was pushed.

**Example:**
```rhai
// Push an image to a registry
bah_image_push("my-image:latest", "registry.example.com/my-repo/my-image:latest", true);
```

### `bah_image_tag(image, new_name)`

Adds an additional name to a local image.

**Parameters:**
- `image` (string): The image ID or name
- `new_name` (string): The new name to add

**Returns:** A success message if the image was tagged.

**Example:**
```rhai
// Tag an image with a new name
bah_image_tag("my-image:latest", "my-image:v1.0");
```

### `bah_image_pull(image, tls_verify)`

Pulls an image from a registry.

**Parameters:**
- `image` (string): The image to pull
- `tls_verify` (boolean): Whether to verify TLS certificates

**Returns:** A success message if the image was pulled.

**Example:**
```rhai
// Pull an image from a registry
bah_image_pull("alpine:latest", true);
```

### `bah_new_commit_options()`

Creates a new map with default commit options.

**Returns:** A map with the following default options:
- `format` (unit/null): The format of the image (default: null)
- `squash` (boolean): Whether to squash layers (default: false)
- `rm` (boolean): Whether to remove the container after commit (default: false)

**Example:**
```rhai
// Create commit options
let options = bah_new_commit_options();
```

### `bah_image_commit(container, image_name, options)`

Commits a container to an image with options specified in a map.

**Parameters:**
- `container` (string): The container ID or name
- `image_name` (string): The name to give the new image
- `options` (map): A map of options created with `bah_new_commit_options()`

**Returns:** A success message if the image was created.

**Example:**
```rhai
// Create and customize commit options
let options = bah_new_commit_options();
options.format = "docker";
options.squash = true;
options.rm = true;

// Commit a container to an image with options
let result = bah_image_commit("my-container", "my-image:latest", options);
```

### `bah_new_config_options()`

Creates a new map for config options.

**Returns:** An empty map to be filled with configuration options.

**Example:**
```rhai
// Create config options
let options = bah_new_config_options();
```

### `bah_config(container, options)`

Configures a container with options specified in a map.

**Parameters:**
- `container` (string): The container ID or name
- `options` (map): A map of options created with `bah_new_config_options()`

**Returns:** A success message if the container was configured.

**Example:**
```rhai
// Create and customize config options
let options = bah_new_config_options();
options.author = "John Doe";
options.cmd = "echo Hello";
options.entrypoint = "/bin/sh -c";
options.workingdir = "/app";
options.env = "NODE_ENV=production";
options.label = "version=1.0";

// Configure a container with options
let result = bah_config("my-container", options);
```