cloudfall 0.2.0__tar.gz → 0.2.1__tar.gz

{cloudfall-0.2.0 → cloudfall-0.2.1}/CHANGELOG.md

@@ -6,6 +6,30 @@ Notable changes to Cloudfall. The format follows
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-09-20
+
+### Fixed
+
+- `cloudfall init` works from a PyPI install. An install from the package
+  index records no origin to read a commit from, so `init` failed with
+  `project_revision_unresolved` on the first command a new user runs, and
+  `--rev` only worked around it by writing a project that installed
+  Cloudfall from git instead of from the index. A project now pins whatever
+  ran `init`: `cloudfall==<version>` with no `[tool.uv.sources]` table for a
+  released install, the commit and repository for a git or source install
+- The project README links the secrets guide and the reference examples at
+  the release tag when the pin is a released version, rather than at a
+  commit the install does not know
+
+### Changed
+
+- `InitOptions` and the `cloudfall init` envelope carry one `pin` instead of
+  a `revision` and a `source`: `{"kind": "index", "version": ...}` or
+  `{"kind": "git", "revision": ..., "source": ...}`. `resolve_installed_pin`
+  replaces `resolve_installed_revision`
+- `--rev` documents that it pins a commit from `--source`, which is now the
+  explicit alternative to the default rather than the only mechanism
+
 ## [0.2.0] — 2026-09-20
 
 ### Added

{cloudfall-0.2.0 → cloudfall-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.2.0
+Version: 0.2.1
 Summary: AI-native control plane for dedicated Debian application fleets
 Project-URL: Homepage, https://cloudfall.dev
 Project-URL: Repository, https://github.com/romamo/cloudfall
@@ -160,10 +160,18 @@ is implemented yet; everything below this line is.
 
 ## Quickstart
 
-Cloudfall is not on PyPI yet; run it from a clone of this repository. The
-only prerequisite is [`uv`](https://docs.astral.sh/uv/): it provisions the
-required Python 3.14 interpreter and all dependencies automatically, so you
-do not need Python 3.14 preinstalled.
+Cloudfall is on PyPI. The only prerequisite is
+[`uv`](https://docs.astral.sh/uv/): it provisions the required Python 3.14
+interpreter and all dependencies automatically, so you do not need Python
+3.14 preinstalled.
+
+```console
+uv tool install cloudfall
+cloudfall --help
+```
+
+The reference resource set lives in this repository, so validating it means
+a clone:
 
 ```console
 git clone https://github.com/romamo/cloudfall.git
@@ -189,13 +197,14 @@ uv run cloudfall-engine inventory render --project config/examples
 Your servers, applications, evidence, and any playbooks of your own belong in
 a project: a directory of its own, kept private. Cloudfall's wheel bundles the
 schema catalog and the Ansible engine, so the project needs no checkout of
-this repository. `cloudfall init` is the first command; run it straight from
-git or from a clone (`uv run cloudfall init ../my-project`), and it pins the
-project to the exact Cloudfall commit it ran from. Without a directory
-argument it initializes the current directory, which must be empty:
+this repository. `cloudfall init` is the first command, and it pins the
+project to the Cloudfall that ran it: the released version when that came
+from PyPI, the exact commit when it came from git or a clone. Without a
+directory argument it initializes the current directory, which must be
+empty:
 
 ```console
-uvx --from git+https://github.com/romamo/cloudfall.git cloudfall init my-project
+uvx cloudfall init my-project
 cd my-project
 uv sync
 ```
@@ -215,15 +224,17 @@ repository, and a `pyproject.toml`:
 name = "my-project"
 version = "0"
 requires-python = ">=3.14"
-dependencies = ["cloudfall"]
+dependencies = ["cloudfall==<version>"]
 
 [tool.uv]
 package = false
-
-[tool.uv.sources]
-cloudfall = { git = "https://github.com/romamo/cloudfall.git", rev = "<commit>" }
 ```
 
+Bump that pin and run `uv sync` to move the project to a newer Cloudfall. A
+project initialized from a git or source install pins a commit instead, with
+a `[tool.uv.sources]` table naming the repository and revision; `--rev` asks
+for that explicitly.
+
 Only the kind directories are read as resources, so playbooks, roles, docs,
 and tooling files may live anywhere else in the project. Commands find the
 project on their own: the current directory when it is one, else

{cloudfall-0.2.0 → cloudfall-0.2.1}/README.md

@@ -134,10 +134,18 @@ is implemented yet; everything below this line is.
 
 ## Quickstart
 
-Cloudfall is not on PyPI yet; run it from a clone of this repository. The
-only prerequisite is [`uv`](https://docs.astral.sh/uv/): it provisions the
-required Python 3.14 interpreter and all dependencies automatically, so you
-do not need Python 3.14 preinstalled.
+Cloudfall is on PyPI. The only prerequisite is
+[`uv`](https://docs.astral.sh/uv/): it provisions the required Python 3.14
+interpreter and all dependencies automatically, so you do not need Python
+3.14 preinstalled.
+
+```console
+uv tool install cloudfall
+cloudfall --help
+```
+
+The reference resource set lives in this repository, so validating it means
+a clone:
 
 ```console
 git clone https://github.com/romamo/cloudfall.git
@@ -163,13 +171,14 @@ uv run cloudfall-engine inventory render --project config/examples
 Your servers, applications, evidence, and any playbooks of your own belong in
 a project: a directory of its own, kept private. Cloudfall's wheel bundles the
 schema catalog and the Ansible engine, so the project needs no checkout of
-this repository. `cloudfall init` is the first command; run it straight from
-git or from a clone (`uv run cloudfall init ../my-project`), and it pins the
-project to the exact Cloudfall commit it ran from. Without a directory
-argument it initializes the current directory, which must be empty:
+this repository. `cloudfall init` is the first command, and it pins the
+project to the Cloudfall that ran it: the released version when that came
+from PyPI, the exact commit when it came from git or a clone. Without a
+directory argument it initializes the current directory, which must be
+empty:
 
 ```console
-uvx --from git+https://github.com/romamo/cloudfall.git cloudfall init my-project
+uvx cloudfall init my-project
 cd my-project
 uv sync
 ```
@@ -189,15 +198,17 @@ repository, and a `pyproject.toml`:
 name = "my-project"
 version = "0"
 requires-python = ">=3.14"
-dependencies = ["cloudfall"]
+dependencies = ["cloudfall==<version>"]
 
 [tool.uv]
 package = false
-
-[tool.uv.sources]
-cloudfall = { git = "https://github.com/romamo/cloudfall.git", rev = "<commit>" }
 ```
 
+Bump that pin and run `uv sync` to move the project to a newer Cloudfall. A
+project initialized from a git or source install pins a commit instead, with
+a `[tool.uv.sources]` table naming the repository and revision; `--rev` asks
+for that explicitly.
+
 Only the kind directories are read as resources, so playbooks, roles, docs,
 and tooling files may live anywhere else in the project. Commands find the
 project on their own: the current directory when it is one, else

{cloudfall-0.2.0 → cloudfall-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cloudfall"
-version = "0.2.0"
+version = "0.2.1"
 description = "AI-native control plane for dedicated Debian application fleets"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

{cloudfall-0.2.0 → cloudfall-0.2.1}/sdk/src/cloudfall/cli.py

@@ -98,6 +98,7 @@ from cloudfall.operator import (
 from cloudfall.project import (
     DEFAULT_SOURCE_URL,
     PROJECT_DIRECTORY_VARIABLE,
+    GitPin,
     GitRevision,
     GitSourceUrl,
     InitOptions,
@@ -106,7 +107,7 @@ from cloudfall.project import (
     ProjectName,
     init_project,
     project_context,
-    resolve_installed_revision,
+    resolve_installed_pin,
 )
 from cloudfall.render_api import (
     HttpRenderApiClient,
@@ -202,8 +203,9 @@ def _add_init_parser(
     init_parser.add_argument(
         "--rev",
         help=(
-            "Cloudfall commit to pin (default: the commit the running "
-            "cloudfall was installed from)"
+            "Cloudfall commit to pin, installed from --source (default: the "
+            "released version of the running cloudfall, or the commit it was "
+            "installed from when that was a git or source install)"
         ),
     )
     init_parser.add_argument(
@@ -217,7 +219,8 @@ def _add_init_parser(
         "--source",
         default=DEFAULT_SOURCE_URL,
         help=(
-            f"git location of Cloudfall to install from (default: {DEFAULT_SOURCE_URL})"
+            "git location of Cloudfall to install from, with --rev "
+            f"(default: {DEFAULT_SOURCE_URL})"
         ),
     )
 
@@ -1030,16 +1033,18 @@ def _run_init(arguments: Namespace) -> int:
             if arguments.name is not None
             else ProjectName.from_directory(directory)
         )
-        revision = (
-            GitRevision.from_boundary(arguments.rev)
+        pin = (
+            GitPin(
+                GitRevision.from_boundary(arguments.rev),
+                GitSourceUrl.from_boundary(arguments.source),
+            )
             if arguments.rev is not None
-            else resolve_installed_revision()
+            else resolve_installed_pin()
         )
         options = InitOptions(
             directory=directory,
             name=name,
-            revision=revision,
-            source=GitSourceUrl.from_boundary(arguments.source),
+            pin=pin,
             description=(
                 ProjectDescription.from_boundary(arguments.description)
                 if arguments.description is not None

{cloudfall-0.2.0 → cloudfall-0.2.1}/sdk/src/cloudfall/project.py

@@ -4,7 +4,8 @@ A project is one directory holding everything Cloudfall needs to run one
 user's stack: the fleet (servers, server types, SSH public keys), the
 applications (applications, components, services, domains), the operating
 declarations (alert rules, operator policies, logging stacks), and the
-``pyproject.toml`` that pins the Cloudfall revision the project runs with.
+``pyproject.toml`` that pins the Cloudfall the project runs with: a
+released version from the package index, or a commit in the repository.
 Every ``cloudfall`` command runs inside a project: the current directory
 when it is one, else ``--project``, else ``CLOUDFALL_PROJECT``.
 Evidence, receipts, and rendered files land under ``tmp/`` inside the
@@ -35,6 +36,9 @@ if TYPE_CHECKING:
 
 _GIT_REVISION_PATTERN = re.compile(r"^[0-9a-f]{40}$")
 _PROJECT_NAME_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$")
+_RELEASE_VERSION_PATTERN = re.compile(
+    r"^\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.post\d+)?(?:\.dev\d+)?$"
+)
 _SCP_LIKE_SOURCE_PATTERN = re.compile(
     r"^(?P<user>[\w.-]+)@(?P<host>[\w.-]+):(?P<path>[\w./-]+)$"
 )
@@ -69,6 +73,7 @@ _ERROR_DIRECTORY_UNRESOLVED = "project_directory_unresolved"
 _ERROR_REVISION_UNRESOLVED = "project_revision_unresolved"
 _ERROR_REVISION_UNCOMMITTED = "project_revision_uncommitted"
 _ERROR_REVISION_UNPUBLISHED = "project_revision_unpublished"
+_ERROR_VERSION_UNRESOLVED = "project_version_unresolved"
 _ERROR_NOT_A_DIRECTORY = "project_directory_not_a_directory"
 _ERROR_NOT_EMPTY = "project_directory_not_empty"
 _ERROR_GIT_UNAVAILABLE = "project_git_unavailable"
@@ -169,6 +174,109 @@ class GitSourceUrl:
         return self.value
 
 
+@dataclass(frozen=True, slots=True)
+class ReleaseVersion:
+    """Released Cloudfall version a project pins from the package index."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        """Enforce the release-version invariant at construction time."""
+        if not _RELEASE_VERSION_PATTERN.fullmatch(self.value):
+            message = f"release version must be a PEP 440 release: {self.value!r}"
+            raise ValueError(message)
+
+    @classmethod
+    def from_boundary(cls, value: object) -> ReleaseVersion:
+        """Coerce a boundary value while keeping internal APIs strictly typed."""
+        if not isinstance(value, str):
+            message = f"release version must be a string, got {type(value).__name__}"
+            raise TypeError(message)
+        return cls(value.strip())
+
+    def __str__(self) -> str:
+        """Return the serialized version."""
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class GitPin:
+    """A project that installs Cloudfall from a commit in the repository."""
+
+    revision: GitRevision
+    source: GitSourceUrl = GitSourceUrl(DEFAULT_SOURCE_URL)
+
+    @property
+    def requirement(self) -> str:
+        """Return the dependency specifier for the project's ``pyproject``."""
+        return "cloudfall"
+
+    @property
+    def sources_table(self) -> str:
+        """Return the ``[tool.uv.sources]`` table that resolves the commit."""
+        return f"""
+# Cloudfall is an installed package: the schema catalog and the Ansible engine
+# ship inside the wheel. Bump `rev` to move this project to a newer Cloudfall
+# commit, then run `uv sync`. Add the `mcp` extra (`cloudfall[mcp]`) to run
+# the `cloudfall-mcp` agent server.
+[tool.uv.sources]
+cloudfall = {{ git = "{self.source}", rev = "{self.revision}" }}
+"""
+
+    @property
+    def browse_url(self) -> str:
+        """Return the https location of the repository the pin reads from."""
+        return self.source.browse_url
+
+    @property
+    def browse_ref(self) -> str:
+        """Return the git ref whose files match the pinned Cloudfall."""
+        return str(self.revision)
+
+    def as_dict(self) -> dict[str, object]:
+        """Serialize the pin for system boundaries."""
+        return {
+            "kind": "git",
+            "revision": str(self.revision),
+            "source": str(self.source),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class IndexPin:
+    """A project that installs a released Cloudfall from the package index."""
+
+    version: ReleaseVersion
+
+    @property
+    def requirement(self) -> str:
+        """Return the dependency specifier for the project's ``pyproject``."""
+        return f"cloudfall=={self.version}"
+
+    @property
+    def sources_table(self) -> str:
+        """Return nothing: a released version needs no source override."""
+        return ""
+
+    @property
+    def browse_url(self) -> str:
+        """Return the https location of the repository the release came from."""
+        return GitSourceUrl(DEFAULT_SOURCE_URL).browse_url
+
+    @property
+    def browse_ref(self) -> str:
+        """Return the release tag whose files match the pinned Cloudfall."""
+        return f"v{self.version}"
+
+    def as_dict(self) -> dict[str, object]:
+        """Serialize the pin for system boundaries."""
+        return {"kind": "index", "version": str(self.version)}
+
+
+type ProjectPin = GitPin | IndexPin
+"""What a project pins Cloudfall to: a released version, or a commit."""
+
+
 @dataclass(frozen=True, slots=True)
 class ProjectName:
     """Package name of a project, as written into its ``pyproject.toml``."""
@@ -255,8 +363,7 @@ class InitOptions:
 
     directory: Path
     name: ProjectName
-    revision: GitRevision
-    source: GitSourceUrl = GitSourceUrl(DEFAULT_SOURCE_URL)
+    pin: ProjectPin
     description: ProjectDescription | None = None
 
 
@@ -276,8 +383,7 @@ class ProjectScaffold:
 
     directory: Path
     name: ProjectName
-    revision: GitRevision
-    source: GitSourceUrl
+    pin: ProjectPin
     files: tuple[str, ...]
     git: GitSetup
 
@@ -288,8 +394,7 @@ class ProjectScaffold:
             "project": {
                 "directory": str(self.directory),
                 "name": str(self.name),
-                "revision": str(self.revision),
-                "source": str(self.source),
+                "pin": self.pin.as_dict(),
                 "git": self.git.value,
             },
             "files": list(self.files),
@@ -388,33 +493,32 @@ def project_path(value: str) -> Path:
     return path
 
 
-def resolve_installed_revision(
+def resolve_installed_pin(
     read_direct_url: Callable[[], str | None] | None = None,
     inspect_checkout: Callable[[Path], CheckoutState] | None = None,
-) -> GitRevision:
-    """Return the commit the running Cloudfall was installed from.
-
-    A wheel installed from git records its commit in ``direct_url.json``; an
-    editable source checkout records the checkout location, whose ``HEAD`` is
-    the commit, provided the checkout is clean (else ``HEAD`` is not the code
-    that is running) and ``HEAD`` is on a remote branch (else ``uv sync``
-    cannot fetch it). Anything else cannot be pinned and must be given
-    explicitly.
+    read_version: Callable[[], str] | None = None,
+) -> ProjectPin:
+    """Return what the running Cloudfall pins a new project to.
+
+    An install from the package index records no origin, and its version is
+    the pin: the project depends on ``cloudfall==<version>`` and resolves it
+    the ordinary way. A wheel installed from git records its commit in
+    ``direct_url.json``; an editable source checkout records the checkout
+    location, whose ``HEAD`` is the commit, provided the checkout is clean
+    (else ``HEAD`` is not the code that is running) and ``HEAD`` is on a
+    remote branch (else ``uv sync`` cannot fetch it). Anything else cannot be
+    pinned and must be given explicitly.
     """
     direct_url = (read_direct_url or _installed_direct_url)()
     if direct_url is None:
-        message = (
-            "the installed cloudfall distribution records no origin; "
-            "pass --rev with the commit to pin"
-        )
-        raise ProjectError(_ERROR_REVISION_UNRESOLVED, message)
+        return IndexPin(_installed_release_version(read_version))
     record = json.loads(direct_url)
     if not isinstance(record, dict):
         message = f"direct_url.json is not an object: {direct_url!r}"
         raise ProjectError(_ERROR_REVISION_UNRESOLVED, message)
     vcs_info = record.get("vcs_info")
     if isinstance(vcs_info, dict) and "commit_id" in vcs_info:
-        return GitRevision.from_boundary(vcs_info["commit_id"])
+        return GitPin(GitRevision.from_boundary(vcs_info["commit_id"]))
     dir_info = record.get("dir_info")
     url = record.get("url")
     if (
@@ -424,7 +528,7 @@ def resolve_installed_revision(
     ):
         checkout = Path(urlparse(url).path)
         inspect = inspect_checkout or _inspect_checkout
-        return _pinnable_head(checkout, inspect(checkout))
+        return GitPin(_pinnable_head(checkout, inspect(checkout)))
     message = (
         "the installed cloudfall distribution is neither a git install nor a "
         f"source checkout ({url!r}); pass --rev with the commit to pin"
@@ -449,6 +553,25 @@ def _pinnable_head(checkout: Path, state: CheckoutState) -> GitRevision:
     return head
 
 
+def _installed_release_version(
+    read_version: Callable[[], str] | None = None,
+) -> ReleaseVersion:
+    raw = (read_version or _installed_version)()
+    try:
+        return ReleaseVersion.from_boundary(raw)
+    except ValueError as error:
+        message = (
+            "the installed cloudfall distribution records no origin and its "
+            f"version {raw!r} is not a release, so there is nothing to pin; "
+            "pass --rev with the commit to pin"
+        )
+        raise ProjectError(_ERROR_VERSION_UNRESOLVED, message) from error
+
+
+def _installed_version() -> str:
+    return metadata.version("cloudfall")
+
+
 def _installed_direct_url() -> str | None:
     return metadata.distribution("cloudfall").read_text("direct_url.json")
 
@@ -543,8 +666,7 @@ def init_project(
     return ProjectScaffold(
         directory=directory,
         name=options.name,
-        revision=options.revision,
-        source=options.source,
+        pin=options.pin,
         files=tuple(files),
         git=git,
     )
@@ -561,18 +683,15 @@ name = "{options.name}"
 version = "0"
 description = "{description}"
 requires-python = ">=3.14"
-dependencies = ["cloudfall"]
+# Cloudfall is an installed package: the schema catalog and the Ansible engine
+# ship inside the wheel. Bump this pin to move the project to a newer
+# Cloudfall, then run `uv sync`. Add the `mcp` extra (`cloudfall[mcp]`) to run
+# the `cloudfall-mcp` agent server.
+dependencies = ["{options.pin.requirement}"]
 
 [tool.uv]
 package = false
-
-# Cloudfall is an installed package: the schema catalog and the Ansible engine
-# ship inside the wheel. Bump `rev` to move this project to a newer Cloudfall
-# commit, then run `uv sync`. Add the `mcp` extra (`cloudfall[mcp]`) to run
-# the `cloudfall-mcp` agent server.
-[tool.uv.sources]
-cloudfall = {{ git = "{options.source}", rev = "{options.revision}" }}
-"""
+{options.pin.sources_table}"""
 
 
 _GITIGNORE = f"""# Runtime state: evidence, receipts, rendered inventory, built
@@ -603,10 +722,10 @@ creation_rules:
 def _readme(options: InitOptions, git: GitSetup) -> str:
     tmp = RUNTIME_DIRECTORY
     secrets = SECRETS_DIRECTORY
-    browse = options.source.browse_url
-    revision = options.revision
-    secrets_guide = f"{browse}/blob/{revision}/{SECRETS_GUIDE_PATH}"
-    examples = f"{browse}/tree/{revision}/{EXAMPLES_PATH}"
+    browse = options.pin.browse_url
+    ref = options.pin.browse_ref
+    secrets_guide = f"{browse}/blob/{ref}/{SECRETS_GUIDE_PATH}"
+    examples = f"{browse}/tree/{ref}/{EXAMPLES_PATH}"
     about = (
         str(options.description)
         if options.description is not None

{cloudfall-0.2.0 → cloudfall-0.2.1}/sdk/tests/test_agent_tools.py

@@ -8,7 +8,13 @@ from pathlib import Path
 import pytest
 import yaml
 from cloudfall.agent_tools import AgentConfig, AgentToolset
-from cloudfall.project import GitRevision, InitOptions, ProjectName, init_project
+from cloudfall.project import (
+    GitPin,
+    GitRevision,
+    InitOptions,
+    ProjectName,
+    init_project,
+)
 
 ROOT = Path(__file__).parents[2]
 SCHEMAS = ROOT / "config" / "schemas" / "v1"
@@ -141,7 +147,7 @@ def _fresh_project(tmp_path: Path) -> AgentToolset:
         InitOptions(
             directory=directory,
             name=ProjectName("project"),
-            revision=GitRevision(REVISION),
+            pin=GitPin(GitRevision(REVISION)),
         )
     )
     return AgentToolset(_config(tmp_path, project_directory=directory))

{cloudfall-0.2.0 → cloudfall-0.2.1}/sdk/tests/test_authoring.py

@@ -17,7 +17,13 @@ from cloudfall.authoring import (
 )
 from cloudfall.cli import main
 from cloudfall.domain import ConnectionAddress, LinuxUser, ResourceId, TcpPort
-from cloudfall.project import GitRevision, InitOptions, ProjectName, init_project
+from cloudfall.project import (
+    GitPin,
+    GitRevision,
+    InitOptions,
+    ProjectName,
+    init_project,
+)
 from cloudfall.validation import ConfigValidationError, validate_config
 
 ROOT = Path(__file__).parents[2]
@@ -46,7 +52,7 @@ def _project(tmp_path: Path) -> Path:
         InitOptions(
             directory=directory,
             name=ProjectName("project"),
-            revision=GitRevision(REVISION),
+            pin=GitPin(GitRevision(REVISION)),
         )
     )
     return directory