# bex-hooks-files

File-related hooks for **bex**. This package provides hooks to download, extract, and generate files.

## Usage
`bex-hooks-files` is available on PyPI.

Add the plugin package to the `requirements` section of your `bex` bootstrap header:

```yaml
# /// bootstrap
# requires-python: ">=3.11,<3.12"
# requirements: |
#   bex-hooks
#   bex-hooks-files
# entrypoint: bex_hooks.exec:main
# ///
```

Then enable the plugin in your configuration:
```yaml
config:
  plugins:
    - bex_hooks.hooks.files
```

## Hooks
### `files/archive`

Downloads an archive (zip or tar, including compressed variants) from a source URL and extracts it to a target directory.

#### Arguments

| Name          | Type   |    Default   | Description                                                             |
|---------------|--------|:------------:|-------------------------------------------------------------------------|
| `source`      | `str`  | *(required)* | URL to the archive file.                                                |
| `source_hash` | `str`  | *(required)* | Expected file hash (e.g. `sha256:<digest>`) for integrity verification. |
| `target`      | `str`  | *(required)* | Destination directory where the archive will be extracted.              |
| `format`      | `str`  | *(required)* | Archive format (e.g. `zip`, `tar`, `tar.gz`, `tar.xz`).                 |
| `keep_source` | `bool` | `True`       | If `False`, removes the downloaded archive after extraction.            |

#### Example

```yaml
hooks:
  - id: files/archive
    source: https://example.com/project.tar.gz
    source_hash: sha256:abc123...
    target: ./project
    format: tar.gz
    keep_source: false
```

### `files/download`

Downloads a file from a source URL to a target path.

#### Arguments

| Name          | Type   |    Default   | Description                                                             |
|---------------|--------|:------------:|-------------------------------------------------------------------------|
| `source`      | `str`  | *(required)* | URL to the file.                                                        |
| `source_hash` | `str`  | *(required)* | Expected file hash (e.g. `sha256:<digest>`) for integrity verification. |
| `target`      | `str`  | *(required)* | Destination file path.                                                  |
| `keep_source` | `bool` | `True`       | If `False`, removes the downloaded file after processing.               |

#### Example

```yaml
hooks:
  - id: files/download
    source: https://example.com/tool.bin
    source_hash: sha256:def456...
    target: ./bin/tool.bin
```

### `files/inline`

Creates a file at the specified target path using inline content.

#### Arguments

| Name      | Type  |    Default   | Description            |
|-----------|-------|:------------:|------------------------|
| `content` | `str` | *(required)* | File contents.         |
| `target`  | `str` | *(required)* | Destination file path. |

#### Example

```yaml
hooks:
  - id: files/inline
    target: ./config/example.txt
    content: |
      hello world
      this file was generated by bex
```
