cloudfall 0.2.0__tar.gz

cloudfall-0.2.0/.ansible-lint

@@ -0,0 +1,5 @@
+---
+profile: production
+exclude_paths:
+  - .venv/
+  - tmp/

cloudfall-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+---
+name: CI
+
+"on":
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type-check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Validate example state
+        run: uv run cloudfall config validate --project config/examples
+
+      - name: Render Ansible inventory
+        run: >-
+          uv run cloudfall-engine inventory render --project config/examples
+          --output tmp/ansible-inventory.json
+
+      - name: Ansible syntax checks
+        env:
+          ANSIBLE_CONFIG: engine/ansible/ansible.cfg
+        run: |
+          for playbook in baseline bootstrap data deploy domains health inspect logging restart rollback services time; do
+            uv run ansible-playbook --syntax-check \
+              --inventory config/examples/tmp/ansible-inventory.json \
+              "engine/ansible/playbooks/${playbook}.yml"
+          done
+
+      - name: Ansible lint
+        env:
+          ANSIBLE_CONFIG: engine/ansible/ansible.cfg
+        run: uv run ansible-lint engine/ansible

cloudfall-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+---
+name: Release
+
+"on":
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    # PyPI trusted publishing: the workflow proves its identity with a
+    # short-lived OIDC token, so no API token is stored anywhere.
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check the tag matches the project version
+        run: |
+          version="$(uv run python -c 'import tomllib, pathlib; \
+            print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "${version}" != "${tag}" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match project version ${version}" >&2
+            exit 1
+          fi
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type-check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      # The wheel carries the schema catalog and the Ansible engine as package
+      # data; a project installed from PyPI has no checkout to fall back on, so
+      # an empty bundle must fail the release rather than ship.
+      - name: Check the wheel carries the bundled schemas and engine
+        run: |
+          uv run python - <<'PY'
+          import sys
+          import zipfile
+          from pathlib import Path
+
+          wheel = next(Path("dist").glob("*.whl"))
+          names = zipfile.ZipFile(wheel).namelist()
+          for expected in ("cloudfall/_bundled/schemas/", "cloudfall_engine/_bundled/ansible/"):
+              if not any(name.startswith(expected) for name in names):
+                  sys.exit(f"{wheel.name} carries nothing under {expected}")
+          PY
+
+      # The published artifact, exercised the way a user gets it: installed
+      # into an empty environment with no repository in sight.
+      - name: Smoke-test the built wheel
+        run: |
+          uv venv /tmp/wheel-check
+          VIRTUAL_ENV=/tmp/wheel-check uv pip install dist/*.whl
+          /tmp/wheel-check/bin/cloudfall config validate --project config/examples
+          /tmp/wheel-check/bin/cloudfall-engine inventory render --project config/examples
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

cloudfall-0.2.0/.gitignore

@@ -0,0 +1,290 @@
+### VisualStudioCode template
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Python template
+# 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
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__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
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Atlas
+.ruff_cache/
+tmp/
+.idea/
+memory/
+
+# Wrangler local state
+site/.wrangler/

cloudfall-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,263 @@
+# Architecture
+
+Cloudfall is the operator's record for a small fleet run by an AI agent.
+The agent decides, Ansible executes, and Cloudfall sits between them: it
+declares what the agent may do, checks every result, and keeps the evidence
+behind every decision. Ansible is the hand, the agent is the brain,
+Cloudfall is the conscience.
+
+It was built wedge-first: take a SaaS off a cloud PaaS such as Render and
+run it on one fresh Debian host with a hardened baseline, monitoring,
+deploys, and rollback, then let an always-on operator run it there. The
+architecture is designed for the goal behind the wedge: an agent safely
+operating 10–100 standalone SaaS applications across a fleet of dedicated
+Debian servers without Kubernetes (see the [fleet goals](docs/fleet-goals.md)),
+on a config the team already owns. This document describes the durable
+design; [`ROADMAP.md`](ROADMAP.md) is the authoritative source for what is
+implemented today, and the [brownfield design](docs/brownfield-design.md)
+describes the proposed next step, none of which is built.
+
+Every layer keeps the same invariants: no action without declared config, no
+status without evidence, no compliance without audit, no decision without a
+record.
+
+## Control plane stack
+
+```text
+Human / AI agent ──edits──► Config (YAML)
+Human / AI agent ──runs───► CLI / MCP / Python API ──► Gate ──► Execution engine ──► Servers
+                                     │                                   │
+                                     └──────────── Record ◄── Verify ◄───┘
+```
+
+The config is a store, not a pipeline stage: humans and agents edit it
+directly, the CLI validates and reads it, and the engine converges servers
+to it. The agent operates through a stable CLI, the `cloudfall-mcp` server
+and a Python API instead of inventing shell commands or discovering
+infrastructure over SSH. Every mutating operation goes through the engine's
+explicit playbook contracts, waits behind a gate the agent does not control
+(a confirmation handshake, or an `OperatorPolicy` that licenses the
+operation class), and produces receipts. Status is derived from validated
+observations, never inferred.
+
+The record is the durable output. Every operator decision is written as a
+schema-validated receipt that holds the evidence it was based on, the
+diagnosis, the exact operation, who approved it and the outcome; deploys,
+backups, restore drills and data migrations write receipts of their own.
+The agent's own log says a tool was called. The record says what the fleet
+looked like when it was, and it is what licenses autonomy later.
+
+The loop the agent runs is fixed: observe (read evidence), decide (pick an
+operation and targets, state why), preview (check mode and diff), approve
+(gate by risk), run (execute through the engine), verify (check the result
+and update the evidence).
+
+## Project
+
+A project is the unit Cloudfall operates: one directory, usually a private
+repository, holding everything needed to run one user's stack.
+
+- **Fleet** — the machines: `Server`, `ServerType`, and `SshPublicKey`
+  resources
+- **Applications** — the workloads: `Application`, `Component`, `Service`,
+  and `Domain` resources
+- **Operations** — the declarations that run them: `AlertRule`,
+  `OperatorPolicy`, and `LoggingStack` resources
+- **Pin** — a `pyproject.toml` that installs Cloudfall as a package at one
+  exact commit, so the project and the platform version move together
+
+Every `cloudfall` command runs inside a project: the current directory when
+it is one, or the directory named by `--project` or by the
+`CLOUDFALL_PROJECT` environment variable. Relative paths, including the
+`tmp/` defaults, resolve against the project, as if the command had been
+started there.
+Resources live in one directory per kind (`servers/`, `components/`, ...),
+and only those directories are read as resources; a resource in the wrong
+directory is a validation error. Everything else in the project is the
+user's: playbooks and roles of their own, encrypted secrets, docs, tooling.
+Runtime state (observations, receipts, rendered inventory, built artifacts,
+rendered environment files, the persisted migration plan) lands under `tmp/`
+and is never committed. `cloudfall init` lays out a new project and
+`cloudfall add` declares its first fleet resources.
+
+Proposed, not built: for a team that already runs Ansible, the project is
+their existing repository. The fleet is read from their inventory instead of
+`Server` resources, Cloudfall's declarations live under one `cloudfall` key
+in their `group_vars` and `host_vars`, and their playbooks are registered as
+operations. One config, theirs; no import and no second copy. See the
+[brownfield design](docs/brownfield-design.md).
+
+## Module boundaries
+
+Cloudfall is a monorepo with three architectural modules:
+
+- [`config/`](config/README.md) — the config: declarative YAML resources and
+  their JSON Schemas
+- [`sdk/`](sdk/README.md) — the `cloudfall` CLI and Python API consumed by
+  agents and tooling
+- [`engine/`](engine/README.md) — internal execution machinery: Ansible-based
+  execution of explicit plans
+
+The boundaries are strict even inside one repository: the config contains no
+execution logic, the CLI reads and validates the config without Ansible
+internals, the engine never silently rewrites the config, and external entry
+points call the CLI rather than Ansible directly. Mutating operations execute
+through the engine's command-line and playbook contracts, never its
+internals. The modules may split into separate repositories later if
+independent release cycles or access control require it.
+
+## Config
+
+The config is declarative only, organized as typed resources validated
+against versioned JSON Schemas: servers, server types, applications,
+components, services, domains, logging stacks, alert rules, operator
+policy, and SSH public keys.
+
+The config never contains secret values; schemas and validation reject them.
+Secrets exist as references, rendered from a sops/age-encrypted secrets
+directory into environment files under the project's `tmp/`, never into a
+resource, and consumed by systemd via `EnvironmentFile`.
+
+The typed resources are today's config, not the point. The point is that
+there is one description of the fleet, the team owns it, it is plain files
+in a repository, and nothing rewrites it silently. The brownfield design
+keeps every one of those properties while moving the description into the
+team's own Ansible inventory; the schemas then validate the `cloudfall`
+block instead of standalone documents.
+
+## Application and component model
+
+An application is an independent SaaS
+product that composes components; a component (frontend, backend, worker,
+scheduler) owns its own deployment. Components are named `crm-backend` style
+rather than by path, and each may deploy to one or more servers.
+
+On disk, each application owns a Linux user and a `/srv/apps/<application>/`
+directory with one subdirectory per component. Releases unpack into
+`releases/` and a `current` symlink points at the active release, which is
+what makes rollback a symlink switch.
+
+Components come from one repository each by preference, with monorepos also
+supported.
+
+## Deployment strategy
+
+Artifacts are built on the management host — the machine running Cloudfall,
+which is a workstation for one-off migrations or a small always-on host
+once the operator runs persistently — never on production servers:
+
+```text
+Git ref → build artifact (hashed tarball + release metadata) → digest-verified
+transfer → unpack into releases/ → locked dependency materialization →
+environment file → systemd unit → health-check gate → symlink switch
+```
+
+A failed health check triggers automatic rollback to the previous release.
+Releases are retained until a cleanup policy removes them, so explicit
+rollback to any retained release stays available. Deployment approval is
+automatic or manual per application.
+
+## Supported workloads
+
+Applications run as native systemd units on long-lived Debian hosts, not
+in containers. The primary stacks are Python (uv, Gunicorn/Uvicorn, Celery)
+and Node.js; anything that runs as a systemd service with a health endpoint
+fits the model.
+
+## Infrastructure model
+
+Servers are traditional long-lived Debian hosts (not immutable), described
+by reusable `ServerType` resources; bare-metal server types
+add software RAID1 and the hybrid storage layout, while cloud VPS types do
+not. Any server can run any declared service or component:
+
+- Infrastructure services (PostgreSQL and Redis today; MySQL, Elasticsearch,
+  and friends as the catalog grows) stay pinned to declared servers
+- Application components are movable: reassigning `crm-backend` from `h1,h2`
+  to `h3` is a config change followed by convergence
+- Failover is manual with easy reassignment rather than automated
+  orchestration; the planned PostgreSQL high-availability formation (M14 on
+  the roadmap) amends this at the database layer only, where a standby may
+  be promoted automatically but an operator never initiates a promotion
+  without explicit confirmation
+
+## Networking
+
+Nginx terminates TLS with virtual hosts rendered from `Domain` resources and
+Let's Encrypt certificates. Cloudflare proxying is used where appropriate,
+and future load balancing is Cloudflare plus Nginx, with HAProxy optional
+later.
+
+## Operations layer
+
+Operating servers is the same evidence discipline running continuously:
+
+- **Alerting** — alert rules and notification channels are typed config
+  rendered into the Loki/Grafana/Alloy stack; a firing alert is evidence,
+  exposed over a read-only mTLS route on the same gateway that receives
+  logs and metrics
+- **Operator** — an always-on management-host process watches alerts and
+  scheduled drift audits, writes every diagnosis as a schema-validated
+  proposal receipt (trigger evidence, diagnosis, exact operation, outcome),
+  and executes only existing engine entry points
+- **Graduated autonomy** — autonomy is granted per operation class by a
+  declared `OperatorPolicy` and earned by verified receipt history, never
+  globally; DNS cutover, data deletion, and database promotion stay behind
+  explicit confirmation regardless of autonomy level
+- **Record** — receipts are the audit log: schema-validated, written under
+  the project's `tmp/`, one per decision or operation, holding the evidence,
+  the action, the approver and the outcome. "Why did the agent do that" is
+  answered from the record, not from the agent's memory
+- **Verify** — a run is not an outcome. Deploys are gated on health, backups
+  on a timer-driven restore drill, migrations on row counts, audits on
+  observed drift. The brownfield design generalises this into a verify step
+  declared on every operation
+
+## Direction: the team's Ansible as the config
+
+The wedge proves the model on one host that Cloudfall set up. Most teams
+that would use the record already have a fleet and an Ansible repository.
+The [brownfield design](docs/brownfield-design.md) re-roots the same
+machinery on that repository, in this build order:
+
+- **Operations catalog** — each of the team's playbooks becomes a declared
+  tool with typed inputs, a risk level exported as MCP tool annotations,
+  preconditions and a verify step
+- **Approval and audit** — the gate and the audit entry, unchanged in
+  principle from the operator above, applied to every declared operation
+- **Agent surface** — the same CLI and MCP server, with the tool list
+  generated from the catalog
+- **Fleet reader** — hosts, groups and merged variables read through
+  ansible-core in process, with the `cloudfall` block as the only addition
+- **Observation, safe edits, starter roles** — last; the existing engine
+  roles become optional operations for teams with no baseline yet
+
+None of this is implemented. The module boundaries above hold: the reader
+is one wrapper module around ansible-core, and mutating operations still
+execute through the engine's contracts.
+
+## Long-term vision: fleet operation
+
+The same config, record, and deploy machinery is designed to extend to
+fleet operation without architectural change; the
+[fleet goals](docs/fleet-goals.md) state the requirements this must deliver
+and their current status:
+
+- **Catalog breadth** — MySQL, Elasticsearch, RabbitMQ, and Node runtime
+  services following the PostgreSQL and Redis pattern: pinned installs,
+  loopback-only binds, backup policies, audited evidence
+- **Multi-server assignment at scale** — components spread across many
+  servers and moved by editing the config; the model exists, fleet-scale
+  operation is the unproven part
+- **Managed secrets backends** — the sops/age provider boundary admits a
+  central secrets manager later, keeping the platform/application/component
+  scope hierarchy
+- **Fleet observability** — per-service exporters beyond PostgreSQL and
+  Redis, and alert rules spanning more than one host
+- **PostgreSQL high availability** — a declared replication, failover, and
+  point-in-time recovery (M13) and failover formation (M14 on the roadmap)
+
+## Status
+
+Implementation status, milestone exit criteria, and what remains before the
+wedge is proven live are tracked in [`ROADMAP.md`](ROADMAP.md).