forktex-cloud 0.2.3__py3-none-any.whl

forktex_cloud/secrets/resolver.py

@@ -0,0 +1,59 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of forktex-cloud.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Resolve ``${vault:KEY}`` references in environment dicts."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from forktex_cloud.secrets.base import SecretsProvider
+
+_VAULT_PATTERN = re.compile(r"\$\{vault:([^}]+)\}")
+
+
+def has_vault_references(env_dict: dict[str, Any]) -> bool:
+    """Return True if any value contains a ``${vault:...}`` reference."""
+    for v in env_dict.values():
+        if isinstance(v, str) and _VAULT_PATTERN.search(v):
+            return True
+    return False
+
+
+def resolve_secrets(
+    env_dict: dict[str, Any],
+    provider: SecretsProvider,
+    env: str = "default",
+) -> dict[str, Any]:
+    """Replace ``${vault:KEY}`` references with actual secret values."""
+    resolved: dict[str, Any] = {}
+    for k, v in env_dict.items():
+        if isinstance(v, str) and _VAULT_PATTERN.search(v):
+            resolved[k] = _VAULT_PATTERN.sub(
+                lambda m: provider.get(m.group(1), env),
+                v,
+            )
+        else:
+            resolved[k] = v
+    return resolved

forktex_cloud/templates/observability/loki.yml

@@ -0,0 +1,55 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of forktex-cloud.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+
+common:
+  path_prefix: /loki
+  storage:
+    filesystem:
+      chunks_directory: /loki/chunks
+      rules_directory: /loki/rules
+  replication_factor: 1
+  ring:
+    kvstore:
+      store: inmemory
+
+schema_config:
+  configs:
+    - from: "2020-10-24"
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+limits_config:
+  reject_old_samples: true
+  reject_old_samples_max_age: 168h
+
+analytics:
+  reporting_enabled: false

forktex_cloud/templates/observability/promtail.yml

@@ -0,0 +1,46 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of forktex-cloud.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: http://loki:3100/loki/api/v1/push
+
+scrape_configs:
+  - job_name: docker
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 5s
+    relabel_configs:
+      - source_labels: ["__meta_docker_container_name"]
+        regex: "/(.*)"
+        target_label: "container"
+      - source_labels: ["__meta_docker_container_log_stream"]
+        target_label: "logstream"
+      - source_labels: ["__meta_docker_container_label_com_docker_compose_service"]
+        target_label: "service"

forktex_cloud-0.2.3.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: forktex-cloud
+Version: 0.2.3
+Summary: Typed Python SDK for the ForkTex Cloud platform — provision, deploy, and manage VPS-backed apps via a declarative manifest.
+License-Expression: AGPL-3.0-only
+License-File: LICENSE
+License-File: NOTICE
+Keywords: forktex,cloud,deployment,vps,hetzner,ansible,blue-green,iac,infrastructure-as-code,sdk
+Author: FORKTEX
+Author-email: info@forktex.com
+Requires-Python: >=3.12
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Dist: cryptography (>=42.0)
+Requires-Dist: httpx (>=0.27.0,<1.0.0)
+Requires-Dist: pydantic[email] (>=2.11.10,<3.0.0)
+Requires-Dist: pyyaml (>=6.0)
+Project-URL: Changelog, https://github.com/forktex/cloud/blob/master/sdk-py/CHANGELOG.md
+Project-URL: Documentation, https://github.com/forktex/cloud/tree/master/docs
+Project-URL: Homepage, https://forktex.com
+Project-URL: Issues, https://github.com/forktex/cloud/issues
+Project-URL: Repository, https://github.com/forktex/cloud
+Description-Content-Type: text/markdown
+
+# forktex-cloud
+
+[![PyPI](https://img.shields.io/pypi/v/forktex-cloud.svg)](https://pypi.org/project/forktex-cloud/)
+[![Python](https://img.shields.io/pypi/pyversions/forktex-cloud.svg)](https://pypi.org/project/forktex-cloud/)
+[![License](https://img.shields.io/pypi/l/forktex-cloud.svg)](https://github.com/forktex/cloud/blob/master/sdk-py/LICENSE)
+
+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.
+
+## Install
+
+```bash
+pip install forktex-cloud
+```
+
+**Requires Python 3.12+.** Tested on 3.12, 3.13, 3.14.
+
+## Quick Start
+
+### Authenticated client
+
+```python
+from forktex_cloud import ForktexCloudClient, CloudContext
+
+ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
+with ForktexCloudClient.from_context(ctx) as client:
+    projects = client.list_projects()
+    servers  = client.list_servers()
+    health   = client.health()
+```
+
+### Direct auth
+
+```python
+from forktex_cloud import ForktexCloudClient
+
+# JWT bearer (user login)
+with ForktexCloudClient("https://cloud.forktex.com", access_token="eyJ...") as client:
+    me = client.me()
+
+# Org-scoped API key (CI/CD)
+with ForktexCloudClient(
+    "https://cloud.forktex.com",
+    account_key="ftx-...",
+    org_id="00000000-0000-0000-0000-000000000001",
+) as client:
+    events = client.list_events(project_id="...")
+    status = client.server_status("server-uuid")
+```
+
+### Local dev (point at your `make local` stack)
+
+```python
+client = ForktexCloudClient(
+    base_url="http://localhost:8000",
+    account_key="ftx-dev-key-2026",
+    org_id="<your-org-uuid>",
+)
+```
+
+### Trigger a deploy pipeline
+
+```python
+# Full up (provision + bootstrap + deploy + DNS + SSL)
+job = client.up(project_dir=Path("./my-project"))      # reads forktex.json
+print(job.job_id, job.deployment_id, job.status)
+
+# Code push to an existing server (no re-provision)
+job = client.deploy(server_id="...", service="api")    # Ansible deploy tag
+
+# Tear down
+job = client.down(keep_dns=True)                       # preserves DNS record
+```
+
+### Manifest loading + validation
+
+```python
+from forktex_cloud import Manifest, ManifestError
+
+# Validates eagerly against the canonical Pydantic schema at construction
+try:
+    m = Manifest.load("forktex.json", env="production")
+except ManifestError as e:
+    print(f"Invalid manifest: {e}")
+    raise
+
+# Typed access to the cloud block (discriminated union over all 4 kinds)
+print(m.cloud.kind)                     # "ProjectDeployment" | "StaticSite" | ...
+print(m.cloud.metadata.name)
+for svc in m.services_for_env(env="production"):
+    print(svc.id, svc.type, svc.image)
+
+# Wire format round-trips cleanly (model_dump → parse_cloud_block)
+as_dict = m.cloud.model_dump(by_alias=True, exclude_none=True)
+```
+
+### Secrets vault (server-side, org-scoped)
+
+```python
+client.vault_set("POSTGRES_PASSWORD", "hunter2")
+secret = client.vault_get("POSTGRES_PASSWORD")           # -> VaultGetResponse
+keys   = client.vault_list()                             # -> list[str]
+client.vault_delete("POSTGRES_PASSWORD")
+```
+
+## What's in the package
+
+| Module | Purpose |
+|---|---|
+| `forktex_cloud.client` | Typed sync httpx client (`ForktexCloudClient`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
+| `forktex_cloud.manifest` | `Manifest` loader, discriminated-union schema (v1beta2), 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 up --env local` |
+| `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) |
+
+All response models come from the OpenAPI codegen pipeline — **one source of truth** shared between the server and every consumer. No hand-written model drift.
+
+## Top-level re-exports
+
+```python
+from forktex_cloud import (
+    # Client
+    ForktexCloudClient, CloudAPIError,
+    # Config
+    CloudContext,
+    # Manifest
+    Manifest, ManifestError,
+    # Response models (from OpenAPI codegen)
+    ApiKeyCreated, ApiKeyRead,
+    EnvironmentRead, EventRead,
+    HealthRead, JobResponse, MeResponse,
+    OrgRead, ProjectRead, ServerRead, UserRead,
+    StatusResponse, TokenResponse, VaultGetResponse,
+    WorkspaceRead,
+)
+```
+
+## Versioning
+
+The SDK follows [SemVer](https://semver.org/). The client's response models are generated from the server's OpenAPI spec at a fixed `SPEC_VERSION` + `SPEC_HASH` (inspectable at runtime via `forktex_cloud.client.generated.SPEC_VERSION`). When the server OpenAPI changes, the SDK is regenerated and released with a bumped version.
+
+## Repository
+
+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)
+- Issues: [https://github.com/forktex/cloud/issues](https://github.com/forktex/cloud/issues)
+
+## Development
+
+The [`Makefile`](Makefile) is generated by `forktex fsd makefile sync` from [`forktex.json`](forktex.json) — do not hand-edit.
+
+```bash
+make help              # list every available target
+make deps              # editable install with the dev group
+make format            # ruff format
+make lint              # ruff check
+make test              # pytest tests/
+make codegen-check     # verify the generated client imports cleanly
+make build             # python3 -m build → dist/
+make ci                # format-check + lint + license-check + audit + test + build
+make clean             # remove caches and dist/
+```
+
+`make ci` is the single command that gates a publish: format-check, lint, dual-license header check, dependency CVE audit, full test suite, and `python -m build` + `twine check`.
+
+### License headers
+
+Every source file carries the AGPL-3.0 + Commercial dual-license SPDX header, applied idempotently via:
+
+```bash
+make license-check    # CI gate — fails if any source file is missing the header
+make license-fix      # add or refresh headers across src/, tests/, scripts/
+make license-strip    # remove headers (used before license-model changes)
+```
+
+## License
+
+Dual-licensed — **AGPL-3.0-or-later** for open-source use, **commercial** for everything else (proprietary products, SaaS without source release, redistribution in closed-source form). See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for the full terms.
+
+Commercial licensing inquiries: info@forktex.com.
+
+The 1.0.x releases on PyPI remain under MIT; from **0.2.3** onwards the package ships AGPL-3.0+Commercial.
+

forktex_cloud-0.2.3.dist-info/RECORD

@@ -0,0 +1,30 @@
+forktex_cloud/__init__.py,sha256=NUmtssYqSXwQmsEiM-q8BhZvVqYb1hYJL9Tcmmt4j2A,2651
+forktex_cloud/bridge/__init__.py,sha256=R7xeSF6i0kjFuHokArxVblTy3_QPFyAsJXXWdPcR04M,1102
+forktex_cloud/bridge/local_compose.py,sha256=-6w_QIsEc47fPZvSp3lEmguclyDKtePpZQfNDwlmMRs,10453
+forktex_cloud/bridge/log_formatter.py,sha256=0wnHNH5JFmofR-xqAaBQJmRLIov2_O3lykAwnuA8IjE,2059
+forktex_cloud/bridge/loki.py,sha256=cYL76e0SqpoI7X9YpvZwMehKbFFSfy_gzwNWqt8z0uQ,3744
+forktex_cloud/bridge/persistence_defaults.py,sha256=hAMTg-gZlcogqNmJSzRVEwHCav4nzFUKaCnWhoXbPcQ,3862
+forktex_cloud/client/__init__.py,sha256=ryD26sslNjop3bYCDjvy_nfXPDBq44FU2OKI1joZvQA,2392
+forktex_cloud/client/client.py,sha256=Zc7FEP5rXD1fujIZ9GcssDBmkIPjLj7VeX-BFN-QS8A,22398
+forktex_cloud/client/generated/__init__.py,sha256=u-SpzKCvUigI0CCc0iBXlevZOfBdcU4TDDv8uXGy4mA,38276
+forktex_cloud/config.py,sha256=oeOFV0rPkMrDNiVEli-zP8gurjlvpWRJ9Ump7NEonzs,2426
+forktex_cloud/manifest/__init__.py,sha256=zHW86vpxfBUPVEmQ9HbxkR5Xa4mjPdVtJrd9CVUDlTo,2100
+forktex_cloud/manifest/errors.py,sha256=2qXugnSZRyhVLeBFKCmm55mMxtVTCbfBKcfvffgAl6o,1331
+forktex_cloud/manifest/loader.py,sha256=AjZwSKMntiuXGfONosUAOd3lbwYxCLt36ht01qkvXBU,9929
+forktex_cloud/manifest/merge.py,sha256=alBUVw7q1X4bbya1QzBaD1Y3BZuaBbgXpz_NvaWL8M4,2013
+forktex_cloud/manifest/schema.py,sha256=05x-xfrH-vqGitmJD2VskXCl11YdJ7nQpyKhVkWHO-A,3171
+forktex_cloud/paths.py,sha256=nuxr5fA-He-JyzSY3PM9P963gdPljCtMZMA1__De990,8801
+forktex_cloud/scaffold/__init__.py,sha256=OpSAWLLho9D5TARs5q4k9hvswsUSp9oerFWbh5xkT3Q,1075
+forktex_cloud/scaffold/templates.py,sha256=zhmnlBkePisYp5q8w5kwmcZ5YpdicbdI-2BpiiNs460,4417
+forktex_cloud/secrets/__init__.py,sha256=ibv-l7jDTFgnzHknxNfvHo3vPHhjXz0PiKa0yRcVywU,1126
+forktex_cloud/secrets/base.py,sha256=G91FYUMlZCR5UCm2ql7zo0gGeWfi8RJh3NPziDsyo_I,1790
+forktex_cloud/secrets/factory.py,sha256=a8RYMxgtmtIalevZRnxKmBVZh3ELoreXdL3lFXnKfOI,2023
+forktex_cloud/secrets/fernet.py,sha256=jNZVKZWnHoVxk8FVf87rYq6niNRAfpOOeIbGnS3AYBU,3446
+forktex_cloud/secrets/resolver.py,sha256=VsByVtlqfxOnPshhrJKS3kiESAiF8VwHHTGRjy9tPIs,2080
+forktex_cloud/templates/observability/loki.yml,sha256=2qQkdZP0Z9VVbqdBDEvTJ3GRNFDLTi5Z8YRspLdpSq4,1580
+forktex_cloud/templates/observability/promtail.yml,sha256=6em4DEU6K8KYttF89nzB8NyedEkoJKkb3mHCC0AiWog,1668
+forktex_cloud-0.2.3.dist-info/METADATA,sha256=PBX5pCPWKSCDSvzRuLejTR6c4wA4FTxGJgRJZk6B85c,9313
+forktex_cloud-0.2.3.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+forktex_cloud-0.2.3.dist-info/licenses/LICENSE,sha256=kz6KCanl6TKXrtl40HZqVKvTjyNx74uE01UMd0K4dRs,1921
+forktex_cloud-0.2.3.dist-info/licenses/NOTICE,sha256=NGffqf9xgVbrPpPb5_V3fpm6CM0MdlPJE2XDcNXE05E,1076
+forktex_cloud-0.2.3.dist-info/RECORD,,

forktex_cloud-0.2.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any

forktex_cloud-0.2.3.dist-info/licenses/LICENSE

@@ -0,0 +1,45 @@
+forktex-cloud -- Dual License
+
+Copyright (C) 2026 FORKTEX S.R.L.
+
+This software is licensed under a dual-license model:
+
+============================================================================
+
+1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
+
+   You may use, modify, and redistribute this software under the terms of the
+   GNU Affero General Public License v3.0 or later, as published by the Free
+   Software Foundation. The full license text is available at:
+   https://www.gnu.org/licenses/agpl-3.0.html
+
+   Key obligations under AGPL-3.0:
+   - Any modified version MUST be released under the same AGPL-3.0 license.
+   - If you run a modified version on a server and let users interact with it
+     over a network, you MUST make the complete source code available to those
+     users under AGPL-3.0.
+   - You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
+
+============================================================================
+
+2. COMMERCIAL LICENSE
+
+   If you wish to use this software without the obligations of AGPL-3.0 --
+   for example, to keep your modifications proprietary, to embed this software
+   in a closed-source product, or to operate it as part of a commercial service
+   without releasing your source code -- you MUST obtain a commercial license
+   from FORKTEX S.R.L.
+
+   Commercial licensing includes, but is not limited to:
+   - SaaS / hosted deployments generating revenue
+   - Embedding in proprietary products or platforms
+   - Redistribution in closed-source form
+   - Use by organizations exceeding the AGPL-3.0 compliance scope
+
+   For commercial licensing inquiries, contact:
+     info@forktex.com
+
+============================================================================
+
+Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
+your use of this software is governed exclusively by the AGPL-3.0 license.

forktex_cloud-0.2.3.dist-info/licenses/NOTICE

@@ -0,0 +1,23 @@
+forktex-cloud
+Copyright (C) 2026 FORKTEX S.R.L.
+
+forktex-cloud is the standalone Python SDK for the ForkTex Cloud platform.
+It provides the typed httpx-based client and Pydantic models for provisioning
+servers, deploying projects, managing static sites, single-container apps and
+native builds, vault secrets, blue-green rollouts, and the declarative
+forktex.json cloud manifest.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing inquiries, contact: info@forktex.com