# Ansible Role: Scriptorium

Installs and configures [Scriptorium](https://gitea.maximumdirect.net/eric/scriptorium)
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
facts and uses privilege escalation only for dependency installation and
root-owned application state.

## Variables

```yaml
scriptorium_version: v0.15.0
scriptorium_repository_url: https://gitea.maximumdirect.net/eric/scriptorium.git
scriptorium_source_dir: /usr/local/src/scriptorium
scriptorium_binary_path: /usr/local/bin/scriptorium
scriptorium_manage_build_dependencies: true
scriptorium_go_snap_channel: 1.26/stable
scriptorium_go_binary: /snap/bin/go
scriptorium_config_path: /usr/local/etc/scriptorium/config.yml
scriptorium_config_owner: root
scriptorium_config_group: root
scriptorium_config_directory_mode: "0755"
scriptorium_config_file_mode: "0644"
scriptorium_configkit_imports: null
scriptorium_prompt_dir: null
scriptorium_profile_dir: null
scriptorium_schema_dir: null
scriptorium_server_addr: null
scriptorium_server_artifact_root: null
scriptorium_server_max_request_bytes: null
scriptorium_server_max_artifact_bytes: null
scriptorium_server_max_response_bytes: null
scriptorium_defaults_render_format: null
scriptorium_backends: null
scriptorium_transient_retries: null
```

When `scriptorium_manage_build_dependencies` is `false`, Git and the executable
selected by `scriptorium_go_binary` must already be available. Otherwise, the
role installs Git with APT and the classic Go Snap from
`scriptorium_go_snap_channel`. It checks out `scriptorium_version`
authoritatively, builds `./cmd/scriptorium` directly to
`scriptorium_binary_path`, and rebuilds only when that checkout changes or the
binary is absent. The source tree is recursively owned by `root:root`; the
binary is `root:root` mode `0755`.

Every application configuration variable defaults to `null`, so it and any
empty parent section are omitted and Scriptorium retains ownership of its
built-in defaults. When no values are selected, the role writes `{}` to
`scriptorium_config_path`. It manages that file and its parent directory with
`scriptorium_config_owner`, `scriptorium_config_group`,
`scriptorium_config_directory_mode`, and `scriptorium_config_file_mode`. The
standalone defaults are `root:root`, directory mode `0755`, and file mode
`0644`; composing roles may override this generic configuration interface.
Non-null falsey values are retained. `scriptorium_backends` is the native
mapping supplied by the caller; the role does not merge or rewrite it. For
example, inventory can compose fragments in the ordinary way:

```yaml
scriptorium_backends: "{{ scriptorium_local_backends | combine(scriptorium_remote_backends) }}"
```

Backend entries may name a credential environment variable through
`api_key_env`; credential values themselves belong outside this role. The role
does not install prompt, profile, or schema content and does not manage a
service.

`scriptorium_configkit_imports` accepts a list of native ConfigKit import
mappings. Paths and globs are interpreted by Scriptorium relative to the
configuration root; the caller supplies and owns the referenced files. For
example, an inventory may select a caller-managed fragment:

```yaml
scriptorium_configkit_imports:
  - path: fragments/server.yml
scriptorium_transient_retries: 0
```

Both settings are omitted when `null`. Setting `scriptorium_transient_retries`
to `0` disables additional transient attempts; omission leaves the retry
budget with Scriptorium and PromptKit. Leave these newer fields unset when
selecting an older Scriptorium version that does not support them.

## Example

```yaml
- hosts: scriptorium_hosts
  roles:
    - role: ansible-role-scriptorium
```

## Validation

The repository-local integration suite installs its pinned collection and runs
syntax checking and production-profile lint. It applies the default role, uses
an offline native profile inspection with the managed configuration, and then
requires clean repeated convergence. It also combines missing-binary recovery
with a caller-supplied Go executable while dependency management is disabled,
and covers one representative configuration with null omission, intentional
zero and false values, backend pass-through, and offline native inspection. It
mutates only the managed source, binary, configuration, and a private temporary
directory, then restores the default deployment during cleanup.

```sh
tests/integration
```