chore: initial commit

docs/examples.md

@@ -0,0 +1,84 @@
+# Examples
+
+See the `examples` directory in the repo.
+
+## Task Examples
+
+### File Operations
+
+```nix
+{
+  name = "Create configuration";
+  template = {
+    src = "nginx.conf.j2";
+    dest = "/etc/nginx/nginx.conf";
+    backup = true;
+  };
+  notify = "restart nginx";
+}
+```
+
+### Service Management
+
+```nix
+{
+  name = "Start services";
+  service = {
+    name = "{{ item }}";
+    state = "started";
+    enabled = true;
+  };
+  loop = ["nginx" "postgresql"];
+}
+```
+
+### Conditional Tasks
+
+```nix
+{
+  name = "Install SSL certificate";
+  copy = {
+    src = "ssl/cert.pem";
+    dest = "/etc/ssl/certs/";
+  };
+  when = "ssl_enabled | default(false)";
+}
+```
+
+### Block Tasks
+
+```nix
+{
+  block = [
+    {
+      name = "Create user";
+      user = {
+        name = "deploy";
+        state = "present";
+      };
+    }
+    {
+      name = "Set up SSH key";
+      authorized_key = {
+        user = "deploy";
+        key = "{{ ssh_public_key }}";
+      };
+    }
+  ];
+  rescue = [
+    {
+      name = "Log error";
+      debug.msg = "Failed to create user";
+    }
+  ];
+  always = [
+    {
+      name = "Cleanup";
+      file = {
+        path = "/tmp/setup";
+        state = "absent";
+      };
+    }
+  ];
+}
+```

docs/index.md

@@ -0,0 +1,60 @@
+# Introduction
+
+Nixible is a Nix-based tool for managing Ansible playbooks with type safety and reproducibility.
+
+## What is Nixible?
+
+Nixible bridges the Nix and Ansible ecosystems by allowing you to define Ansible playbooks, inventories, and collections as Nix expressions. It provides:
+
+- **Type-safe playbook definitions** using Nix's module system
+- **Reproducible Ansible environments** with locked dependencies
+- **Automatic collection management** from Ansible Galaxy
+
+## Quick Start
+
+### 1. Define your configuration
+
+Create a `some-playbook.nix` file:
+
+```nix title="some-playbook.nix"
+{pkgs, ...}: {
+  collections = {
+    "community-general" = {
+      version = "8.0.0";
+      hash = "sha256-...";
+    };
+  };
+  
+  inventory = {}; # can also be omitted, we only use localhost
+  
+  playbook = [{
+    name = "Hello World";
+    hosts = "localhost";
+    tasks = [{
+      name = "Say hello";
+      debug.msg = "Hello from Nixible!";
+    }];
+  }];
+}
+```
+
+### 2. Run with Nix
+
+```nix title="flake.nix"
+{
+  inputs.nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  # outputs = ...
+  # nixible_lib = inputs.nixible.lib { inherit pkgs lib; };
+  packages.some-playbook = nixible_lib.mkNixibleCli ./some-playbook.nix;
+}
+```
+
+```bash
+nix run .#some-playbook
+```
+
+## Getting Started
+
+1. **[Usage](usage.md)** - Learn how to build and run Nixible configurations
+1. **[Examples](examples.md)** - See real-world usage patterns
+1. **[Reference](reference.md)** - Detailed API and configuration reference

docs/reference.md

@@ -0,0 +1,215 @@
+# Reference
+
+## `flakeModule`
+
+The `flakeModule` for [flake-parts](https://flake.parts).
+
+Provides a `perSystem.nixible` option for defining Nixible configurations directly in your flake.
+
+```nix
+{
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  };
+  
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ nixible.flakeModule ];
+      systems = # ...
+
+      perSystem = { pkgs, ... }: {
+        nixible = {
+          "deploy" = {
+            dependencies = [ pkgs.rsync ];
+            playbook = [{
+              name = "Deploy application";
+              hosts = "servers";
+              tasks = [ /* ... */ ];
+            }];
+          };
+          "backup" = {
+            dependencies = [ pkgs.borg ];
+            playbook = [{
+              name = "Backup data";
+              hosts = "backup_servers";
+              tasks = [ /* ... */ ];
+            }];
+          };
+        };
+      };
+    };
+}
+```
+
+Each configuration defined in `perSystem.nixible` automatically creates a corresponding package in `legacyPackages` with the name `nixible:<config-name>`. These packages contain the CLI executable for that specific configuration.
+
+**Example usage:**
+
+```bash
+nix run .#nixible:deploy
+nix run .#nixible:backup
+```
+
+## `lib`
+
+### `module`
+
+The nix module for validation of Nixible configurations.
+Used internally by `mkNixible`.
+
+### `mkNixible`
+
+```nix
+mkNixible config
+```
+
+Creates a Nixible configuration module evaluation.
+`config` can be a path to a nix file or a function/attrset.
+
+**Noteworthy attributes**:
+
+- `config`: The evaluated configuration with all options
+- `config.inventoryFile`: Generated JSON inventory file
+- `config.playbookFile`: Generated YAML playbook file
+- `config.installedCollections`: Directory containing installed collections
+- `config.cli`: The nixible CLI executable
+
+### `mkNixibleCli`
+
+```nix
+mkNixibleCli config
+```
+
+Creates a CLI executable for your Nixible configuration.
+Basically `(mkNixible config).config.cli`.
+
+## Configuration Options
+
+### `ansiblePackage`
+
+**Type:** `package`
+**Default:** Custom ansible-core package
+
+The Ansible package to use. The default package is optimized for size, by not
+including the gazillion collections that `pkgs.ansible` and `pkgs.ansible-core` include.
+
+```nix
+ansiblePackage = pkgs.ansible;
+```
+
+### `collections`
+
+**Type:** `attrsOf collectionType`
+**Default:** `{}`
+
+Ansible collections to fetch from Galaxy.
+
+```nix
+collections = {
+  "community-general" = {
+    version = "8.0.0";
+    hash = "sha256-...";
+  };
+};
+```
+
+### `dependencies`
+
+**Type:** `listOf package`
+**Default:** `[]`
+
+Additional packages available at runtime.
+
+```nix
+dependencies = [pkgs.git pkgs.rsync];
+```
+
+### `inventory`
+
+**Type:** `attrs`
+**Default:** `{}`
+
+Ansible inventory as Nix data structure, converted to JSON.
+
+```nix
+inventory = {
+  webservers = {
+    hosts = {
+      web1 = { ansible_host = "192.168.1.10"; };
+    };
+    vars = {
+      http_port = 80;
+    };
+  };
+};
+```
+
+### `playbook`
+
+**Type:** `listOf playbookType`
+
+List of plays that make up the playbook.
+
+```nix
+playbook = [
+  {
+    name = "Configure servers";
+    hosts = "webservers";
+    become = true;
+    tasks = [
+      {
+        name = "Install nginx";
+        package = {
+          name = "nginx";
+          state = "present";
+        };
+      }
+    ];
+  }
+];
+```
+
+## Collection Type
+
+### `version`
+
+**Type:** `str`
+
+Version of the collection from Ansible Galaxy.
+
+### `hash`
+
+**Type:** `str`
+
+SHA256 hash of the collection tarball for verification.
+
+## Playbook Type
+
+### `name`
+
+**Type:** `str`
+
+Name of the play.
+
+### `hosts`
+
+**Type:** `str`
+
+Target hosts pattern (e.g., "all", "webservers", "localhost").
+
+### `become`
+
+**Type:** `bool`
+**Default:** `false`
+
+Whether to use privilege escalation.
+
+### `tasks`
+
+**Type:** `listOf attrs`
+**Default:** `[]`
+
+List of tasks to execute. Each task corresponds to Ansible task syntax.
+
+Standard Ansible playbook options are supported: `gather_facts`, `serial`, `vars`, `vars_files`, `tags`, `handlers`, `pre_tasks`, `post_tasks`, etc.

docs/usage.md

@@ -0,0 +1,119 @@
+# Usage
+
+Learn how to build and use Nixible configurations.
+
+## Using flakeModule
+
+The recommended way to use Nixible is with the flakeModule:
+
+```nix title="flake.nix"
+{
+  inputs = {
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  };
+  
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ nixible.flakeModule ];
+      systems = # ...
+
+      perSystem = { pkgs, ... }: {
+        nixible = {
+          deploy = {
+            dependencies = [ pkgs.rsync ];
+            inventory = {
+              webservers = {
+                hosts = {
+                  web1 = { ansible_host = "192.168.1.10"; };
+                };
+              };
+            };
+            playbook = [{
+              name = "Deploy application";
+              hosts = "webservers";
+              tasks = [{
+                name = "Deploy files";
+                copy = {
+                  src = "{{ pwd }}/dist/";
+                  dest = "/var/www/";
+                };
+              }];
+            }];
+          };
+        };
+      };
+    };
+    };
+  };
+}
+```
+
+Then run with:
+
+```bash
+nix run .#nixible:deploy
+
+# With ansible-playbook options
+nix run .#nixible:deploy -- --check --diff --limit web1
+```
+
+## Using the CLI directly
+
+You can also create CLI packages directly:
+
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    nixible.url = "gitlab:TECHNOFAB/nixible?dir=lib";
+  };
+  
+  outputs = { nixpkgs, nixible, ... }: let
+    pkgs = nixpkgs.legacyPackages.x86_64-linux;
+    lib = nixpkgs.lib;
+    nixible_lib = nixible.lib { inherit pkgs lib; };
+  in {
+    packages.x86_64-linux.deploy = nixible_lib.mkNixibleCli ./deploy.nix;
+  };
+}
+```
+
+Then run with:
+
+```bash
+nix run .#deploy
+
+# Dry run with diff
+nix run .#deploy -- --check --diff
+
+# Limit to specific hosts
+nix run .#deploy -- --limit webservers
+
+# Extra variables
+nix run .#deploy -- --extra-vars "env=production debug=true"
+# etc.
+```
+
+## Variables
+
+Nixible automatically provides these variables to your playbooks:
+
+- `pwd`: Current working directory when nixible is run
+- `git_root`: Git repository root (empty if not in a git repo)
+
+Use them in your playbooks:
+
+```nix
+playbook = [{
+  name = "Deploy from current directory";
+  hosts = "localhost";
+  tasks = [{
+    name = "Copy files";
+    copy = {
+      src = "{{ pwd }}/dist/";
+      dest = "/var/www/";
+    };
+  }];
+}];
+```