ftl2 0.1.0__tar.gz

ftl2-0.1.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(source:*)",
+      "Bash(pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)"
+    ]
+  }
+}

ftl2-0.1.0/.ftl2-state.json

@@ -0,0 +1,75 @@
+{
+  "version": 1,
+  "created_at": "2026-02-11T18:06:54.971737+00:00",
+  "updated_at": "2026-03-08T02:49:46.865282+00:00",
+  "hosts": {
+    "web01": {
+      "ansible_host": "192.168.1.10",
+      "ansible_port": 22,
+      "groups": [
+        "ungrouped"
+      ],
+      "added_at": "2026-03-08T02:49:46.857091+00:00"
+    },
+    "db01": {
+      "ansible_host": "192.168.1.20",
+      "ansible_port": 2222,
+      "groups": [
+        "databases",
+        "production"
+      ],
+      "added_at": "2026-03-08T02:49:46.857669+00:00",
+      "ansible_user": "admin",
+      "db_type": "postgres"
+    },
+    "myhost.example.com": {
+      "ansible_host": "myhost.example.com",
+      "ansible_port": 22,
+      "groups": [
+        "ungrouped"
+      ],
+      "added_at": "2026-03-08T02:49:46.858186+00:00"
+    },
+    "host01": {
+      "ansible_host": "host01",
+      "ansible_port": 22,
+      "groups": [
+        "newgroup"
+      ],
+      "added_at": "2026-02-11T18:06:54.975470+00:00"
+    },
+    "web02": {
+      "ansible_host": "192.168.1.11",
+      "ansible_port": 22,
+      "groups": [
+        "webservers"
+      ],
+      "added_at": "2026-03-08T02:49:46.858685+00:00"
+    },
+    "lonely": {
+      "ansible_host": "10.0.0.1",
+      "ansible_port": 22,
+      "groups": [
+        "ungrouped"
+      ],
+      "added_at": "2026-03-08T02:49:46.859195+00:00"
+    },
+    "newhost": {
+      "ansible_host": "10.0.0.5",
+      "ansible_port": 22,
+      "groups": [
+        "ungrouped"
+      ],
+      "added_at": "2026-03-08T02:49:46.859768+00:00"
+    },
+    "localtest": {
+      "ansible_host": "localhost",
+      "ansible_port": 22,
+      "groups": [
+        "testgroup"
+      ],
+      "added_at": "2026-03-08T02:49:46.865275+00:00"
+    }
+  },
+  "resources": {}
+}

ftl2-0.1.0/.gitignore

@@ -0,0 +1,159 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/
+uv.lock
+tests/ssh_test_config/
+
+# FTL2 build artifacts
+.ftl2-deps.txt
+.ftl2-modules.txt
+*.pyz

ftl2-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# FTL2 Development History
+
+## Foundation (Feb 5)
+
+Core architecture: typed dataclasses for host/inventory config, Strategy-pattern runner (local vs remote), gate communication protocol for remote execution, variable reference system, argument merging, CLI with subcommands.
+
+## FTL Modules (Feb 6)
+
+In-process Ansible module execution — the core performance win. FQCN parser resolves `community.general.slack` to actual module files. Dependency detector finds Python requirements from module DOCUMENTATION strings. Bundle builder packages modules + module_utils into self-contained zipapps. Async executor runs modules as Python functions instead of subprocesses. 3-17x faster than `ansible-playbook`.
+
+## Event Streaming (Feb 6)
+
+Real-time event protocol between gate and controller. Event types: module start/complete, file changes (inotify), system metrics (CPU/memory/disk). Rich TUI for progress display. `await ftl.listen()` for persistent monitoring.
+
+## Automation Context API (Feb 6-7)
+
+The developer-facing interface:
+
+```python
+async with automation(inventory="hosts.yml", secret_bindings={...}) as ftl:
+    await ftl.file(path="/tmp/test", state="directory")
+    await ftl.run_on("webservers", "dnf", name="nginx", state="present")
+```
+
+Features: secret bindings (auto-inject credentials, never visible in logs), host-scoped proxies (`ftl["hostname"].module()`), bracket notation for host names with dashes, `add_host()` for dynamic provisioning workflows, check mode, fail_fast, per-host summary printing.
+
+## Gate System (Feb 7)
+
+Remote execution via SSH gate process. Gate builder creates cached zipapps with baked-in modules. FTL modules sent by name (gate has them), Ansible modules sent as bundles. Gate protocol supports debug commands (Info, ListModules). SSH subsystem registration eliminates shell startup overhead. Gates cached in `~/.ftl` per user.
+
+## Native Modules (Feb 7-8)
+
+FTL-native implementations for hot-path modules: `copy` (with file transfer), `template`, `fetch`, `shell`, `swap`, `ping`, `wait_for`. Native modules skip the Ansible module machinery entirely.
+
+## State Management (Feb 7)
+
+State file (`.ftl2-state.json`) tracks dynamically provisioned hosts and resources. `add_host()` persists immediately. Hosts loaded from state on context enter — enables crash recovery and idempotent provisioning. State exposed to automation scripts via `ftl.state`.
+
+## Dependency Management (Feb 7)
+
+`auto_install_deps` installs missing Python packages with `uv` at runtime. `record_deps` captures requirements during execution and writes to `.ftl2-deps.txt`. Module names tracked in `.ftl2-modules.txt` for gate building.
+
+## Audit & Replay (Feb 8)
+
+`record="audit.json"` captures every module execution with timestamps, durations, parameters (secrets redacted), and results. `replay="audit.json"` skips successful actions from a previous run, resuming from the first failure. Enables crash recovery without re-running completed work.
+
+## Policy Engine (Feb 11)
+
+YAML-based rules evaluated before every module execution. Match conditions: `module` (fnmatch), `host`, `environment`, `param.<name>`. First matching deny rule raises `PolicyDeniedError`. Integrated into both `execute()` (local) and `_execute_on_host()` (remote). `Policy.empty()` for backward compatibility.
+
+## JSON Inventory & Inventory Scripts (Feb 11)
+
+`load_inventory()` auto-detects format: executable scripts (run with `--list`), JSON (Ansible `ansible-inventory --list` format with `_meta.hostvars`), or YAML. Enables dynamic inventory from cloud providers without reimplementing inventory plugins — just shell out to `ansible-inventory` and pass the JSON to FTL2.
+
+## Vault Secrets (Feb 11)
+
+HashiCorp Vault KV v2 support via `vault_secrets` parameter. Maps names to `path#field` references, resolved at context startup, accessible via `ftl.secrets["NAME"]` alongside env var secrets. Uses standard `VAULT_ADDR`/`VAULT_TOKEN` env vars. Reads grouped by path to minimize API calls. `hvac` is an optional dependency (`pip install ftl2[vault]`). Works with `secret_bindings` for auto-injection of vault-sourced credentials.

ftl2-0.1.0/CLAUDE.md

@@ -0,0 +1,311 @@
+# CLAUDE.md
+
+## What This Is
+
+FTL2 is a Python automation framework that runs Ansible modules in-process instead of as subprocesses. It provides an `async with automation()` context manager that gives Python scripts direct access to the entire Ansible module ecosystem — 3-17x faster than `ansible-playbook`.
+
+## Installation
+
+**Preferred: Use `uv run` with PEP 723 inline metadata (no install needed):**
+
+Add this header to any script and `uv run` handles everything:
+```python
+#!/usr/bin/env python3
+# /// script
+# dependencies = [
+#     "ftl2 @ git+https://github.com/benthomasson/ftl2",
+# ]
+# requires-python = ">=3.13"
+# ///
+```
+
+Then run directly:
+```bash
+uv run my_script.py
+```
+
+**Alternative: Install the CLI tool globally:**
+```bash
+uvx --from "git+https://github.com/benthomasson/ftl2" ftl2
+```
+
+Both pull ftl2 and all dependencies (`ftl-module-utils`, `ftl-builtin-modules`, `ftl-collections`, `asyncssh`, `httpx`, etc.) directly from GitHub.
+
+## The Pattern
+
+```python
+import asyncio
+from ftl2 import automation
+
+async def main():
+    async with automation(
+        secret_bindings={
+            "community.general.linode_v4": {
+                "access_token": "LINODE_TOKEN",
+                "root_pass": "LINODE_ROOT_PASS",
+            },
+        }
+    ) as ftl:
+        await ftl.file(path="/tmp/test", state="directory")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Module Names
+
+Use the same Ansible module names and parameters:
+
+```python
+# Short names for builtin modules
+await ftl.file(path="/tmp/test", state="touch")
+await ftl.copy(src="config.yml", dest="/etc/app/config.yml")
+await ftl.command(cmd="echo hello")
+await ftl.service(name="nginx", state="restarted")
+await ftl.template(src="app.conf.j2", dest="/etc/app.conf")
+
+# FQCN for collection modules
+await ftl.community.general.linode_v4(label="web01", type="g6-standard-1", ...)
+await ftl.community.general.slack(channel="#ops", msg="Done!")
+await ftl.ansible.posix.authorized_key(user="ben", key=ssh_key)
+await ftl.ansible.posix.firewalld(port="80/tcp", state="enabled")
+```
+
+## Secret Bindings
+
+Secrets are configured once and injected automatically:
+
+```python
+async with automation(
+    secret_bindings={
+        "community.general.linode_v4": {
+            "access_token": "LINODE_TOKEN",
+            "root_pass": "LINODE_ROOT_PASS",
+        },
+        "community.general.slack": {"token": "SLACK_TOKEN"},
+        "uri": {"bearer_token": "API_TOKEN"},
+    }
+) as ftl:
+    # No credentials in the code - injected from environment
+    await ftl.local.community.general.linode_v4(label="web01", ...)
+
+    # bearer_token injected automatically, redacted in audit logs
+    await ftl.local.uri(
+        url="https://api.example.com/data",
+        body={"key": "value"},
+        body_format="json",
+    )
+```
+
+## Targeting Hosts and Groups
+
+```python
+async with automation(inventory="inventory.yml") as ftl:
+    # Local execution (for cloud/API modules)
+    await ftl.local.community.general.linode_v4(label="web01", ...)
+
+    # Target a group
+    await ftl.webservers.service(name="nginx", state="restarted")
+
+    # Target a specific host
+    await ftl.db01.command(cmd="pg_dump mydb")
+```
+
+## State File Tracking
+
+```python
+async with automation(state_file=".ftl2-state.json") as ftl:
+    if ftl.state.has("web01"):
+        resource = ftl.state.get("web01")
+        print(f"Server exists: {resource['ipv4'][0]}")
+    else:
+        server = await ftl.local.community.general.linode_v4(label="web01", ...)
+        ftl.state.add("web01", {
+            "provider": "linode",
+            "id": server["instance"]["id"],
+            "ipv4": server["instance"]["ipv4"],
+        })
+        ftl.add_host(
+            hostname="web01",
+            ansible_host=server["instance"]["ipv4"][0],
+            ansible_user="root",
+            groups=["webservers"],
+        )
+```
+
+State operations:
+```python
+ftl.state.has("web01")          # Check existence
+ftl.state.get("web01")          # Get resource dict
+ftl.state.add("web01", {...})   # Add resource (persists immediately)
+ftl.state.remove("web01")       # Remove resource
+ftl.state.resources()           # List all resource names
+ftl.state.hosts()               # List all host names
+```
+
+## Return Types
+
+**Local execution** returns a `dict`:
+```python
+server = await ftl.local.community.general.linode_v4(label="web01", ...)
+ip = server["instance"]["ipv4"][0]
+```
+
+**Remote execution** returns `list[ExecuteResult]`:
+```python
+results = await ftl.webservers.command(cmd="uptime")
+for result in results:
+    print(f"{result.host}: {result.output}")
+```
+
+## Safety Features
+
+```python
+# Check mode - preview without executing
+async with automation(check_mode=True) as ftl:
+    await ftl.file(path="/etc/important", state="absent")
+
+# Fail fast - stop on first error
+async with automation(fail_fast=True) as ftl:
+    await ftl.file(...)
+```
+
+## Gate Modules (Pre-built Remote Execution)
+
+```python
+async with automation(
+    gate_modules="auto",      # Read from .ftl2-modules.txt, or record on first run
+    record_deps=True,         # Record modules to .ftl2-modules.txt
+) as ftl:
+    await ftl.webservers.dnf(name="nginx", state="present")
+```
+
+First run records modules; subsequent runs bake them into the gate for faster execution.
+
+## Audit Recording
+
+```python
+async with automation(record="audit.json") as ftl:
+    await ftl.file(path="/tmp/test", state="directory")
+# Writes audit.json with all actions, timestamps, durations
+# Secret-injected params are excluded
+```
+
+## Common Gotchas
+
+### Bootstrap python3-dnf on Fedora
+```python
+await host.command(cmd="dnf install -y python3-dnf")  # Before any dnf calls
+await host.dnf(name="nginx", state="present")
+```
+
+### `user` module: `group` vs `groups`
+```python
+# WRONG - changes primary group
+await host.user(name="ben", group="wheel")
+# RIGHT - adds supplementary group
+await host.user(name="ben", groups=["wheel"])
+```
+
+### Some modules require FQCN
+```python
+# WRONG - not in ansible.builtin
+await host.authorized_key(user="ben", key=ssh_key)
+# RIGHT
+await host.ansible.posix.authorized_key(user="ben", key=ssh_key)
+```
+
+| Module | FQCN |
+|--------|------|
+| `authorized_key` | `ansible.posix.authorized_key` |
+| `firewalld` | `ansible.posix.firewalld` |
+| `slack` | `community.general.slack` |
+| `linode_v4` | `community.general.linode_v4` |
+
+### `swap` module: string size
+```python
+await host.swap(path="/swapfile", size="1G")  # String, not int
+```
+
+### No Jinja2 or Lookup Plugins
+```python
+# WRONG
+key="{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
+# RIGHT
+from pathlib import Path
+key = (Path.home() / ".ssh" / "id_rsa.pub").read_text().strip()
+```
+
+### .gitignore
+```
+.ftl2-state.json
+.ftl2-deps.txt
+.ftl2-modules.txt
+*.pyz
+audit.json
+```
+
+---
+
+## Project Structure (for developers)
+
+```
+src/ftl2/
+    automation/         # AutomationContext, ModuleProxy — the async with automation() API
+        context.py      # Main context manager, execute(), secret_bindings, record
+        proxy.py        # Host/group proxy for ftl.webservers.dnf() syntax
+        __init__.py     # automation() wrapper function
+    ftl_modules/        # FTL-native module implementations (in-process, no subprocess)
+        http.py         # ftl_uri, ftl_get_url (httpx-based)
+        executor.py     # ExecuteResult dataclass, FTL module dispatcher
+        swap.py, pip.py # Other native modules
+    ftl_gate/           # Remote execution gate (.pyz zipapp)
+        __main__.py     # Gate-side: receives modules over stdin, executes, returns results
+    state/              # State management
+        state.py        # State class for .ftl2-state.json
+        execution.py    # ExecutionState for CLI run tracking
+    gate.py             # Gate builder — creates .pyz with baked-in modules
+    runners.py          # SSH connection, gate deployment, remote module execution
+    cli.py              # Click CLI (ftl2 command)
+    ssh.py              # SSH host abstraction
+    inventory.py        # Inventory loading (YAML)
+    builder.py          # ftl-gate-builder entry point
+```
+
+## Key Abstractions
+
+- **AutomationContext** (`automation/context.py`) — the core. Manages inventory, secrets, module execution, state, and recording
+- **ModuleProxy** (`automation/proxy.py`) — translates `ftl.webservers.dnf()` into `context.execute("dnf", hosts, params)`
+- **Gate** (`gate.py` + `ftl_gate/`) — .pyz zipapp deployed to remote hosts for module execution
+- **ExecuteResult** (`ftl_modules/executor.py`) — dataclass returned from every module call
+
+## How Module Execution Works
+
+1. Script calls `await ftl.webservers.dnf(name="nginx", state="present")`
+2. ModuleProxy resolves `webservers` to a host group and `dnf` to a module name
+3. AutomationContext injects secret_bindings, captures original params for audit
+4. For local: module runs in-process via Ansible's module machinery
+5. For remote: module is sent to the gate over SSH stdin, gate executes and returns result
+6. Result is stored in `_results` list for audit recording
+
+## Development Commands
+
+```bash
+pytest                          # Run tests
+pytest tests/test_automation.py # Run specific test
+ruff check src/                 # Lint
+ruff format src/                # Format
+mypy src/ftl2                   # Type check
+```
+
+## Dependencies
+
+- `asyncssh` — SSH connections
+- `httpx` — async HTTP (used by ftl_uri)
+- `click` — CLI
+- `pyyaml` — inventory parsing
+- `jinja2` — template module
+- `rich` — CLI output
+- `ftl-module-utils` — Ansible module_utils extracted for standalone use
+- `ftl-builtin-modules` — Ansible builtin modules extracted
+- `ftl-collections` — Community collection module_utils (community.general, amazon.aws, etc.)