forktex-cloud 2.1.0__tar.gz → 2.3.0__tar.gz

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/PKG-INFO

@@ -1,21 +1,20 @@
 Metadata-Version: 2.4
 Name: forktex-cloud
-Version: 2.1.0
+Version: 2.3.0
 Summary: Typed Python SDK for the ForkTex Cloud platform — provision, deploy, and manage VPS-backed apps via a declarative manifest.
 License-Expression: MIT
 License-File: LICENSE
 Keywords: forktex,cloud,deployment,vps,hetzner,ansible,blue-green,iac,infrastructure-as-code,sdk
 Author: ForkTex
 Author-email: info@forktex.com
-Requires-Python: >=3.11
+Requires-Python: >=3.14,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Topic :: System :: Installation/Setup
@@ -40,9 +39,7 @@ Description-Content-Type: text/markdown
 
 Standalone Python SDK for the [ForkTex Cloud](https://cloud.forktex.com) platform.
 
-`forktex-cloud` is the typed `httpx` client + manifest plumbing that the `forktex` CLI uses to talk to the ForkTex Cloud control plane: project provisioning, server management, deployments, vault, manifest validation, and the docker-compose / Hetzner / Ansible bridge.
-
-You can use it directly from any Python application — no `forktex` CLI required.
+`forktex-cloud` is the typed `httpx` client + manifest plumbing for the ForkTex Cloud control plane: project provisioning, server management, deployments, vault, manifest validation, and the docker-compose / Hetzner / Ansible bridge. It was the library behind the retired `forktex cloud …` CLI; today it is used directly from Python applications, the platform's own runner, and CI.
 
 ## Install
 
@@ -50,7 +47,7 @@ You can use it directly from any Python application — no `forktex` CLI require
 pip install forktex-cloud
 ```
 
-Requires Python ≥ 3.11.
+Requires Python ≥ 3.14 (`requires-python = ">=3.14,<4.0"`).
 
 ## Quick Start
 
@@ -93,6 +90,10 @@ client = Cloud(
     account_key="ftx-dev-key-2026",
     org_id="<your-org-uuid>",
 )
+
+For integration tests or proxying through a mock/live transport, pass the
+optional `transport=` argument to `Cloud(...)` and provide any `httpx`
+transport implementation.
 ```
 
 ### Trigger a deploy pipeline
@@ -155,8 +156,8 @@ client.vault_delete("POSTGRES_PASSWORD")
 | `forktex_cloud.client` | Typed sync httpx client (`Cloud`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
 | `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1), deep-merge for env overlays, `ManifestError` |
 | `forktex_cloud.config` | `CloudContext` — controller URL, JWT / account-key, current org + project keys |
-| `forktex_cloud.scaffold` | `forktex cloud init` template generator (ProjectDeployment / StaticSite / SingleContainer / NativeBuild) |
-| `forktex_cloud.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --env local` |
+| `forktex_cloud.scaffold` | `forktex.json` template generator (formerly driven by the retired `forktex cloud init` CLI) |
+| `forktex_cloud.bridge` | docker-compose generator (local mode: `local_compose_from_manifest`, used by the repo's `scripts/local_stack.py` / `make start`; formerly by the retired `forktex cloud apply --env local` CLI), Loki config, log formatters |
 | `forktex_cloud.secrets` | Fernet vault + `${vault:KEY}` resolver for compile-time secret injection |
 | `forktex_cloud.paths` | Cross-platform `.forktex/` + `~/.forktex/` filesystem spec (V1). See [docs/forktex-directory-spec.md](https://github.com/forktex/cloud/blob/master/docs/forktex-directory-spec.md) |
 
@@ -191,7 +192,7 @@ The SDK follows [SemVer](https://semver.org/). The client's response models are
 This SDK lives inside the [`forktex/cloud`](https://github.com/forktex/cloud) monorepo alongside the API server (`api/`) and React Native client (`client/`). The SDK package is independently versioned and published to PyPI.
 
 - Docs: [https://github.com/forktex/cloud/tree/master/docs](https://github.com/forktex/cloud/tree/master/docs)
-- Production runbook: [production-runbook.md](https://github.com/forktex/cloud/blob/master/docs/production-runbook.md)
+- Operations guide: [operations.md](https://github.com/forktex/cloud/blob/master/docs/operations.md)
 - Issues: [https://github.com/forktex/cloud/issues](https://github.com/forktex/cloud/issues)
 
 ## License

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/README.md

@@ -6,9 +6,7 @@
 
 Standalone Python SDK for the [ForkTex Cloud](https://cloud.forktex.com) platform.
 
-`forktex-cloud` is the typed `httpx` client + manifest plumbing that the `forktex` CLI uses to talk to the ForkTex Cloud control plane: project provisioning, server management, deployments, vault, manifest validation, and the docker-compose / Hetzner / Ansible bridge.
-
-You can use it directly from any Python application — no `forktex` CLI required.
+`forktex-cloud` is the typed `httpx` client + manifest plumbing for the ForkTex Cloud control plane: project provisioning, server management, deployments, vault, manifest validation, and the docker-compose / Hetzner / Ansible bridge. It was the library behind the retired `forktex cloud …` CLI; today it is used directly from Python applications, the platform's own runner, and CI.
 
 ## Install
 
@@ -16,7 +14,7 @@ You can use it directly from any Python application — no `forktex` CLI require
 pip install forktex-cloud
 ```
 
-Requires Python ≥ 3.11.
+Requires Python ≥ 3.14 (`requires-python = ">=3.14,<4.0"`).
 
 ## Quick Start
 
@@ -59,6 +57,10 @@ client = Cloud(
     account_key="ftx-dev-key-2026",
     org_id="<your-org-uuid>",
 )
+
+For integration tests or proxying through a mock/live transport, pass the
+optional `transport=` argument to `Cloud(...)` and provide any `httpx`
+transport implementation.
 ```
 
 ### Trigger a deploy pipeline
@@ -121,8 +123,8 @@ client.vault_delete("POSTGRES_PASSWORD")
 | `forktex_cloud.client` | Typed sync httpx client (`Cloud`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
 | `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1), deep-merge for env overlays, `ManifestError` |
 | `forktex_cloud.config` | `CloudContext` — controller URL, JWT / account-key, current org + project keys |
-| `forktex_cloud.scaffold` | `forktex cloud init` template generator (ProjectDeployment / StaticSite / SingleContainer / NativeBuild) |
-| `forktex_cloud.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --env local` |
+| `forktex_cloud.scaffold` | `forktex.json` template generator (formerly driven by the retired `forktex cloud init` CLI) |
+| `forktex_cloud.bridge` | docker-compose generator (local mode: `local_compose_from_manifest`, used by the repo's `scripts/local_stack.py` / `make start`; formerly by the retired `forktex cloud apply --env local` CLI), Loki config, log formatters |
 | `forktex_cloud.secrets` | Fernet vault + `${vault:KEY}` resolver for compile-time secret injection |
 | `forktex_cloud.paths` | Cross-platform `.forktex/` + `~/.forktex/` filesystem spec (V1). See [docs/forktex-directory-spec.md](https://github.com/forktex/cloud/blob/master/docs/forktex-directory-spec.md) |
 
@@ -157,7 +159,7 @@ The SDK follows [SemVer](https://semver.org/). The client's response models are
 This SDK lives inside the [`forktex/cloud`](https://github.com/forktex/cloud) monorepo alongside the API server (`api/`) and React Native client (`client/`). The SDK package is independently versioned and published to PyPI.
 
 - Docs: [https://github.com/forktex/cloud/tree/master/docs](https://github.com/forktex/cloud/tree/master/docs)
-- Production runbook: [production-runbook.md](https://github.com/forktex/cloud/blob/master/docs/production-runbook.md)
+- Operations guide: [operations.md](https://github.com/forktex/cloud/blob/master/docs/operations.md)
 - Issues: [https://github.com/forktex/cloud/issues](https://github.com/forktex/cloud/issues)
 
 ## License

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forktex-cloud"
-version = "2.1.0"
+version = "2.3.0"
 description = "Typed Python SDK for the ForkTex Cloud platform — provision, deploy, and manage VPS-backed apps via a declarative manifest."
 authors = [
     {name = "ForkTex", email = "info@forktex.com"}
@@ -8,7 +8,7 @@ authors = [
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.11"
+requires-python = ">=3.14,<4.0"
 keywords = [
     "forktex",
     "cloud",
@@ -28,8 +28,7 @@ classifiers = [
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Distributed Computing",
     "Topic :: System :: Installation/Setup",
@@ -61,10 +60,15 @@ dev = [
     "ruff (>=0.8.0)",
     "pyright (>=1.1.0,<2.0.0)",
     "mypy (>=1.11.0,<2.0.0)",
+    # Release tooling. `make build` and `make publish` shell out to these, so
+    # undeclared they turn a release into "No module named twine" at the moment
+    # you try to ship. Same pair, same versions, as ../forktex-py.
+    "build (>=1.2.0)",
+    "twine (>=5.0.0)",
 ]
 
 [tool.ruff]
-target-version = "py311"
+target-version = "py314"
 line-length = 100
 extend-exclude = [
     # Auto-generated by OpenAPI codegen. Canonical import shape comes from
@@ -76,6 +80,13 @@ extend-exclude = [
 [tool.ruff.lint]
 select = ["E", "F", "I", "W"]
 
+[tool.mypy]
+plugins = ["pydantic.mypy"]
+ignore_missing_imports = true
+# Auto-generated from the OpenAPI spec — committed for drift-checking but not
+# subject to hand-typing (mirrors the api codegen/build exclude).
+exclude = ["client/generated"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/src/forktex_cloud/__init__.py

@@ -41,8 +41,10 @@ __version__ = "2.1.0"
 # model lookups hit the module-level cache populated by __getattr__.
 _LAZY_ATTRS: dict[str, tuple[str, str]] = {
     # Client (httpx-backed, heavy)
-    "Cloud": ("forktex_cloud.client.client", "Cloud"),
+    "Cloud": ("forktex_cloud.client.facade", "Cloud"),
+    "CloudClient": ("forktex_cloud.client.client", "CloudClient"),
     "CloudAPIError": ("forktex_cloud.client.client", "CloudAPIError"),
+    "DeployBlocked": ("forktex_cloud.client.client", "DeployBlocked"),
     # Config
     "CloudContext": ("forktex_cloud.config", "CloudContext"),
     # Manifest
@@ -65,7 +67,6 @@ _LAZY_ATTRS: dict[str, tuple[str, str]] = {
     "TokenResponse": ("forktex_cloud.client.generated", "TokenResponse"),
     "UserRead": ("forktex_cloud.client.generated", "UserRead"),
     "VaultGetResponse": ("forktex_cloud.client.generated", "VaultGetResponse"),
-    "WorkspaceRead": ("forktex_cloud.client.generated", "WorkspaceRead"),
 }
 
 
@@ -93,7 +94,8 @@ def __dir__() -> list[str]:
 # Static type-checker hint — declared as a TYPE_CHECKING block so it costs
 # nothing at runtime but lets editors / mypy see the eventual symbol types.
 if TYPE_CHECKING:  # pragma: no cover
-    from forktex_cloud.client.client import Cloud, CloudAPIError
+    from forktex_cloud.client.client import CloudAPIError, CloudClient, DeployBlocked
+    from forktex_cloud.client.facade import Cloud
     from forktex_cloud.client.generated import (
         SPEC_HASH,
         SPEC_VERSION,
@@ -111,7 +113,6 @@ if TYPE_CHECKING:  # pragma: no cover
         TokenResponse,
         UserRead,
         VaultGetResponse,
-        WorkspaceRead,
     )
     from forktex_cloud.config import CloudContext
     from forktex_cloud.manifest.loader import Manifest, ManifestError
@@ -123,7 +124,9 @@ __all__ = [
     "SPEC_HASH",
     # Client — lazy
     "Cloud",
+    "CloudClient",
     "CloudAPIError",
+    "DeployBlocked",
     # Config — lazy
     "CloudContext",
     # Manifest — lazy
@@ -144,5 +147,4 @@ __all__ = [
     "TokenResponse",
     "UserRead",
     "VaultGetResponse",
-    "WorkspaceRead",
 ]

forktex_cloud-2.3.0/src/forktex_cloud/bridge/__init__.py

@@ -0,0 +1,25 @@
+"""Bridge modules: manifest → docker compose for local dev, plus log helpers.
+
+``local_compose_from_manifest`` is the pure renderer the cloud repo's
+``scripts/local_stack.py`` drives; it returns a compose dict and writes nothing.
+"""
+
+from forktex_cloud.bridge.local_compose import (
+    local_compose_from_manifest,
+    render_observability_configs,
+)
+from forktex_cloud.bridge.log_formatter import assign_colors, format_line
+from forktex_cloud.bridge.loki import build_logql, loki_ready, query_range, tail
+from forktex_cloud.bridge.persistence_defaults import detect_persistence_defaults
+
+__all__ = [
+    "assign_colors",
+    "build_logql",
+    "detect_persistence_defaults",
+    "format_line",
+    "local_compose_from_manifest",
+    "loki_ready",
+    "query_range",
+    "render_observability_configs",
+    "tail",
+]

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/src/forktex_cloud/bridge/local_compose.py

@@ -194,6 +194,22 @@ def _add_observability_services(
     }
 
 
+def _observability_enabled(manifest: Manifest) -> bool:
+    """Whether the manifest asks for the local Loki/Promtail pair.
+
+    The `observability` argument is the caller's veto, not the answer: a
+    manifest that sets `observability.enabled: false` — as a project whose
+    local stack runs beside another one does, to keep Loki's 3100 free — still
+    got both containers, because the flag defaulted to True and nothing
+    consulted the manifest.
+    """
+    cloud = getattr(manifest, "cloud", None)
+    obs = getattr(cloud, "observability", None)
+    if obs is None:
+        return True
+    return bool(getattr(obs, "enabled", True))
+
+
 def local_compose_from_manifest(
     manifest: Manifest,
     project_root: Path,
@@ -245,8 +261,8 @@ def local_compose_from_manifest(
     # behind the initializer's start. We can't wait on `service_completed`
     # for a true oneshot the way k8s init-containers do, but the
     # ``service_started`` ordering closes the most common race (e.g.
-    # gitea-init writes the token file → api can read it on its first
-    # gitea call). The initializer itself self-polls its dependencies.
+    # an initializer writes state the primary reads on its first call).
+    # The initializer itself self-polls its dependencies.
     oneshot_ids: list[str] = [
         svc_def["id"]
         for svc_def in local_services
@@ -280,7 +296,7 @@ def local_compose_from_manifest(
                 build_entry["dockerfile"] = dockerfile
             _require_dockerfile(ctx_dir, dockerfile, sid=sid, context=ctx)
             svc["build"] = build_entry
-        elif svc_type == "compute":
+        elif svc_type in ("compute", "daemon"):
             found = _autodetect_dockerfile(project_root / sid, env_name)
             if found is not None:
                 build_entry = {"context": _project_relative(f"./{sid}", root_prefix)}
@@ -291,14 +307,18 @@ def local_compose_from_manifest(
         if sid in host_ports:
             host_port = host_ports[sid]
             svc["ports"] = [f"{host_port}:{port}"]
+        # Additional host:container mappings (e.g. mailhog UI 8025:8025).
+        extra_ports = svc_def.get("extraPorts") or []
+        if extra_ports:
+            svc.setdefault("ports", []).extend(str(p) for p in extra_ports)
 
-        # One-shot init services (e.g. `gitea-init`) carry the
+        # One-shot init services carry the
         # `forktex.oneshot=true` label so the generator skips the implicit
         # restart-always; they should exit cleanly after their seed step
         # and stay exited. The label lives on the existing ServiceDef
         # `labels` field — no schema/codegen change required.
         is_oneshot = (svc_def.get("labels") or {}).get("forktex.oneshot") == "true"
-        if svc_type in ("persistence", "observability") and not is_oneshot:
+        if svc_type in ("persistence", "daemon", "observability") and not is_oneshot:
             svc["restart"] = "always"
         if svc_def.get("labels"):
             svc["labels"] = dict(svc_def["labels"])
@@ -349,7 +369,7 @@ def local_compose_from_manifest(
         if svc_type == "persistence":
             # Bind-mount persistence data under .forktex/data/{sid}/ so it
             # survives `docker compose down -v` and is visible on the host
-            # for inspection + backups. Mirrors api/src/bridge/local_compose.py.
+            # for inspection + backups.
             defaults = detect_persistence_defaults(image)
             if defaults and defaults.get("default_volume"):
                 target = defaults["default_volume"]
@@ -362,7 +382,7 @@ def local_compose_from_manifest(
         if cmd:
             svc["command"] = cmd
 
-        if svc_type == "compute":
+        if svc_type in ("compute", "daemon"):
             depends: dict[str, Any] = {}
             for pid in persistence_ids:
                 healthy = persistence_has_healthcheck.get(pid)
@@ -371,7 +391,10 @@ def local_compose_from_manifest(
             for iid in oneshot_ids:
                 # Initializers run side-by-side; we only need start-ordering,
                 # not completion. The initializer's contract is "write its
-                # output before the first compute request needs it."
+                # output before the first compute request needs it." A oneshot
+                # that is itself a daemon must not wait on itself.
+                if iid == sid:
+                    continue
                 depends[iid] = {"condition": "service_started"}
             if depends:
                 svc["depends_on"] = depends
@@ -383,7 +406,7 @@ def local_compose_from_manifest(
         svc["networks"] = ["forktex"]
         services[sid] = svc
 
-    if observability:
+    if observability and _observability_enabled(manifest):
         _add_observability_services(services, named_volumes)
 
     compose: dict[str, Any] = {"services": services}

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/src/forktex_cloud/bridge/loki.py

@@ -16,7 +16,7 @@ def loki_ready(base_url: str = "http://localhost:3100") -> bool:
         req = urllib.request.Request(f"{base_url}/ready", method="GET")
         with urllib.request.urlopen(req, timeout=2) as resp:
             return resp.status == 200
-    except (urllib.error.URLError, OSError):
+    except urllib.error.URLError, OSError:
         return False
 
 
@@ -77,7 +77,7 @@ def tail(
         now_ns = int(time.time() * 1_000_000_000)
         try:
             entries = query_range(base_url, logql, last_ts + 1, now_ns)
-        except (urllib.error.URLError, OSError):
+        except urllib.error.URLError, OSError:
             return
         for ts_ns, service, line in entries:
             yield (ts_ns, service, line)

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/src/forktex_cloud/bridge/persistence_defaults.py

@@ -60,11 +60,24 @@ PERSISTENCE_DEFAULTS: dict[str, dict[str, Any]] = {
         "default_volume": "/data/db",
     },
     "qdrant": {
+        # The qdrant image ships no wget, curl or nc — only bash. So the probe
+        # speaks HTTP over /dev/tcp rather than shelling out to a client that is
+        # not there. It must be `CMD` + an explicit `bash -c`: /dev/tcp is a bash
+        # builtin, and `CMD-SHELL` runs /bin/sh, where it fails with "cannot
+        # create /dev/tcp/..." — indistinguishable from a down node.
+        # `/readyz` rather than a bare port open: a bound socket is not a node
+        # that is ready to serve.
         "healthcheck": {
-            "test": ["CMD-SHELL", "bash -c 'echo > /dev/tcp/localhost/6333'"],
-            "interval": "5s",
-            "timeout": "5s",
-            "retries": 10,
+            "test": [
+                "CMD",
+                "bash",
+                "-c",
+                'exec 3<>/dev/tcp/localhost/6333; printf "GET /readyz HTTP/1.0\\r\\n\\r\\n" >&3; '
+                'head -1 <&3 | grep -q "200 OK"',
+            ],
+            "interval": "30s",
+            "timeout": "10s",
+            "retries": 5,
         },
         "default_port": 6333,
         "default_volume": "/qdrant/storage",

{forktex_cloud-2.1.0 → forktex_cloud-2.3.0}/src/forktex_cloud/client/__init__.py

@@ -6,7 +6,8 @@ commonly used ones so call sites can ``from forktex_cloud.client import X``
 without touching the ``generated`` namespace directly.
 """
 
-from forktex_cloud.client.client import Cloud, CloudAPIError
+from forktex_cloud.client.client import CloudAPIError, CloudClient, DeployBlocked
+from forktex_cloud.client.facade import Cloud
 from forktex_cloud.client.generated import (
     ApiKeyCreated,
     ApiKeyRead,
@@ -31,12 +32,13 @@ from forktex_cloud.client.generated import (
     TokenResponse,
     UserRead,
     VaultGetResponse,
-    WorkspaceRead,
 )
 
 __all__ = [
     "Cloud",
+    "CloudClient",
     "CloudAPIError",
+    "DeployBlocked",
     "ApiKeyCreated",
     "ApiKeyRead",
     "CapacityOrgLimits",
@@ -60,5 +62,4 @@ __all__ = [
     "TokenResponse",
     "UserRead",
     "VaultGetResponse",
-    "WorkspaceRead",
 ]