forktex-cloud 0.2.4__tar.gz → 0.5.0__tar.gz

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forktex-cloud
-Version: 0.2.4
+Version: 0.5.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
@@ -57,10 +57,10 @@ Requires Python ≥ 3.11.
 ### Authenticated client
 
 ```python
-from forktex_cloud import ForktexCloudClient, CloudContext
+from forktex_cloud import Cloud, CloudContext
 
 ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
-with ForktexCloudClient.from_context(ctx) as client:
+with Cloud.from_context(ctx) as client:
     projects = client.list_projects()
     servers  = client.list_servers()
     health   = client.health()
@@ -69,14 +69,14 @@ with ForktexCloudClient.from_context(ctx) as client:
 ### Direct auth
 
 ```python
-from forktex_cloud import ForktexCloudClient
+from forktex_cloud import Cloud
 
 # JWT bearer (user login)
-with ForktexCloudClient("https://cloud.forktex.com", access_token="eyJ...") as client:
+with Cloud("https://cloud.forktex.com", access_token="eyJ...") as client:
     me = client.me()
 
 # Org-scoped API key (CI/CD)
-with ForktexCloudClient(
+with Cloud(
     "https://cloud.forktex.com",
     account_key="ftx-...",
     org_id="00000000-0000-0000-0000-000000000001",
@@ -88,7 +88,7 @@ with ForktexCloudClient(
 ### Local dev (point at your `make local` stack)
 
 ```python
-client = ForktexCloudClient(
+client = Cloud(
     base_url="http://localhost:8000",
     account_key="ftx-dev-key-2026",
     org_id="<your-org-uuid>",
@@ -98,15 +98,23 @@ client = ForktexCloudClient(
 ### Trigger a deploy pipeline
 
 ```python
-# Full up (provision + bootstrap + deploy + DNS + SSL)
-job = client.up(project_dir=Path("./my-project"))      # reads forktex.json
+# Preview what an apply WOULD do (read-only, no mutation):
+plan = client.plan(project_dir=Path("./my-project"), env="production")
+print(plan.manifest_diff)            # added / removed / changed paths
+for role in plan.ansible_plan:
+    print(f"  {role.role}: {role.changed} changed, {role.failed} failed")
+    for d in role.diffs:
+        print(f"    {d.task}: {d.before_header}")  # file-level diff hints
+
+# Full apply (provision + bootstrap + deploy + DNS + SSL)
+job = client.apply(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
+job = client.destroy(keep_dns=True)                       # preserves DNS record
 ```
 
 ### Manifest loading + validation
@@ -144,11 +152,11 @@ client.vault_delete("POSTGRES_PASSWORD")
 
 | Module | Purpose |
 |---|---|
-| `forktex_cloud.client` | Typed sync httpx client (`ForktexCloudClient`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
+| `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 (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.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --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) |
 
@@ -159,7 +167,7 @@ All response models come from the OpenAPI codegen pipeline — **one source of t
 ```python
 from forktex_cloud import (
     # Client
-    ForktexCloudClient, CloudAPIError,
+    Cloud, CloudAPIError,
     # Config
     CloudContext,
     # Manifest

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/README.md

@@ -23,10 +23,10 @@ Requires Python ≥ 3.11.
 ### Authenticated client
 
 ```python
-from forktex_cloud import ForktexCloudClient, CloudContext
+from forktex_cloud import Cloud, CloudContext
 
 ctx = CloudContext(controller="https://cloud.forktex.com", account_key="ftx-...")
-with ForktexCloudClient.from_context(ctx) as client:
+with Cloud.from_context(ctx) as client:
     projects = client.list_projects()
     servers  = client.list_servers()
     health   = client.health()
@@ -35,14 +35,14 @@ with ForktexCloudClient.from_context(ctx) as client:
 ### Direct auth
 
 ```python
-from forktex_cloud import ForktexCloudClient
+from forktex_cloud import Cloud
 
 # JWT bearer (user login)
-with ForktexCloudClient("https://cloud.forktex.com", access_token="eyJ...") as client:
+with Cloud("https://cloud.forktex.com", access_token="eyJ...") as client:
     me = client.me()
 
 # Org-scoped API key (CI/CD)
-with ForktexCloudClient(
+with Cloud(
     "https://cloud.forktex.com",
     account_key="ftx-...",
     org_id="00000000-0000-0000-0000-000000000001",
@@ -54,7 +54,7 @@ with ForktexCloudClient(
 ### Local dev (point at your `make local` stack)
 
 ```python
-client = ForktexCloudClient(
+client = Cloud(
     base_url="http://localhost:8000",
     account_key="ftx-dev-key-2026",
     org_id="<your-org-uuid>",
@@ -64,15 +64,23 @@ client = ForktexCloudClient(
 ### Trigger a deploy pipeline
 
 ```python
-# Full up (provision + bootstrap + deploy + DNS + SSL)
-job = client.up(project_dir=Path("./my-project"))      # reads forktex.json
+# Preview what an apply WOULD do (read-only, no mutation):
+plan = client.plan(project_dir=Path("./my-project"), env="production")
+print(plan.manifest_diff)            # added / removed / changed paths
+for role in plan.ansible_plan:
+    print(f"  {role.role}: {role.changed} changed, {role.failed} failed")
+    for d in role.diffs:
+        print(f"    {d.task}: {d.before_header}")  # file-level diff hints
+
+# Full apply (provision + bootstrap + deploy + DNS + SSL)
+job = client.apply(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
+job = client.destroy(keep_dns=True)                       # preserves DNS record
 ```
 
 ### Manifest loading + validation
@@ -110,11 +118,11 @@ client.vault_delete("POSTGRES_PASSWORD")
 
 | Module | Purpose |
 |---|---|
-| `forktex_cloud.client` | Typed sync httpx client (`ForktexCloudClient`) + all OpenAPI-codegenned Pydantic models (`ServerRead`, `ProjectRead`, `EventRead`, `VaultGetResponse`, ...) |
+| `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 (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.bridge` | docker-compose generator (local mode), Loki config, log formatters used by `forktex cloud apply --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) |
 
@@ -125,7 +133,7 @@ All response models come from the OpenAPI codegen pipeline — **one source of t
 ```python
 from forktex_cloud import (
     # Client
-    ForktexCloudClient, CloudAPIError,
+    Cloud, CloudAPIError,
     # Config
     CloudContext,
     # Manifest

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forktex-cloud"
-version = "0.2.4"
+version = "0.5.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"}

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/src/forktex_cloud/__init__.py

@@ -2,25 +2,32 @@
 
 Usage::
 
-    from forktex_cloud import ForktexCloudClient, CloudContext
+    from forktex_cloud import Cloud
+
+    with Cloud("https://cloud.forktex.com", account_key="ftx-...") as cloud:
+        projects = cloud.list_projects()
+        servers = cloud.list_servers()
+
+Or, when you already hold a ``CloudContext``::
+
+    from forktex_cloud import Cloud, 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()
+    with Cloud.from_context(ctx) as cloud:
+        ...
 """
 
-__version__ = "1.0.1"
+__version__ = "0.5.0"
 
 from forktex_cloud import paths
-from forktex_cloud.client.client import CloudAPIError, ForktexCloudClient
+from forktex_cloud.client.client import Cloud, CloudAPIError
 from forktex_cloud.client.generated import (
     SPEC_HASH,
     SPEC_VERSION,
     ApiKeyCreated,
     ApiKeyRead,
+    AuditEventRead,
     EnvironmentRead,
-    EventRead,
     HealthRead,
     JobResponse,
     MeResponse,
@@ -43,7 +50,7 @@ __all__ = [
     "SPEC_VERSION",
     "SPEC_HASH",
     # Client
-    "ForktexCloudClient",
+    "Cloud",
     "CloudAPIError",
     # Config
     "CloudContext",
@@ -53,8 +60,8 @@ __all__ = [
     # Models (from OpenAPI codegen — the single source of truth)
     "ApiKeyCreated",
     "ApiKeyRead",
+    "AuditEventRead",
     "EnvironmentRead",
-    "EventRead",
     "HealthRead",
     "JobResponse",
     "MeResponse",

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/src/forktex_cloud/bridge/local_compose.py

@@ -142,24 +142,23 @@ def local_compose_from_manifest(
 
         svc: dict[str, Any] = {"image": image}
 
-        if svc_type == "compute":
-            build_cfg = svc_def.get("build")
-            if build_cfg and isinstance(build_cfg, dict):
-                # Use explicit build config from manifest overlay
-                build_entry: dict[str, str] = {}
-                ctx = build_cfg.get("context", f"./{sid}")
-                # Rewrite relative context to be relative to .forktex/ dir
-                if ctx.startswith("./"):
-                    build_entry["context"] = f"../{ctx[2:]}"
-                else:
-                    build_entry["context"] = ctx
-                if build_cfg.get("dockerfile"):
-                    build_entry["dockerfile"] = build_cfg["dockerfile"]
-                svc["build"] = build_entry
-            else:
-                dockerfile = project_root / sid / "Dockerfile"
-                if dockerfile.is_file():
-                    svc["build"] = {"context": f"../{sid}"}
+        # Build context — explicit overlay first, else auto-detect a sibling
+        # Dockerfile for compute services. Persistence services only opt in
+        # when the manifest explicitly declares `build` (zot is the canonical
+        # case — persistence-typed but first-party).
+        build_cfg = svc_def.get("build")
+        if build_cfg and isinstance(build_cfg, dict):
+            build_entry: dict[str, str] = {}
+            ctx = build_cfg.get("context", f"./{sid}")
+            # Rewrite relative context to be relative to .forktex/ dir
+            build_entry["context"] = f"../{ctx.removeprefix('./')}" if ctx.startswith("./") else ctx
+            if build_cfg.get("dockerfile"):
+                build_entry["dockerfile"] = build_cfg["dockerfile"]
+            svc["build"] = build_entry
+        elif svc_type == "compute":
+            dockerfile = project_root / sid / "Dockerfile"
+            if dockerfile.is_file():
+                svc["build"] = {"context": f"../{sid}"}
 
         if sid in host_ports:
             host_port = host_ports[sid]
@@ -207,12 +206,17 @@ def local_compose_from_manifest(
                 else:
                     rewritten.append(v)
             svc["volumes"] = rewritten
-        elif svc_type == "persistence":
+        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.
             defaults = detect_persistence_defaults(image)
             if defaults and defaults.get("default_volume"):
-                vol_name = f"{sid}-data"
-                svc["volumes"] = [f"{vol_name}:{defaults['default_volume']}"]
-                named_volumes[vol_name] = None
+                target = defaults["default_volume"]
+                existing = svc.get("volumes", [])
+                if not any(isinstance(v, str) and v.endswith(f":{target}") for v in existing):
+                    existing.append(f"./data/{sid}:{target}")
+                    svc["volumes"] = existing
 
         cmd = svc_def.get("command")
         if cmd:

{forktex_cloud-0.2.4 → forktex_cloud-0.5.0}/src/forktex_cloud/client/__init__.py

@@ -6,7 +6,7 @@ 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 CloudAPIError, ForktexCloudClient
+from forktex_cloud.client.client import Cloud, CloudAPIError
 from forktex_cloud.client.generated import (
     ApiKeyCreated,
     ApiKeyRead,
@@ -14,13 +14,15 @@ from forktex_cloud.client.generated import (
     CapacityReport,
     CapacityServers,
     EnvironmentRead,
-    EventRead,
     HealthRead,
     JobResponse,
     MeResponse,
     OrgBrief,
     OrgRead,
     ProjectRead,
+    RegistryCredentialCreate,
+    RegistryCredentialRead,
+    RegistryVerifyResponse,
     ServerDnsRead,
     ServerRead,
     ServerServiceRead,
@@ -33,7 +35,7 @@ from forktex_cloud.client.generated import (
 )
 
 __all__ = [
-    "ForktexCloudClient",
+    "Cloud",
     "CloudAPIError",
     "ApiKeyCreated",
     "ApiKeyRead",
@@ -41,13 +43,15 @@ __all__ = [
     "CapacityReport",
     "CapacityServers",
     "EnvironmentRead",
-    "EventRead",
     "HealthRead",
     "JobResponse",
     "MeResponse",
     "OrgBrief",
     "OrgRead",
     "ProjectRead",
+    "RegistryCredentialCreate",
+    "RegistryCredentialRead",
+    "RegistryVerifyResponse",
     "ServerDnsRead",
     "ServerRead",
     "ServerServiceRead",