forktex-cloud 0.2.3__py3-none-any.whl

forktex_cloud/paths.py

@@ -0,0 +1,297 @@
+# 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/>.
+
+"""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",
+]

forktex_cloud/scaffold/__init__.py

@@ -0,0 +1,24 @@
+# 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/>.
+
+"""Project scaffolding templates."""

forktex_cloud/scaffold/templates.py

@@ -0,0 +1,143 @@
+# 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/>.
+
+"""forktex cloud init -- scaffold a new forktex.json manifest."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+TEMPLATES: dict[str, dict] = {
+    "ProjectDeployment": {
+        "cloud": {
+            "apiVersion": "forktex.cloud/v1beta2",
+            "kind": "ProjectDeployment",
+            "metadata": {
+                "name": "",
+                "environment": "production",
+            },
+            "deployment": {
+                "strategy": "blue-green",
+                "router": "haproxy",
+                "defaultComponent": "",
+                "retries": 45,
+                "drainDelaySeconds": 5,
+                "gracefulStopSeconds": 30,
+            },
+            "gateway": {
+                "domains": [],
+                "ssl": {
+                    "enabled": False,
+                    "provider": "letsencrypt",
+                    "email": "",
+                },
+            },
+            "services": [],
+            "observability": {
+                "enabled": True,
+                "logging": {"enabled": True},
+                "metrics": {"enabled": True},
+            },
+        },
+    },
+    "StaticSite": {
+        "cloud": {
+            "apiVersion": "forktex.cloud/v1beta2",
+            "kind": "StaticSite",
+            "metadata": {
+                "name": "",
+            },
+            "build": {
+                "command": "npm run build",
+                "outputDir": "dist",
+                "installCommand": "npm install",
+            },
+            "serve": {
+                "router": "nginx",
+                "spa": True,
+            },
+        },
+    },
+    "SingleContainer": {
+        "cloud": {
+            "apiVersion": "forktex.cloud/v1beta2",
+            "kind": "SingleContainer",
+            "metadata": {
+                "name": "",
+            },
+            "container": {
+                "image": "",
+                "port": 3000,
+                "healthPath": "/health",
+            },
+            "deployment": {
+                "strategy": "blue-green",
+                "router": "haproxy",
+            },
+        },
+    },
+    "NativeBuild": {
+        "cloud": {
+            "apiVersion": "forktex.cloud/v1beta2",
+            "kind": "NativeBuild",
+            "metadata": {
+                "name": "",
+            },
+            "build": {
+                "command": "",
+                "outputBinary": "",
+            },
+        },
+    },
+}
+
+
+def scaffold_manifest(
+    project_root: Path,
+    *,
+    kind: str = "ProjectDeployment",
+    name: str | None = None,
+    force: bool = False,
+) -> Path:
+    """Create forktex.json at the project root.
+
+    Returns the path to the created manifest.
+    """
+    target = project_root / "forktex.json"
+
+    if target.exists() and not force:
+        raise FileExistsError(f"forktex.json already exists: {target}. Use --force to overwrite.")
+
+    template = TEMPLATES.get(kind)
+    if template is None:
+        raise ValueError(f"Unknown kind: {kind}. Available: {', '.join(TEMPLATES.keys())}")
+
+    manifest = json.loads(json.dumps(template))  # deep copy
+    project_name = name or project_root.name
+    manifest["name"] = project_name
+    if "cloud" in manifest and "metadata" in manifest["cloud"]:
+        manifest["cloud"]["metadata"]["name"] = project_name
+
+    target.write_text(json.dumps(manifest, indent=2) + "\n")
+    return target

forktex_cloud/secrets/__init__.py

@@ -0,0 +1,24 @@
+# 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/>.
+
+"""Secrets management: Fernet vault, provider factory, and vault reference resolver."""

forktex_cloud/secrets/base.py

@@ -0,0 +1,52 @@
+# 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/>.
+
+"""Secrets provider abstract base class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class SecretsProvider(ABC):
+    """Abstract base for secrets providers."""
+
+    @abstractmethod
+    def get(self, key: str, env: str = "default") -> str:
+        """Retrieve a secret value by key."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: str, env: str = "default") -> None:
+        """Store a secret value."""
+        ...
+
+    @abstractmethod
+    def list_keys(self, env: str = "default") -> list[str]:
+        """List all secret keys for an environment."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str, env: str = "default") -> None:
+        """Delete a secret by key."""
+        ...

forktex_cloud/secrets/factory.py

@@ -0,0 +1,57 @@
+# 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/>.
+
+"""Secrets provider factory."""
+
+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,
+    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"``
+    """
+    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)
+
+    raise ValueError(f"Unknown secrets provider: {name}")

forktex_cloud/secrets/fernet.py

@@ -0,0 +1,96 @@
+# 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/>.
+
+"""Built-in Fernet-encrypted file vault for secrets."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from forktex_cloud.secrets.base import SecretsProvider
+
+
+class FernetVault(SecretsProvider):
+    """File-backed secrets vault using Fernet symmetric encryption.
+
+    Storage layout: ``.forktex/vault/{env}/secrets.enc``
+    """
+
+    def __init__(self, vault_root: Path, master_key: str | None = None) -> None:
+        self._root = vault_root
+        self._key = master_key or os.environ.get("FORKTEX_MASTER_KEY", "")
+        if not self._key:
+            raise ValueError(
+                "Master key required for vault operations. "
+                "Set FORKTEX_MASTER_KEY or pass master_key."
+            )
+
+    def _fernet(self):
+        from cryptography.fernet import Fernet
+
+        return Fernet(self._key.encode() if isinstance(self._key, str) else self._key)
+
+    def _vault_path(self, env: str) -> Path:
+        return self._root / env / "secrets.enc"
+
+    def _load(self, env: str) -> dict[str, str]:
+        path = self._vault_path(env)
+        if not path.exists():
+            return {}
+        encrypted = path.read_bytes()
+        try:
+            decrypted = self._fernet().decrypt(encrypted)
+        except Exception:
+            raise ValueError(
+                f"Failed to decrypt vault ({path}). "
+                "Check that FORKTEX_MASTER_KEY matches the key used to encrypt."
+            )
+        return json.loads(decrypted)
+
+    def _save(self, env: str, data: dict[str, str]) -> None:
+        path = self._vault_path(env)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        raw = json.dumps(data, indent=2).encode()
+        encrypted = self._fernet().encrypt(raw)
+        path.write_bytes(encrypted)
+
+    def get(self, key: str, env: str = "default") -> str:
+        data = self._load(env)
+        if key not in data:
+            raise KeyError(f"Secret not found: {key} (env={env})")
+        return data[key]
+
+    def set(self, key: str, value: str, env: str = "default") -> None:
+        data = self._load(env)
+        data[key] = value
+        self._save(env, data)
+
+    def list_keys(self, env: str = "default") -> list[str]:
+        return sorted(self._load(env).keys())
+
+    def delete(self, key: str, env: str = "default") -> None:
+        data = self._load(env)
+        data.pop(key, None)
+        self._save(env, data)