forktex-cloud 1.0.0__tar.gz → 2.0.0__tar.gz

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forktex-cloud
-Version: 1.0.0
+Version: 2.0.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

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forktex-cloud"
-version = "1.0.0"
+version = "2.0.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-2.0.0/src/forktex_cloud/__init__.py

@@ -0,0 +1,148 @@
+"""forktex_cloud — Standalone Python SDK for the ForkTex Cloud platform.
+
+Usage::
+
+    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 Cloud.from_context(ctx) as cloud:
+        ...
+
+Loading model — lazy
+--------------------
+
+The SDK is **filesystem-independent**: it deals in data (manifests, compose
+dicts, cipher bytes), never in ``.forktex/`` paths — forktex-py owns the
+on-disk layout. The HTTP client (``Cloud``), the auth/config types
+(``CloudContext``), the manifest loader, and the 17 OpenAPI-codegen models are
+loaded **lazily** via PEP 562 ``__getattr__`` on first access, keeping
+``import forktex_cloud`` cheap. The public surface is unchanged:
+``from forktex_cloud import Cloud`` still works.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+__version__ = "2.0.0"
+
+# ── Lazy attribute map ──────────────────────────────────────────────────────
+#
+# Name → (submodule, attribute). Anything not listed raises AttributeError.
+# Codegen models share one submodule, so first access pays once — subsequent
+# 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"),
+    "CloudAPIError": ("forktex_cloud.client.client", "CloudAPIError"),
+    # Config
+    "CloudContext": ("forktex_cloud.config", "CloudContext"),
+    # Manifest
+    "Manifest": ("forktex_cloud.manifest.loader", "Manifest"),
+    "ManifestError": ("forktex_cloud.manifest.loader", "ManifestError"),
+    # Codegen contract + OpenAPI models (all from forktex_cloud.client.generated)
+    "SPEC_HASH": ("forktex_cloud.client.generated", "SPEC_HASH"),
+    "SPEC_VERSION": ("forktex_cloud.client.generated", "SPEC_VERSION"),
+    "ApiKeyCreated": ("forktex_cloud.client.generated", "ApiKeyCreated"),
+    "ApiKeyRead": ("forktex_cloud.client.generated", "ApiKeyRead"),
+    "AuditEventRead": ("forktex_cloud.client.generated", "AuditEventRead"),
+    "EnvironmentRead": ("forktex_cloud.client.generated", "EnvironmentRead"),
+    "HealthRead": ("forktex_cloud.client.generated", "HealthRead"),
+    "JobResponse": ("forktex_cloud.client.generated", "JobResponse"),
+    "MeResponse": ("forktex_cloud.client.generated", "MeResponse"),
+    "OrgRead": ("forktex_cloud.client.generated", "OrgRead"),
+    "ProjectRead": ("forktex_cloud.client.generated", "ProjectRead"),
+    "ServerRead": ("forktex_cloud.client.generated", "ServerRead"),
+    "StatusResponse": ("forktex_cloud.client.generated", "StatusResponse"),
+    "TokenResponse": ("forktex_cloud.client.generated", "TokenResponse"),
+    "UserRead": ("forktex_cloud.client.generated", "UserRead"),
+    "VaultGetResponse": ("forktex_cloud.client.generated", "VaultGetResponse"),
+    "WorkspaceRead": ("forktex_cloud.client.generated", "WorkspaceRead"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy attribute resolver — imports a submodule on first access.
+
+    Once resolved, the attribute is bound on the module so subsequent accesses
+    skip this function entirely (Python looks it up in ``globals()`` first).
+    """
+    if name in _LAZY_ATTRS:
+        import importlib
+
+        module_path, attr_name = _LAZY_ATTRS[name]
+        value = getattr(importlib.import_module(module_path), attr_name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'forktex_cloud' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Include lazy attributes in ``dir()`` so REPL completion still works."""
+    return sorted(set(__all__) | set(globals()))
+
+
+# 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.generated import (
+        SPEC_HASH,
+        SPEC_VERSION,
+        ApiKeyCreated,
+        ApiKeyRead,
+        AuditEventRead,
+        EnvironmentRead,
+        HealthRead,
+        JobResponse,
+        MeResponse,
+        OrgRead,
+        ProjectRead,
+        ServerRead,
+        StatusResponse,
+        TokenResponse,
+        UserRead,
+        VaultGetResponse,
+        WorkspaceRead,
+    )
+    from forktex_cloud.config import CloudContext
+    from forktex_cloud.manifest.loader import Manifest, ManifestError
+
+
+__all__ = [
+    # Codegen contract (wire-compatibility markers) — lazy
+    "SPEC_VERSION",
+    "SPEC_HASH",
+    # Client — lazy
+    "Cloud",
+    "CloudAPIError",
+    # Config — lazy
+    "CloudContext",
+    # Manifest — lazy
+    "Manifest",
+    "ManifestError",
+    # Models (from OpenAPI codegen — the single source of truth) — lazy
+    "ApiKeyCreated",
+    "ApiKeyRead",
+    "AuditEventRead",
+    "EnvironmentRead",
+    "HealthRead",
+    "JobResponse",
+    "MeResponse",
+    "OrgRead",
+    "ProjectRead",
+    "ServerRead",
+    "StatusResponse",
+    "TokenResponse",
+    "UserRead",
+    "VaultGetResponse",
+    "WorkspaceRead",
+]

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/src/forktex_cloud/bridge/local_compose.py

@@ -6,11 +6,9 @@ No proxy, no blue-green, no SSL -- just plain containers with direct port mappin
 
 from __future__ import annotations
 
-import shutil
 from pathlib import Path
 from typing import Any
 
-from forktex_cloud import paths
 from forktex_cloud.bridge.persistence_defaults import detect_persistence_defaults
 from forktex_cloud.manifest.loader import Manifest
 from forktex_cloud.secrets.base import SecretsProvider
@@ -58,31 +56,37 @@ def _templates_dir() -> Path:
     return Path(__file__).resolve().parent.parent / "templates"
 
 
-def _write_observability_configs(project_root: Path) -> Path:
-    """Copy observability config files to the canonical observability dir."""
-    out_dir = paths.observability_dir(project_root)
-    out_dir.mkdir(parents=True, exist_ok=True)
+def render_observability_configs() -> dict[str, str]:
+    """Return the observability config files as ``{filename: content}``.
+
+    Pure: reads the bundled SDK templates and returns their text. The caller
+    (forktex-py) writes them next to the generated compose file. No ``.forktex/``
+    knowledge here — the SDK only produces data.
+    """
+    out: dict[str, str] = {}
     src_dir = _templates_dir() / "observability"
     if src_dir.is_dir():
-        for src_file in src_dir.iterdir():
+        for src_file in sorted(src_dir.iterdir()):
             if src_file.is_file():
-                shutil.copy2(src_file, out_dir / src_file.name)
-    return out_dir
+                out[src_file.name] = src_file.read_text(encoding="utf-8")
+    return out
 
 
 def _add_observability_services(
     services: dict[str, Any],
     named_volumes: dict[str, Any],
-    project_root: Path,
 ) -> None:
-    """Add Loki + Promtail services."""
-    obs_dir = _write_observability_configs(project_root)
+    """Add Loki + Promtail services.
 
+    The compose file and the ``observability/`` configs are written into the
+    same directory by the caller, so the bind mounts are siblings
+    (``./observability/...``).
+    """
     services["loki"] = {
         "image": "grafana/loki:2.9.0",
         "ports": ["3100:3100"],
         "volumes": [
-            f"../{obs_dir.relative_to(project_root)}/loki.yml:/etc/loki/local-config.yaml:ro",
+            "./observability/loki.yml:/etc/loki/local-config.yaml:ro",
             "loki-data:/loki",
         ],
         "healthcheck": {
@@ -101,7 +105,7 @@ def _add_observability_services(
     services["promtail"] = {
         "image": "grafana/promtail:2.9.0",
         "volumes": [
-            f"../{obs_dir.relative_to(project_root)}/promtail.yml:/etc/promtail/config.yml:ro",
+            "./observability/promtail.yml:/etc/promtail/config.yml:ro",
             "/var/run/docker.sock:/var/run/docker.sock:ro",
             "/var/lib/docker/containers:/var/lib/docker/containers:ro",
         ],
@@ -118,8 +122,16 @@ def local_compose_from_manifest(
     *,
     secrets_provider: SecretsProvider | None = None,
     observability: bool = True,
+    root_prefix: str = "../..",
 ) -> dict[str, Any]:
-    """Build a docker-compose dict suitable for local development."""
+    """Build a docker-compose dict suitable for local development.
+
+    ``root_prefix`` is the relative path from the compose file's directory up to
+    the project root. forktex-py writes the compose into ``.forktex/cache/``
+    (two levels under the root), so the default is ``../..``; build contexts and
+    source bind-mounts are emitted relative to it. (cache-sibling artefacts —
+    ``./observability``, ``./data`` — are unaffected.)
+    """
     services: dict[str, Any] = {}
     named_volumes: dict[str, Any] = {}
     env_name = getattr(manifest, "env_name", None) or "default"
@@ -134,6 +146,35 @@ def local_compose_from_manifest(
         if svc_def.get("type") == "persistence":
             persistence_ids.append(svc_def["id"])
 
+    # Precompute which persistence services WILL get a healthcheck (declared or
+    # from image defaults), independent of generation order. The depends_on
+    # condition derivation below used to read the not-yet-generated persistence
+    # service dict, so services appearing before their DB in the manifest (api,
+    # client, ...) wrongly got ``service_started`` and raced the DB on startup.
+    persistence_has_healthcheck: dict[str, bool] = {}
+    for svc_def in local_services:
+        if svc_def.get("type") != "persistence":
+            continue
+        pid = svc_def["id"]
+        if svc_def.get("healthcheck"):
+            persistence_has_healthcheck[pid] = True
+        else:
+            defaults = detect_persistence_defaults(svc_def.get("image", ""))
+            persistence_has_healthcheck[pid] = bool(defaults and "healthcheck" in defaults)
+
+    # One-shot init services (`labels.forktex.oneshot=true`) — compute
+    # services get an auto-depends_on on each so they're at least ordered
+    # 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.
+    oneshot_ids: list[str] = [
+        svc_def["id"]
+        for svc_def in local_services
+        if (svc_def.get("labels") or {}).get("forktex.oneshot") == "true"
+    ]
+
     for svc_def in local_services:
         sid = svc_def["id"]
         image = svc_def.get("image", "")
@@ -150,22 +191,37 @@ def local_compose_from_manifest(
         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
+            # Rewrite a project-relative context to be relative to the compose
+            # file's directory (.forktex/cache/) via root_prefix.
+            build_entry["context"] = (
+                f"{root_prefix}/{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}"}
+                svc["build"] = {"context": f"{root_prefix}/{sid}"}
 
         if sid in host_ports:
             host_port = host_ports[sid]
             svc["ports"] = [f"{host_port}:{port}"]
 
-        if svc_type in ("persistence", "observability"):
+        # One-shot init services (e.g. `gitea-init`) 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:
             svc["restart"] = "always"
+        if svc_def.get("labels"):
+            svc["labels"] = dict(svc_def["labels"])
+        # docker-compose `pid:` passthrough — `service:<id>` shares another
+        # service's PID namespace so e.g. a sidecar can signal its primary.
+        if svc_def.get("pid"):
+            svc["pid"] = svc_def["pid"]
 
         if svc_type == "persistence":
             defaults = detect_persistence_defaults(image)
@@ -196,7 +252,7 @@ def local_compose_from_manifest(
                     src = v.split(":")[0]
                     rest = v[len(src) :]
                     if src.startswith("./"):
-                        rewritten.append(f"../{src[2:]}{rest}")
+                        rewritten.append(f"{root_prefix}/{src[2:]}{rest}")
                     elif src.startswith("/") or not src.startswith("."):
                         rewritten.append(v)
                         if not src.startswith("/"):
@@ -222,16 +278,19 @@ def local_compose_from_manifest(
         if cmd:
             svc["command"] = cmd
 
-        if svc_type == "compute" and persistence_ids:
+        if svc_type == "compute":
             depends: dict[str, Any] = {}
             for pid in persistence_ids:
-                # Use service_healthy only if the persistence service has a healthcheck
-                psvc = services.get(pid, {})
-                if "healthcheck" in psvc:
-                    depends[pid] = {"condition": "service_healthy"}
-                else:
-                    depends[pid] = {"condition": "service_started"}
-            svc["depends_on"] = depends
+                healthy = persistence_has_healthcheck.get(pid)
+                cond = "service_healthy" if healthy else "service_started"
+                depends[pid] = {"condition": cond}
+            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."
+                depends[iid] = {"condition": "service_started"}
+            if depends:
+                svc["depends_on"] = depends
 
         explicit_deps = svc_def.get("depends_on")
         if explicit_deps:
@@ -241,7 +300,7 @@ def local_compose_from_manifest(
         services[sid] = svc
 
     if observability:
-        _add_observability_services(services, named_volumes, project_root)
+        _add_observability_services(services, named_volumes)
 
     compose: dict[str, Any] = {"services": services}
 
@@ -251,26 +310,3 @@ def local_compose_from_manifest(
     compose["networks"] = {"forktex": {}}
 
     return compose
-
-
-def write_local_compose(
-    manifest: Manifest,
-    project_root: Path,
-    *,
-    secrets_provider: SecretsProvider | None = None,
-    observability: bool = True,
-) -> Path:
-    """Generate the local docker-compose file for the project and return its path."""
-    import yaml
-
-    compose = local_compose_from_manifest(
-        manifest,
-        project_root,
-        secrets_provider=secrets_provider,
-        observability=observability,
-    )
-    paths.ensure_project_dirs(project_root)
-    out_path = paths.compose_path(project_root, "local")
-    with open(out_path, "w") as f:
-        yaml.dump(compose, f, default_flow_style=False, sort_keys=False)
-    return out_path

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/src/forktex_cloud/client/client.py

@@ -895,12 +895,23 @@ class Cloud:
             svc_type = svc.get("type", "compute")
             service_prefix = f"services/{svc_id}"
 
-            # Volume-mounted local files and directories
+            # Volume-mounted local files and directories.
+            #
+            # Only RELATIVE local paths (./foo, ../bar) are treated as
+            # tarball-worthy assets — they're project-local source dirs the
+            # deploy needs to ship.
+            #
+            # Absolute paths in `volumes:` (e.g. /media/megatyres/db) are
+            # by convention **server-side host paths** on the deployment
+            # target, NOT local asset directories. Tarballing them is
+            # always wrong (they may not exist locally; if they do, the
+            # permissions are whatever the local OS happens to assign,
+            # which has nothing to do with the deploy). Skip them.
             for vol in svc.get("volumes", []):
                 if isinstance(vol, str) and ":" in vol:
                     parts = vol.split(":")
                     local_part = parts[0]
-                    if local_part.startswith("./") or local_part.startswith("/"):
+                    if local_part.startswith("./") or local_part.startswith("../"):
                         local_path = (project_dir / local_part).resolve()
                         if local_path.is_dir() or local_path.is_file():
                             source_basename = Path(local_part).name

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/src/forktex_cloud/client/generated/__init__.py

@@ -4,13 +4,13 @@ DO NOT EDIT — regenerate with: make codegen
 
 Source: GET /api/openapi.json
 API version: 0.6.0
-Spec hash: 0739bc915ed92cad
+Spec hash: 8d93387d1a2e1ae4
 """
 from __future__ import annotations
 
 
 SPEC_VERSION = "0.6.0"
-SPEC_HASH = "0739bc915ed92cad"
+SPEC_HASH = "8d93387d1a2e1ae4"
 
 
 from enum import StrEnum
@@ -656,6 +656,14 @@ class ManifestVersionRead(BaseModel):
     version: Annotated[int, Field(title="Version")]
 
 
+class MemberRead(BaseModel):
+    createdAt: Annotated[AwareDatetime, Field(title="Createdat")]
+    id: Annotated[UUID, Field(title="Id")]
+    orgId: Annotated[UUID, Field(title="Orgid")]
+    role: Annotated[str, Field(title="Role")]
+    userId: Annotated[UUID, Field(title="Userid")]
+
+
 class MetadataDef(BaseModel):
     model_config = ConfigDict(
         extra="forbid",
@@ -741,6 +749,7 @@ class OpsResponse(BaseModel):
 class OrgBrief(BaseModel):
     id: Annotated[UUID, Field(title="Id")]
     name: Annotated[str, Field(title="Name")]
+    role: Annotated[str | None, Field(title="Role")] = None
     slug: Annotated[str, Field(title="Slug")]
 
 
@@ -1190,6 +1199,10 @@ class ServiceDef(BaseModel):
     """
     Log format this service writes to stdout. 'json' enables structured field extraction in Loki (level, request_id). 'auto' (default when omitted) infers from the image name.
     """
+    pid: Annotated[str | None, Field(title="Pid")] = None
+    """
+    Docker-compose ``pid:`` passthrough. Common values: ``service:<other-service-id>`` to share another service's PID namespace (useful for sidecars that need to signal their primary, e.g. ``kill -HUP``), or ``host`` for full host PID namespace. When omitted, the container runs in its own PID namespace (compose default).
+    """
     port: Annotated[int | None, Field(title="Port")] = None
     resources: Annotated[dict[str, Any] | None, Field(title="Resources")] = None
     routePrefix: Annotated[str | None, Field(title="Routeprefix")] = None

{forktex_cloud-1.0.0 → forktex_cloud-2.0.0}/src/forktex_cloud/secrets/factory.py

@@ -5,30 +5,27 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
-from forktex_cloud import paths
 from forktex_cloud.secrets.base import SecretsProvider
 
 
 def get_secrets_provider(
     *,
-    project_root: Path | None = None,
+    vault_root: Path,
     provider_name: str | None = None,
     master_key: str | None = None,
 ) -> SecretsProvider:
     """Create and return the configured SecretsProvider.
 
-    Resolution order for provider name:
-    1. Explicit ``provider_name`` argument
-    2. ``FORKTEX_SECRETS_PROVIDER`` environment variable
-    3. Defaults to ``"fernet"``
+    ``vault_root`` is supplied by the caller — forktex-py owns the ``.forktex/``
+    layout; the SDK never computes filesystem paths. Resolution order for the
+    provider name: explicit ``provider_name`` → ``FORKTEX_SECRETS_PROVIDER`` →
+    ``"fernet"``.
     """
     name = provider_name or os.environ.get("FORKTEX_SECRETS_PROVIDER", "fernet")
 
     if name == "fernet":
         from forktex_cloud.secrets.fernet import FernetVault
 
-        root = project_root or Path.cwd()
-        vault_root = paths.project_dir(root) / "vault"
-        return FernetVault(vault_root, master_key=master_key)
+        return FernetVault(Path(vault_root), master_key=master_key)
 
     raise ValueError(f"Unknown secrets provider: {name}")

forktex_cloud-1.0.0/src/forktex_cloud/__init__.py

@@ -1,76 +0,0 @@
-"""forktex_cloud — Standalone Python SDK for the ForkTex Cloud platform.
-
-Usage::
-
-    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 Cloud.from_context(ctx) as cloud:
-        ...
-"""
-
-__version__ = "1.0.0"
-
-from forktex_cloud import paths
-from forktex_cloud.client.client import Cloud, CloudAPIError
-from forktex_cloud.client.generated import (
-    SPEC_HASH,
-    SPEC_VERSION,
-    ApiKeyCreated,
-    ApiKeyRead,
-    AuditEventRead,
-    EnvironmentRead,
-    HealthRead,
-    JobResponse,
-    MeResponse,
-    OrgRead,
-    ProjectRead,
-    ServerRead,
-    StatusResponse,
-    TokenResponse,
-    UserRead,
-    VaultGetResponse,
-    WorkspaceRead,
-)
-from forktex_cloud.config import CloudContext
-from forktex_cloud.manifest.loader import Manifest, ManifestError
-
-__all__ = [
-    # Filesystem layout spec (V1)
-    "paths",
-    # Codegen contract (wire-compatibility markers)
-    "SPEC_VERSION",
-    "SPEC_HASH",
-    # Client
-    "Cloud",
-    "CloudAPIError",
-    # Config
-    "CloudContext",
-    # Manifest
-    "Manifest",
-    "ManifestError",
-    # Models (from OpenAPI codegen — the single source of truth)
-    "ApiKeyCreated",
-    "ApiKeyRead",
-    "AuditEventRead",
-    "EnvironmentRead",
-    "HealthRead",
-    "JobResponse",
-    "MeResponse",
-    "OrgRead",
-    "ProjectRead",
-    "ServerRead",
-    "StatusResponse",
-    "TokenResponse",
-    "UserRead",
-    "VaultGetResponse",
-    "WorkspaceRead",
-]

forktex_cloud-1.0.0/src/forktex_cloud/paths.py

@@ -1,274 +0,0 @@
-"""Canonical filesystem layout for the forktex ecosystem (V1).
-
-Every subsystem that reads or writes under ``.forktex/`` (project scope) or
-``~/.forktex/`` (user/OS scope) MUST go through this module. Hardcoding path
-literals elsewhere is enforced against by ``tests/test_paths_contract.py``.
-
-Cross-platform rules:
-- All returned values are ``pathlib.Path`` (never ``str``).
-- Project scope directory is always lowercase ``.forktex``.
-- User scope directory is ``~/.forktex`` on POSIX and ``%APPDATA%/forktex`` on Windows.
-- Secrets-bearing directories are created with mode ``0o700`` on POSIX; Windows
-  relies on per-user ACLs on ``%APPDATA%``.
-
-See ``cloud/docs/forktex-directory-spec.md`` for the full V1 spec.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from pathlib import Path
-
-#: Bump when the on-disk layout changes incompatibly. Written to
-#: ``.forktex/.version`` by :func:`ensure_project_dirs` on init.
-SCHEMA_VERSION = 1
-
-#: Directory name at project scope.
-PROJECT_DIRNAME = ".forktex"
-
-#: Directory name at user/OS scope (stripped of leading dot on Windows).
-_USER_DIRNAME_POSIX = ".forktex"
-_USER_DIRNAME_WINDOWS = "forktex"
-
-#: Marker comment used to idempotently detect the canonical ``.gitignore`` block.
-_GITIGNORE_MARKER = "# forktex — generated + secrets (keep .forktex/.version committed)"
-_GITIGNORE_BLOCK = f"""
-{_GITIGNORE_MARKER}
-.forktex/**
-!.forktex/.version
-"""
-
-
-# ── Project-scope paths ──────────────────────────────────────────────────────
-
-
-def project_dir(root: Path) -> Path:
-    return root / PROJECT_DIRNAME
-
-
-def version_file(root: Path) -> Path:
-    return project_dir(root) / ".version"
-
-
-def compose_path(root: Path, env: str) -> Path:
-    return project_dir(root) / f"docker-compose.{env}.yml"
-
-
-def observability_dir(root: Path) -> Path:
-    return project_dir(root) / "observability"
-
-
-def vault_dir(root: Path, env: str) -> Path:
-    return project_dir(root) / "vault" / env
-
-
-def vault_secrets_file(root: Path, env: str) -> Path:
-    return vault_dir(root, env) / "secrets.enc"
-
-
-def state_dir(root: Path) -> Path:
-    return project_dir(root) / "state"
-
-
-def servers_json(root: Path) -> Path:
-    return state_dir(root) / "servers.json"
-
-
-def server_keys_dir(root: Path) -> Path:
-    return state_dir(root) / "keys"
-
-
-def generated_dir(root: Path) -> Path:
-    return project_dir(root) / "generated"
-
-
-def data_dir(root: Path, service_id: str) -> Path:
-    return project_dir(root) / "data" / service_id
-
-
-def custom_ssl_dir(root: Path) -> Path:
-    return project_dir(root) / "ssl" / "custom"
-
-
-def fsd_evidence_dir(root: Path) -> Path:
-    return project_dir(root) / "fsd" / "evidence"
-
-
-def architecture_dir(root: Path) -> Path:
-    return project_dir(root) / "architecture"
-
-
-def agents_history_dir(root: Path) -> Path:
-    return project_dir(root) / "agents" / "history"
-
-
-def agents_history_file(root: Path, agent_id: str) -> Path:
-    return agents_history_dir(root) / f"{agent_id}.jsonl"
-
-
-def agents_types_file(root: Path) -> Path:
-    return project_dir(root) / "agents" / "types.json"
-
-
-def scraper_truths_dir(root: Path) -> Path:
-    return project_dir(root) / "scraper" / "truths"
-
-
-def scraper_truths_file(root: Path, domain: str) -> Path:
-    return scraper_truths_dir(root) / f"{domain}.json"
-
-
-def scraper_output_dir(root: Path) -> Path:
-    return project_dir(root) / "scraper" / "output"
-
-
-def project_config_file(root: Path) -> Path:
-    return project_dir(root) / "config.json"
-
-
-def project_cloud_file(root: Path) -> Path:
-    return project_dir(root) / "cloud" / "config.json"
-
-
-def project_intelligence_file(root: Path) -> Path:
-    return project_dir(root) / "intelligence.json"
-
-
-def project_network_file(root: Path) -> Path:
-    return project_dir(root) / "network.json"
-
-
-# ── User/OS-scope paths ──────────────────────────────────────────────────────
-
-
-def global_dir() -> Path:
-    """Return the global forktex directory, cross-platform.
-
-    POSIX: ``~/.forktex/``. Windows: ``%APPDATA%/forktex/`` (roaming user profile).
-    """
-    if sys.platform == "win32":
-        appdata = os.environ.get("APPDATA")
-        base = Path(appdata) if appdata else Path.home()
-        return base / _USER_DIRNAME_WINDOWS
-    return Path.home() / _USER_DIRNAME_POSIX
-
-
-def global_cloud_file() -> Path:
-    return global_dir() / "cloud.json"
-
-
-def global_intelligence_file() -> Path:
-    return global_dir() / "intelligence.json"
-
-
-def global_network_file() -> Path:
-    return global_dir() / "network.json"
-
-
-def global_config_file() -> Path:
-    return global_dir() / "config.toml"
-
-
-# ── Lifecycle helpers ────────────────────────────────────────────────────────
-
-
-def ensure_project_dirs(root: Path) -> None:
-    """Create ``.forktex/`` under *root*, write the schema version marker, and
-    ensure the project ``.gitignore`` has the canonical forktex block.
-
-    Safe to call repeatedly. Does not touch existing files.
-    """
-    pdir = project_dir(root)
-    pdir.mkdir(parents=True, exist_ok=True)
-    write_schema_version(root)
-    _ensure_gitignore_block(root)
-
-
-def ensure_global_dir() -> None:
-    """Create the user/OS-scope forktex dir with secure permissions on POSIX."""
-    gdir = global_dir()
-    gdir.mkdir(parents=True, exist_ok=True)
-    if sys.platform != "win32":
-        try:
-            gdir.chmod(0o700)
-        except OSError:
-            # Non-fatal: existing dir with stricter perms is fine.
-            pass
-
-
-def read_schema_version(root: Path) -> int | None:
-    """Return the on-disk ``.forktex/.version`` as int, or ``None`` if missing."""
-    vf = version_file(root)
-    if not vf.is_file():
-        return None
-    try:
-        return int(vf.read_text().strip())
-    except (ValueError, OSError):
-        return None
-
-
-def write_schema_version(root: Path) -> None:
-    """Write ``SCHEMA_VERSION`` to ``.forktex/.version`` if not already correct."""
-    vf = version_file(root)
-    if read_schema_version(root) == SCHEMA_VERSION:
-        return
-    vf.parent.mkdir(parents=True, exist_ok=True)
-    vf.write_text(f"{SCHEMA_VERSION}\n")
-
-
-def _ensure_gitignore_block(root: Path) -> None:
-    gi = root / ".gitignore"
-    if gi.is_file():
-        existing = gi.read_text()
-        if _GITIGNORE_MARKER in existing:
-            return
-        # Append, ensuring a trailing newline separator.
-        if not existing.endswith("\n"):
-            existing += "\n"
-        gi.write_text(existing + _GITIGNORE_BLOCK)
-    else:
-        gi.write_text(_GITIGNORE_BLOCK.lstrip("\n"))
-
-
-__all__ = [
-    # Constants
-    "SCHEMA_VERSION",
-    "PROJECT_DIRNAME",
-    # Project-scope
-    "project_dir",
-    "version_file",
-    "compose_path",
-    "observability_dir",
-    "vault_dir",
-    "vault_secrets_file",
-    "state_dir",
-    "servers_json",
-    "server_keys_dir",
-    "generated_dir",
-    "data_dir",
-    "custom_ssl_dir",
-    "fsd_evidence_dir",
-    "architecture_dir",
-    "agents_history_dir",
-    "agents_history_file",
-    "agents_types_file",
-    "scraper_truths_dir",
-    "scraper_truths_file",
-    "scraper_output_dir",
-    "project_config_file",
-    "project_cloud_file",
-    "project_intelligence_file",
-    "project_network_file",
-    # User/OS-scope
-    "global_dir",
-    "global_cloud_file",
-    "global_intelligence_file",
-    "global_network_file",
-    "global_config_file",
-    # Lifecycle
-    "ensure_project_dirs",
-    "ensure_global_dir",
-    "read_schema_version",
-    "write_schema_version",
-]