cloudfall 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -6,6 +6,49 @@ Notable changes to Cloudfall. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-09-20
+
+### Removed
+
+- `cloudfall init --rev` and `--source`, and the machinery behind them:
+  `GitRevision`, `GitSourceUrl`, `GitPin`, `IndexPin`, `CheckoutState`, the
+  checkout inspection, and the `project_revision_unresolved`,
+  `project_revision_uncommitted` and `project_revision_unpublished` errors.
+  Cloudfall is on PyPI, so a project pins a release and resolves it like any
+  other dependency; `resolve_installed_version` replaces
+  `resolve_installed_pin`, and the `init` envelope reports `version` rather
+  than a `pin` object. To run an unreleased Cloudfall in a project, point the
+  dependency at a checkout with uv's own `[tool.uv.sources]`
+
+### Changed
+
+- The quickstart and the Render migration guide install Cloudfall from the
+  index rather than from git
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.2.0
+Version: 0.3.0
 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,12 @@ 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 released Cloudfall that ran it. 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 +222,18 @@ 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 version and run `uv sync` to move the project to a newer
+Cloudfall. To run an unreleased Cloudfall in a project, point the dependency
+at a checkout or a commit with uv's own
+[`[tool.uv.sources]`](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources);
+Cloudfall itself only ever pins a release.
+
 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.3.0}/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,12 @@ 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 released Cloudfall that ran it. 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 +196,18 @@ 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 version and run `uv sync` to move the project to a newer
+Cloudfall. To run an unreleased Cloudfall in a project, point the dependency
+at a checkout or a commit with uv's own
+[`[tool.uv.sources]`](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources);
+Cloudfall itself only ever pins a release.
+
 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.3.0}/docs/render-migration-guide.md

@@ -55,7 +55,7 @@ Not imported today; each lands in the gap report instead of being guessed at:
 - Your `render.yaml` blueprint and access to your application repositories
 - Python 3.14 and [`uv`](https://docs.astral.sh/uv/) on the machine you run
   Cloudfall from (your workstation works; no management server is required)
-- A project: `uvx --from git+https://github.com/romamo/cloudfall.git cloudfall init my-project`,
+- A project: `uvx cloudfall init my-project`,
   then `cd my-project && uv sync`. Every command below runs from inside it
 
 ## Step 1: import the blueprint

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

@@ -1,6 +1,6 @@
 [project]
 name = "cloudfall"
-version = "0.2.0"
+version = "0.3.0"
 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.3.0}/sdk/src/cloudfall/cli.py

@@ -96,17 +96,14 @@ from cloudfall.operator import (
     run_once as operator_run_once,
 )
 from cloudfall.project import (
-    DEFAULT_SOURCE_URL,
     PROJECT_DIRECTORY_VARIABLE,
-    GitRevision,
-    GitSourceUrl,
     InitOptions,
     ProjectDescription,
     ProjectError,
     ProjectName,
     init_project,
     project_context,
-    resolve_installed_revision,
+    resolve_installed_version,
 )
 from cloudfall.render_api import (
     HttpRenderApiClient,
@@ -199,13 +196,6 @@ def _add_init_parser(
         "--name",
         help="package name written to pyproject.toml (default: the directory name)",
     )
-    init_parser.add_argument(
-        "--rev",
-        help=(
-            "Cloudfall commit to pin (default: the commit the running "
-            "cloudfall was installed from)"
-        ),
-    )
     init_parser.add_argument(
         "--description",
         help=(
@@ -213,13 +203,6 @@ def _add_init_parser(
             "and pyproject.toml"
         ),
     )
-    init_parser.add_argument(
-        "--source",
-        default=DEFAULT_SOURCE_URL,
-        help=(
-            f"git location of Cloudfall to install from (default: {DEFAULT_SOURCE_URL})"
-        ),
-    )
 
 
 def _add_add_parsers(
@@ -1030,16 +1013,10 @@ def _run_init(arguments: Namespace) -> int:
             if arguments.name is not None
             else ProjectName.from_directory(directory)
         )
-        revision = (
-            GitRevision.from_boundary(arguments.rev)
-            if arguments.rev is not None
-            else resolve_installed_revision()
-        )
         options = InitOptions(
             directory=directory,
             name=name,
-            revision=revision,
-            source=GitSourceUrl.from_boundary(arguments.source),
+            version=resolve_installed_version(),
             description=(
                 ProjectDescription.from_boundary(arguments.description)
                 if arguments.description is not None

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

@@ -4,7 +4,7 @@ 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 released Cloudfall the project runs with.
 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
@@ -13,7 +13,6 @@ project and are never committed.
 
 from __future__ import annotations
 
-import json
 import os
 import re
 import shutil
@@ -25,7 +24,6 @@ from enum import Enum
 from importlib import metadata
 from pathlib import Path
 from typing import TYPE_CHECKING
-from urllib.parse import urlparse
 
 from cloudfall.commands import CommandEffect, commands_with_effect
 from cloudfall.domain import ResourceKind
@@ -33,17 +31,17 @@ from cloudfall.domain import ResourceKind
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Mapping
 
-_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])?$")
-_SCP_LIKE_SOURCE_PATTERN = re.compile(
-    r"^(?P<user>[\w.-]+)@(?P<host>[\w.-]+):(?P<path>[\w./-]+)$"
+_RELEASE_VERSION_PATTERN = re.compile(
+    r"^\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.post\d+)?(?:\.dev\d+)?$"
 )
 _PROJECT_NAME_MAX_LENGTH = 64
 _PROJECT_DESCRIPTION_MAX_LENGTH = 512
 _GIT_TIMEOUT_SECONDS = 30
 _GIT_NOT_A_REPOSITORY_EXIT_CODE = 128
 
-DEFAULT_SOURCE_URL = "https://github.com/romamo/cloudfall.git"
+REPOSITORY_URL = "https://github.com/romamo/cloudfall"
+"""Location of the Cloudfall repository, for links to its files."""
 
 SECRETS_DIRECTORY = "secrets"
 """Project directory holding sops-encrypted secret fragments."""
@@ -66,9 +64,7 @@ CLAUDE_POINTER_FILE = "CLAUDE.md"
 _ERROR_NAME_UNDERIVED = "project_name_underived"
 _ERROR_DIRECTORY_MISSING = "project_directory_missing"
 _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"
@@ -100,72 +96,27 @@ class ProjectError(RuntimeError):
 
 
 @dataclass(frozen=True, slots=True)
-class GitRevision:
-    """Full 40-character commit hash a project pins Cloudfall to."""
+class ReleaseVersion:
+    """Released Cloudfall version a project pins from the package index."""
 
     value: str
 
     def __post_init__(self) -> None:
-        """Enforce the full-hash invariant at construction time."""
-        if not _GIT_REVISION_PATTERN.fullmatch(self.value):
-            message = f"git revision must be a full 40-hex commit hash: {self.value!r}"
+        """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) -> GitRevision:
+    def from_boundary(cls, value: object) -> ReleaseVersion:
         """Coerce a boundary value while keeping internal APIs strictly typed."""
         if not isinstance(value, str):
-            message = f"git revision must be a string, got {type(value).__name__}"
-            raise TypeError(message)
-        return cls(value.strip().lower())
-
-    def __str__(self) -> str:
-        """Return the serialized hash."""
-        return self.value
-
-
-@dataclass(frozen=True, slots=True)
-class GitSourceUrl:
-    """Location of the Cloudfall repository a project installs from."""
-
-    value: str
-
-    def __post_init__(self) -> None:
-        """Accept https and ssh git locations only."""
-        parsed = urlparse(self.value)
-        https = parsed.scheme == "https" and bool(parsed.netloc)
-        ssh = parsed.scheme == "ssh" and bool(parsed.netloc)
-        scp_like = _SCP_LIKE_SOURCE_PATTERN.fullmatch(self.value) is not None
-        if not (https or ssh or scp_like):
-            message = f"git source must be an https or ssh location: {self.value!r}"
-            raise ValueError(message)
-
-    @classmethod
-    def from_boundary(cls, value: object) -> GitSourceUrl:
-        """Coerce a boundary value while keeping internal APIs strictly typed."""
-        if not isinstance(value, str):
-            message = f"git source must be a string, got {type(value).__name__}"
+            message = f"release version must be a string, got {type(value).__name__}"
             raise TypeError(message)
         return cls(value.strip())
 
-    @property
-    def browse_url(self) -> str:
-        """Return the https location of the repository for links to its files.
-
-        ``https://host/owner/repo.git``, ``ssh://git@host/owner/repo.git``, and
-        ``git@host:owner/repo.git`` all browse at ``https://host/owner/repo``.
-        """
-        scp_like = _SCP_LIKE_SOURCE_PATTERN.fullmatch(self.value)
-        if scp_like is not None:
-            host, path = scp_like.group("host"), scp_like.group("path")
-        else:
-            parsed = urlparse(self.value)
-            host, path = parsed.hostname or "", parsed.path
-        path = path.strip("/").removesuffix(".git")
-        return f"https://{host}/{path}"
-
     def __str__(self) -> str:
-        """Return the serialized location."""
+        """Return the serialized version."""
         return self.value
 
 
@@ -255,8 +206,7 @@ class InitOptions:
 
     directory: Path
     name: ProjectName
-    revision: GitRevision
-    source: GitSourceUrl = GitSourceUrl(DEFAULT_SOURCE_URL)
+    version: ReleaseVersion
     description: ProjectDescription | None = None
 
 
@@ -276,8 +226,7 @@ class ProjectScaffold:
 
     directory: Path
     name: ProjectName
-    revision: GitRevision
-    source: GitSourceUrl
+    version: ReleaseVersion
     files: tuple[str, ...]
     git: GitSetup
 
@@ -288,8 +237,7 @@ class ProjectScaffold:
             "project": {
                 "directory": str(self.directory),
                 "name": str(self.name),
-                "revision": str(self.revision),
-                "source": str(self.source),
+                "version": str(self.version),
                 "git": self.git.value,
             },
             "files": list(self.files),
@@ -302,17 +250,6 @@ class ProjectScaffold:
         }
 
 
-@dataclass(frozen=True, slots=True)
-class CheckoutState:
-    """What a source checkout says about the commit it is running."""
-
-    head: str
-    clean: bool
-    """No tracked file differs from ``HEAD``, so ``HEAD`` is the running code."""
-    published: bool
-    """``HEAD`` is reachable from a remote-tracking branch, so it can be fetched."""
-
-
 def is_project(directory: Path) -> bool:
     """Return whether a directory holds at least one resource kind directory."""
     return directory.is_dir() and any(
@@ -388,69 +325,30 @@ def project_path(value: str) -> Path:
     return path
 
 
-def resolve_installed_revision(
-    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.
+def resolve_installed_version(
+    read_version: Callable[[], str] | None = None,
+) -> ReleaseVersion:
+    """Return the released version of the running Cloudfall.
 
-    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.
+    A project depends on ``cloudfall==<version>`` and resolves it from the
+    package index like any other dependency. An install whose version is not
+    a release cannot be pinned that way, which is a checkout of this
+    repository between releases.
     """
-    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)
-    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"])
-    dir_info = record.get("dir_info")
-    url = record.get("url")
-    if (
-        isinstance(dir_info, dict)
-        and isinstance(url, str)
-        and url.startswith("file://")
-    ):
-        checkout = Path(urlparse(url).path)
-        inspect = inspect_checkout or _inspect_checkout
-        return _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"
-    )
-    raise ProjectError(_ERROR_REVISION_UNRESOLVED, message)
-
-
-def _pinnable_head(checkout: Path, state: CheckoutState) -> GitRevision:
-    head = GitRevision.from_boundary(state.head)
-    if not state.clean:
-        message = (
-            f"the source checkout {checkout} has uncommitted changes, so HEAD "
-            f"{head} is not the code that is running; commit them or pass --rev"
-        )
-        raise ProjectError(_ERROR_REVISION_UNCOMMITTED, message)
-    if not state.published:
+    raw = (read_version or _installed_version)()
+    try:
+        return ReleaseVersion.from_boundary(raw)
+    except ValueError as error:
         message = (
-            f"HEAD {head} of the source checkout {checkout} is on no remote "
-            "branch, so `uv sync` could not fetch it; push it or pass --rev"
+            f"the installed cloudfall version {raw!r} is not a release, so a "
+            "project cannot pin it; install a released cloudfall, or set the "
+            "dependency in the project's pyproject.toml by hand"
         )
-        raise ProjectError(_ERROR_REVISION_UNPUBLISHED, message)
-    return head
+        raise ProjectError(_ERROR_VERSION_UNRESOLVED, message) from error
 
 
-def _installed_direct_url() -> str | None:
-    return metadata.distribution("cloudfall").read_text("direct_url.json")
+def _installed_version() -> str:
+    return metadata.version("cloudfall")
 
 
 def _git_binary() -> str:
@@ -486,15 +384,6 @@ def _git_or_fail(directory: Path, *arguments: str) -> str:
     return completed.stdout
 
 
-def _inspect_checkout(checkout: Path) -> CheckoutState:
-    head = _git_or_fail(checkout, "rev-parse", "HEAD").strip()
-    changes = _git_or_fail(checkout, "status", "--porcelain", "--untracked-files=no")
-    remote_branches = _git_or_fail(checkout, "branch", "--remotes", "--contains", head)
-    return CheckoutState(
-        head=head, clean=not changes.strip(), published=bool(remote_branches.strip())
-    )
-
-
 def _initialize_git(directory: Path) -> GitSetup:
     """Create a repository in the directory unless one already encloses it."""
     enclosing = _run_git(directory, "rev-parse", "--is-inside-work-tree")
@@ -543,8 +432,7 @@ def init_project(
     return ProjectScaffold(
         directory=directory,
         name=options.name,
-        revision=options.revision,
-        source=options.source,
+        version=options.version,
         files=tuple(files),
         git=git,
     )
@@ -561,17 +449,14 @@ 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 version 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 = ["cloudfall=={options.version}"]
 
 [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}" }}
 """
 
 
@@ -603,10 +488,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 = REPOSITORY_URL
+    ref = f"v{options.version}"
+    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
@@ -689,9 +574,9 @@ uv run cloudfall migrate --build <component>=main
 uv run cloudfall migrate --build <component>=main --yes
 ```
 
-Cloudfall is pinned to one commit in `pyproject.toml`; bump `rev` and run
-`uv sync` to move the project to a newer release. The links below point at
-the pinned commit.
+Cloudfall is pinned to one released version in `pyproject.toml`; bump it
+and run `uv sync` to move the project to a newer release. The links below
+point at the pinned release.
 
 [cloudfall]: {browse}
 [secrets-guide]: {secrets_guide}

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

@@ -8,7 +8,12 @@ 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 (
+    InitOptions,
+    ProjectName,
+    ReleaseVersion,
+    init_project,
+)
 
 ROOT = Path(__file__).parents[2]
 SCHEMAS = ROOT / "config" / "schemas" / "v1"
@@ -26,7 +31,7 @@ services:
 """
 
 
-REVISION = "5dea76ae7fdf4f99f5e8eb84b939dfa68b12ef3b"
+VERSION = "0.3.0"
 
 
 def _config(
@@ -141,7 +146,7 @@ def _fresh_project(tmp_path: Path) -> AgentToolset:
         InitOptions(
             directory=directory,
             name=ProjectName("project"),
-            revision=GitRevision(REVISION),
+            version=ReleaseVersion(VERSION),
         )
     )
     return AgentToolset(_config(tmp_path, project_directory=directory))