comfygit-core 0.7.0__tar.gz → 0.7.1__tar.gz

comfygit_core-0.7.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: comfygit-core
+Version: 0.7.1
+Summary: ComfyGit Core - Git-based ComfyUI environment manager
+Project-URL: Documentation, https://docs.comfygit.org/
+Project-URL: Repository, https://github.com/comfygit-ai/comfygit
+Project-URL: Issues, https://github.com/comfygit-ai/comfygit/issues
+License-File: LICENSE.txt
+Requires-Python: >=3.10
+Requires-Dist: blake3>=0.3.3
+Requires-Dist: huggingface-hub>=0.15.1
+Requires-Dist: packaging>=16.2
+Requires-Dist: requests>=2.32.4
+Requires-Dist: requirements-parser>=0.11.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: tomlkit>=0.11.0
+Requires-Dist: uv>=0.11.15
+Requires-Dist: xxhash>=2.0.0
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.7.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# ComfyGit Core
+
+`comfygit-core` is the UI-independent library behind ComfyGit's CLI and runtime
+adapters. It owns workspace discovery, environment manifests, custom nodes,
+model metadata, dependency resolution, sync, import/export and materialization.
+APIs are still evolving; integrations should pin a tested release.
+
+## Installation
+
+```bash
+uv add 'comfygit-core==0.7.0'
+```
+
+Core does not require desktop keyring. For OS-backed credential persistence,
+install the optional `comfygit-core[keyring]==0.7.0` extra. The CLI includes that
+extra; headless library users can use environment credentials or inject their
+own store instead.
+
+## Open a workspace
+
+```python
+from pathlib import Path
+from comfygit_core import Workspace
+
+workspace = Workspace.open(Path.home() / "comfygit")
+env = workspace.get_environment("my-project", auto_sync=False)
+status = env.status()
+```
+
+`Workspace.create(path)` creates a workspace; `Workspace.open_or_create(path)`
+handles either case. Opening with `auto_sync=False` above avoids reconciling the
+environment just to inspect it.
+
+## Create and reconcile an environment
+
+```python
+env = workspace.create_environment(
+    name="experiment",
+    python_version="3.12",
+    torch_backend="auto",
+    no_manager=True,
+)
+env.add_node("rgthree-comfy")
+result = env.sync(model_strategy="required")
+```
+
+Creation and sync can download code and packages. Resolve an existing saved
+workflow by its name, not an arbitrary JSON path:
+
+```python
+result = env.resolve_workflow("my-workflow")
+```
+
+For ambiguous resolution, supply implementations of the protocols in
+[`models/protocols.py`](src/comfygit_core/models/protocols.py). Do not put prompts,
+printing or CLI policy into Core. A successful dependency resolution is not proof
+that a ComfyUI inference job succeeds.
+
+## Credentials
+
+Workspace entry points accept process-local `credential_overrides`, keyed by
+`CredentialProvider`. A token overrides all discovery for that provider; `None`
+explicitly selects anonymous access. Omitted providers use normal discovery.
+
+```python
+from comfygit_core.models.credentials import CredentialProvider
+
+workspace = Workspace.open(
+    Path.home() / "comfygit",
+    credential_overrides={CredentialProvider.HUGGINGFACE: None},
+)
+```
+
+Normal resolution uses provider environment variables, workspace secure storage,
+provider-native credentials when available, then legacy workspace values during
+migration. An unavailable keyring backend does not prevent environment/native
+credentials from working. Saving a new credential requires a working secure store;
+there is no new plaintext fallback. Callers may inject a `CredentialStore` through
+the `credential_store` parameter.
+
+## Portable and local state
+
+The tracked `pyproject.toml`, `workflows/`, `workflow_api/`, shared overlays and
+source metadata form the portable environment. Model bytes stay in the shared
+model directory. ComfyUI/node checkouts, virtualenvs, `.cec/`, local overlays,
+credentials and backend choices are derived or machine-local state.
+
+Use ComfyGit operations to change the recipe; manual runtime edits may be
+replaced on sync. For a headless recreation, use the materialization API or
+[`cg materialize`](https://docs.comfygit.org/user-guide/collaboration/materialize/).
+
+## API and development references
+
+- [Workspace entry points](src/comfygit_core/core/workspace.py)
+- [Environment operations](src/comfygit_core/core/environment.py)
+- [Architecture](docs/architecture.md)
+- [Normative contracts](../../docs/contracts/) and [specifications](../../docs/specs/)
+- [Contributing](../../CONTRIBUTING.md)
+
+From the monorepo root:
+
+```bash
+uv sync --frozen --all-packages
+uv run pytest packages/core/tests -q
+make lint
+```
+
+Core, Studio runtime and CLI releases use matched versions. See the root
+[agent guide](../../AGENTS.md) for release ordering and package boundaries.

comfygit_core-0.7.1/README.md

@@ -0,0 +1,109 @@
+# ComfyGit Core
+
+`comfygit-core` is the UI-independent library behind ComfyGit's CLI and runtime
+adapters. It owns workspace discovery, environment manifests, custom nodes,
+model metadata, dependency resolution, sync, import/export and materialization.
+APIs are still evolving; integrations should pin a tested release.
+
+## Installation
+
+```bash
+uv add 'comfygit-core==0.7.0'
+```
+
+Core does not require desktop keyring. For OS-backed credential persistence,
+install the optional `comfygit-core[keyring]==0.7.0` extra. The CLI includes that
+extra; headless library users can use environment credentials or inject their
+own store instead.
+
+## Open a workspace
+
+```python
+from pathlib import Path
+from comfygit_core import Workspace
+
+workspace = Workspace.open(Path.home() / "comfygit")
+env = workspace.get_environment("my-project", auto_sync=False)
+status = env.status()
+```
+
+`Workspace.create(path)` creates a workspace; `Workspace.open_or_create(path)`
+handles either case. Opening with `auto_sync=False` above avoids reconciling the
+environment just to inspect it.
+
+## Create and reconcile an environment
+
+```python
+env = workspace.create_environment(
+    name="experiment",
+    python_version="3.12",
+    torch_backend="auto",
+    no_manager=True,
+)
+env.add_node("rgthree-comfy")
+result = env.sync(model_strategy="required")
+```
+
+Creation and sync can download code and packages. Resolve an existing saved
+workflow by its name, not an arbitrary JSON path:
+
+```python
+result = env.resolve_workflow("my-workflow")
+```
+
+For ambiguous resolution, supply implementations of the protocols in
+[`models/protocols.py`](src/comfygit_core/models/protocols.py). Do not put prompts,
+printing or CLI policy into Core. A successful dependency resolution is not proof
+that a ComfyUI inference job succeeds.
+
+## Credentials
+
+Workspace entry points accept process-local `credential_overrides`, keyed by
+`CredentialProvider`. A token overrides all discovery for that provider; `None`
+explicitly selects anonymous access. Omitted providers use normal discovery.
+
+```python
+from comfygit_core.models.credentials import CredentialProvider
+
+workspace = Workspace.open(
+    Path.home() / "comfygit",
+    credential_overrides={CredentialProvider.HUGGINGFACE: None},
+)
+```
+
+Normal resolution uses provider environment variables, workspace secure storage,
+provider-native credentials when available, then legacy workspace values during
+migration. An unavailable keyring backend does not prevent environment/native
+credentials from working. Saving a new credential requires a working secure store;
+there is no new plaintext fallback. Callers may inject a `CredentialStore` through
+the `credential_store` parameter.
+
+## Portable and local state
+
+The tracked `pyproject.toml`, `workflows/`, `workflow_api/`, shared overlays and
+source metadata form the portable environment. Model bytes stay in the shared
+model directory. ComfyUI/node checkouts, virtualenvs, `.cec/`, local overlays,
+credentials and backend choices are derived or machine-local state.
+
+Use ComfyGit operations to change the recipe; manual runtime edits may be
+replaced on sync. For a headless recreation, use the materialization API or
+[`cg materialize`](https://docs.comfygit.org/user-guide/collaboration/materialize/).
+
+## API and development references
+
+- [Workspace entry points](src/comfygit_core/core/workspace.py)
+- [Environment operations](src/comfygit_core/core/environment.py)
+- [Architecture](docs/architecture.md)
+- [Normative contracts](../../docs/contracts/) and [specifications](../../docs/specs/)
+- [Contributing](../../CONTRIBUTING.md)
+
+From the monorepo root:
+
+```bash
+uv sync --frozen --all-packages
+uv run pytest packages/core/tests -q
+make lint
+```
+
+Core, Studio runtime and CLI releases use matched versions. See the root
+[agent guide](../../AGENTS.md) for release ordering and package boundaries.

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfygit-core"
-version = "0.7.0"
+version = "0.7.1"
 description = "ComfyGit Core - Git-based ComfyUI environment manager"
 readme = "README.md"
 requires-python = ">=3.10"

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/core/environment.py

@@ -6,7 +6,8 @@ import os
 import re
 import shutil
 import subprocess
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
 from datetime import datetime, timezone
 from functools import cached_property, wraps
 from pathlib import Path
@@ -125,7 +126,7 @@ def _workflow_api_prompt_relpath(workflow_name: str) -> Path:
 def _requires_env_lock(method):
     @wraps(method)
     def wrapper(self, *args, **kwargs):
-        with self._operation_lock:
+        with self._operation_lock.named(method.__name__):
             return method(self, *args, **kwargs)
     return wrapper
 
@@ -2532,10 +2533,21 @@ class Environment:
     # Public Snapshots and Readiness
     # =====================================================
 
-    @_requires_env_lock
     def get_manifest_snapshot(self) -> EnvironmentManifestSnapshot:
         """Return a typed read-only projection of the current manifest."""
-        return self.pyproject.get_manifest_snapshot()
+        with self.read_manifest_snapshot() as snapshot:
+            return snapshot
+
+    @contextmanager
+    def read_manifest_snapshot(self) -> Iterator[EnvironmentManifestSnapshot]:
+        """Capture manifest and related artifacts under a short shared lock.
+
+        Do not await, mutate the environment, or execute a prompt in this scope.
+        A new detached snapshot is loaded each time; no stale-cache fallback is
+        used when a writer is active.
+        """
+        with self._operation_lock.read():
+            yield self.pyproject.get_manifest_snapshot(force_reload=True)
 
     def list_manifest_nodes(self) -> Mapping[str, NodeInfo]:
         """Return tracked manifest nodes without exposing the manifest manager."""

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/lifecycle/runtime_control.py

@@ -61,6 +61,7 @@ def read_runtime_advertisement(workspace: Path, environment: str) -> dict | None
         if isinstance(data, dict) and data.get("environment") == environment:
             return data
     except (OSError, ValueError):
+        # Missing or malformed advertisements cannot establish runtime ownership.
         pass
     return None
 
@@ -123,6 +124,7 @@ class ManagedRuntimeController:
                                 and isinstance(data.get("queue_pending"), list)):
                             running, pending = len(data["queue_running"]), len(data["queue_pending"])
                 except (requests.RequestException, ValueError):
+                    # Keep unavailable probes unknown; restart refuses an unverified queue.
                     pass
             return ManagedRuntimeStatus(
                 environment=self.environment, instance_id=self.instance_id,

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/lifecycle/switch_observer.py

@@ -229,6 +229,7 @@ class SwitchObserverServer:
                 if self.runtime_controller and data.get("instance_id") == self.runtime_controller.instance_id:
                     path.unlink(missing_ok=True)
             except (OSError, ValueError):
+                # Cleanup is best effort; never remove an advertisement without ownership proof.
                 pass
 
     def append_log(self, message: str, level: str = "info") -> None:

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/models/__init__.py

@@ -11,6 +11,8 @@ _EXPORTS: dict[str, str] = {
     "CDWorkspaceExistsError": "exceptions",
     "CDCredentialStoreError": "exceptions",
     "CDEnvironmentError": "exceptions",
+    "CDEnvironmentBusyError": "exceptions",
+    "EnvironmentLockOwner": "exceptions",
     "CDEnvironmentNotFoundError": "exceptions",
     "CDEnvironmentExistsError": "exceptions",
     "CDDependencyPreviewStaleError": "exceptions",

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/models/exceptions.py

@@ -41,6 +41,28 @@ class CDEnvironmentError(ComfyDockError):
     """Environment-related errors."""
     pass
 
+
+@dataclass(frozen=True)
+class EnvironmentLockOwner:
+    """Best-effort diagnostics, never authority to delete or steal a lock."""
+
+    pid: int | None = None
+    operation: str | None = None
+    acquired_at: str | None = None
+
+
+class CDEnvironmentBusyError(CDEnvironmentError):
+    """An environment lock is held; the requested operation has not begun."""
+
+    def __init__(self, lock_path: str, owner: EnvironmentLockOwner):
+        self.lock_path = lock_path
+        self.owner = owner
+        super().__init__(
+            "Another ComfyGit operation is running on this environment. "
+            f"Wait for it to complete (owner PID: {owner.pid}, operation: {owner.operation}). "
+            "Do not delete the lock file while an operation may be running."
+        )
+
 class CDEnvironmentNotFoundError(ComfyDockError):
     """Environment doesn't exist."""
     pass

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/models/manifest.py

@@ -1,5 +1,8 @@
 # models/manifest.py
+import hashlib
+import json
 from collections.abc import Mapping
+from copy import deepcopy
 from dataclasses import dataclass, field
 from types import MappingProxyType
 from typing import Any, Literal
@@ -304,6 +307,7 @@ class EnvironmentManifestSnapshot:
     nodes: Mapping[str, NodeInfo]
     workflows: Mapping[str, ManifestWorkflowEntry]
     models: Mapping[str, ManifestModel]
+    revision: str = ""
 
     def get_node(self, identifier: str) -> NodeInfo | None:
         """Return one manifest node by package identifier."""
@@ -331,6 +335,8 @@ class EnvironmentManifestSnapshot:
 
     @classmethod
     def from_toml_dict(cls, data: dict[str, Any]) -> "EnvironmentManifestSnapshot":
+        # Detached from the manager's mutable document, including nested defaults.
+        data = deepcopy(data)
         tool = _plain_mapping(data.get("tool", {}))
         comfygit = _plain_mapping(tool.get("comfygit", {}))
 
@@ -362,6 +368,7 @@ class EnvironmentManifestSnapshot:
             normalized_schema_version = 1
 
         return cls(
+            revision=hashlib.sha256(json.dumps(data, sort_keys=True, default=str).encode()).hexdigest(),
             project=ManifestProjectSnapshot.from_toml_dict(data),
             schema_version=normalized_schema_version,
             comfyui_version=(

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/src/comfygit_core/services/credential_service.py

@@ -70,6 +70,7 @@ class CredentialService:
             if value := self.credential_store.get(workspace_id, provider):
                 return value
         except CDCredentialStoreError:
+            # An unavailable desktop store must not block native/headless credentials.
             pass
 
         if value := self._native_value(provider):

comfygit_core-0.7.1/src/comfygit_core/utils/environment_lock.py

@@ -0,0 +1,196 @@
+"""Environment operation lock utilities."""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+import sys
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import IO
+
+from ..models.exceptions import CDEnvironmentBusyError, EnvironmentLockOwner
+
+
+class EnvironmentOperationLock:
+    """Cross-process, cross-thread lock for environment mutations."""
+
+    def __init__(self, lock_path: Path, *, shared: bool = False, operation: str = "environment operation"):
+        self.lock_path = lock_path
+        self.shared = shared
+        self.operation = operation
+        self._thread_lock = threading.Lock()
+        self._depth = 0
+        self._file: IO[str] | None = None
+        self._owner_thread: int | None = None
+
+    def __enter__(self) -> EnvironmentOperationLock:
+        return self._enter()
+
+    def _enter(self, operation: str | None = None) -> EnvironmentOperationLock:
+        current_thread = threading.get_ident()
+        with self._thread_lock:
+            if self._depth > 0 and self._owner_thread != current_thread:
+                raise self._busy_error()
+            if self._depth == 0:
+                if operation is not None:
+                    self.operation = operation
+                self._acquire_file_lock()
+                self._owner_thread = current_thread
+            self._depth += 1
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        with self._thread_lock:
+            self._depth -= 1
+            if self._depth == 0:
+                self._owner_thread = None
+                self._release_file_lock()
+        return False
+
+    @contextmanager
+    def read(self) -> Iterator[None]:
+        """Short shared read scope; never hold across await or upgrade to a write."""
+        with self._thread_lock:
+            owns_write = self._depth > 0 and self._owner_thread == threading.get_ident()
+        if owns_write:
+            # Synchronous reads nested inside a mutation already have protection.
+            yield
+            return
+        with EnvironmentOperationLock(self.lock_path, shared=True, operation="snapshot read"):
+            yield
+
+    @contextmanager
+    def named(self, operation: str) -> Iterator[None]:
+        """Label the outer mutation, retaining its label across nested calls."""
+        self._enter(operation)
+        try:
+            yield
+        finally:
+            self.__exit__(None, None, None)
+
+    def _busy_error(self) -> CDEnvironmentBusyError:
+        owner = EnvironmentLockOwner()
+        try:
+            with self.lock_path.open(encoding="utf-8") as source:
+                # Win32 locks byte zero against even diagnostic reads. New
+                # writers reserve that byte and put their JSON after it.
+                if sys.platform == "win32":
+                    source.seek(1)
+                data = json.loads(source.read(4096))
+            if isinstance(data, int) and sys.platform != "win32":  # Legacy PID-only writer.
+                owner = EnvironmentLockOwner(pid=data)
+            elif isinstance(data, dict):
+                owner = EnvironmentLockOwner(
+                    pid=data.get("pid") if type(data.get("pid")) is int else None,
+                    operation=str(data["operation"])[:160] if data.get("operation") else None,
+                    acquired_at=str(data["acquired_at"])[:64] if data.get("acquired_at") else None,
+                )
+        except (OSError, ValueError):
+            pass
+        return CDEnvironmentBusyError(str(self.lock_path), owner)
+
+    def _acquire_file_lock(self) -> None:
+        self.lock_path.parent.mkdir(parents=True, exist_ok=True)
+        self._file = open(self.lock_path, "a+")
+
+        try:
+            self._file.seek(0)
+            if sys.platform == "win32":
+                try:
+                    _windows_lock(self._file.fileno(), shared=self.shared)
+                except OSError as e:
+                    if e.winerror == 33:  # ERROR_LOCK_VIOLATION
+                        raise self._busy_error() from e
+                    raise
+            else:
+                import fcntl
+
+                try:
+                    mode = fcntl.LOCK_SH if self.shared else fcntl.LOCK_EX
+                    fcntl.flock(self._file.fileno(), mode | fcntl.LOCK_NB)
+                except OSError as e:
+                    if e.errno in {errno.EAGAIN, errno.EACCES}:
+                        raise self._busy_error() from e
+                    raise
+
+            if self.shared:
+                return  # Readers must not overwrite or clear writer diagnostics.
+
+            try:
+                self._file.seek(0)
+                self._file.truncate()
+                self._file.write(" ")
+                json.dump({"pid": os.getpid(), "operation": self.operation,
+                           "acquired_at": datetime.now(timezone.utc).isoformat()}, self._file)
+                self._file.flush()
+            except OSError:
+                pass
+        except Exception:
+            self._file.close()
+            self._file = None
+            raise
+
+    def _release_file_lock(self) -> None:
+        if not self._file:
+            return
+
+        try:
+            self._file.seek(0)
+            try:
+                if not self.shared:
+                    self._file.truncate()
+                    self._file.flush()
+            except OSError:
+                pass
+
+            if sys.platform == "win32":
+                try:
+                    _windows_lock(self._file.fileno(), shared=self.shared, unlock=True)
+                except OSError:
+                    pass
+            else:
+                import fcntl
+
+                try:
+                    fcntl.flock(self._file.fileno(), fcntl.LOCK_UN)
+                except OSError:
+                    pass
+        finally:
+            self._file.close()
+            self._file = None
+
+
+def _windows_lock(fd: int, *, shared: bool, unlock: bool = False) -> None:
+    """Lock byte zero with Win32 shared/exclusive semantics (msvcrt lacks shared locks)."""
+    if sys.platform != "win32":
+        raise RuntimeError("Win32 locking is only available on Windows")
+    import ctypes
+    import msvcrt
+    from ctypes import wintypes
+
+    class Overlapped(ctypes.Structure):
+        _fields_ = [("Internal", ctypes.c_size_t), ("InternalHigh", ctypes.c_size_t),
+                    ("Offset", wintypes.DWORD), ("OffsetHigh", wintypes.DWORD),
+                    ("hEvent", wintypes.HANDLE)]
+
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    handle = wintypes.HANDLE(msvcrt.get_osfhandle(fd))
+    overlap = Overlapped()
+    if unlock:
+        fn = kernel.UnlockFileEx
+        fn.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD,
+                       wintypes.DWORD, ctypes.POINTER(Overlapped)]
+        args = (handle, 0, 1, 0, ctypes.byref(overlap))
+    else:
+        fn = kernel.LockFileEx
+        fn.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD,
+                       wintypes.DWORD, wintypes.DWORD, ctypes.POINTER(Overlapped)]
+        args = (handle, 1 | (0 if shared else 2), 0, 1, 0, ctypes.byref(overlap))
+    fn.restype = wintypes.BOOL
+    if not fn(*args):
+        raise ctypes.WinError(ctypes.get_last_error())

{comfygit_core-0.7.0 → comfygit_core-0.7.1}/tests/unit/core/test_environment_operation_locking.py

@@ -1,5 +1,7 @@
 """Tests for environment operation lock decorators."""
 
+import os
+
 from comfygit_core.core.environment import Environment
 from comfygit_core.utils.environment_lock import EnvironmentOperationLock
 
@@ -13,6 +15,9 @@ class _FakeLock:
         self.entered = True
         return self
 
+    def named(self, operation):
+        return self
+
     def __exit__(self, exc_type, exc, tb) -> bool:
         self.exited = True
         return False
@@ -50,6 +55,8 @@ def test_environment_operation_lock_clears_owner_file_on_release(tmp_path):
     lock_path = tmp_path / ".comfygit.lock"
 
     with EnvironmentOperationLock(lock_path):
-        assert lock_path.read_text(encoding="utf-8").strip()
+        # Windows reserves byte zero for the mandatory OS lock. Read owner
+        # diagnostics through the same portable path used by contending callers.
+        assert EnvironmentOperationLock(lock_path)._busy_error().owner.pid == os.getpid()
 
     assert lock_path.read_text(encoding="utf-8") == ""