kd-cli 2.4.0__tar.gz → 2.4.1__tar.gz

{kd_cli-2.4.0/kd_cli.egg-info → kd_cli-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.4.0
+Version: 2.4.1
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

kd_cli-2.4.1/kd/locking.py

@@ -0,0 +1,97 @@
+"""Advisory file locking for read-modify-write transactions on kd-managed files.
+
+Provides :func:`file_transaction` — a context manager that acquires an
+exclusive advisory lock on a sidecar lockfile (``<path>.lock``) for the
+duration of a load → mutate → save cycle.  Concurrent kd processes that
+enter the same transaction serialize rather than clobber each other.
+
+Design notes:
+
+* **Sidecar lockfile, not the target file.**  Atomic writes elsewhere in
+  kd use ``tempfile.mkstemp`` + ``os.replace``, which changes the target
+  file's inode on every write.  Holding ``flock`` on the target inode
+  would not protect a second writer that opens the freshly-replaced file.
+  Locking a separate sidecar file that nobody rewrites keeps the lock
+  stable across atomic replaces of the data file.
+
+* **No unlink on release.**  Removing the lockfile after releasing the
+  lock is a classic race: process B can open the doomed inode while
+  process C creates a fresh one, and both end up holding "exclusive"
+  locks on different inodes.  Empty sidecar files are cheap; leave them.
+
+* **POSIX only.**  ``fcntl`` is imported lazily inside the context
+  manager so that unrelated kd commands remain importable on Windows.
+  On non-POSIX platforms, :func:`file_transaction` raises ``ConfigError``
+  with a suggestion to run the command sequentially.
+
+* **NFS caveat.**  ``flock`` on NFS has been unreliable historically.
+  Modern Linux kernels implement it correctly, but operators using a
+  networked ``$HOME`` should be aware that concurrency guarantees weaken.
+  Local ``.kd/`` directories inside a repo are unaffected.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from kd.exceptions import ConfigError
+
+LOCK_SUFFIX = ".lock"
+_POLL_INTERVAL_SECONDS = 0.05
+
+
+@contextmanager
+def file_transaction(path: Path, *, timeout: float = 30.0) -> Generator[None, None, None]:
+    """Hold an exclusive advisory lock on ``<path>.lock`` for the ``with`` body.
+
+    The sidecar lockfile is created if missing (``O_RDWR | O_CREAT``,
+    never truncated).  Acquisition polls non-blocking ``flock`` until
+    the lock is granted or *timeout* seconds elapse.  On timeout, raises
+    :class:`ConfigError` naming the contested file.  The lockfile is
+    intentionally left on disk after release.
+
+    Raises :class:`ConfigError` on non-POSIX platforms.
+    """
+    if sys.platform == "win32":
+        raise ConfigError(
+            "File locking is not available on this platform (POSIX only).",
+            suggestion="Run the kd command sequentially; concurrent mutations are not supported on Windows.",
+        )
+
+    import fcntl  # noqa: PLC0415 — lazy import keeps kd importable on Windows
+
+    lock_path = path.with_name(path.name + LOCK_SUFFIX)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise ConfigError(
+                        f"Another kd process is writing to {path}; retry in a moment.",
+                        suggestion=f"If no other kd process is running, remove the stale lockfile: {lock_path}",
+                    ) from None
+                time.sleep(_POLL_INTERVAL_SECONDS)
+
+        try:
+            yield
+        finally:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass

{kd_cli-2.4.0 → kd_cli-2.4.1}/kd/primer.py

@@ -11,6 +11,8 @@ knowledge).  The file is created lazily on first write operation.
 from __future__ import annotations
 
 import importlib.resources
+from collections.abc import Generator
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
@@ -18,6 +20,7 @@ import yaml
 from pydantic import BaseModel
 
 from kd.exceptions import ConfigError, ValidationError
+from kd.locking import file_transaction
 
 
 # ---------------------------------------------------------------------------
@@ -125,10 +128,15 @@ def load_primer(path: Path | None = None) -> PrimerData:
 
 
 def save_primer(data: PrimerData, path: Path | None = None) -> None:
-    """Write primer to YAML.
+    """Write primer to YAML — low-level primitive.
 
     Snapshots the current file before writing (copy-on-write) and uses
-    atomic writes to prevent partial-write corruption.
+    atomic writes to prevent partial-write corruption.  Does **not**
+    serialize concurrent writers on its own; callers that do
+    ``load_primer → mutate → save_primer`` across processes risk lost
+    updates.  Prefer the mutator functions below (:func:`add_note`,
+    :func:`update_note`, etc.), which wrap load/save in
+    :func:`primer_transaction` to guarantee per-file serialization.
     """
     from kd.history import atomic_write_text, snapshot_before_write
 
@@ -172,46 +180,56 @@ def _tag_dump(tag: dict[str, Any]) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
+@contextmanager
+def _primer_transaction(path: Path) -> Generator[PrimerData, None, None]:
+    """Serialize a primer read-modify-write cycle under an advisory lock.
+
+    Holds an exclusive advisory lock on ``<path>.lock`` for the full
+    cycle: loads the primer, yields a ``PrimerData`` for the caller to
+    mutate in place, and saves on clean exit.  If the caller raises,
+    the save is skipped (the file is not modified).
+    """
+    with file_transaction(path):
+        data = load_primer(path)
+        yield data
+        save_primer(data, path)
+
+
 def add_note(text: str, path: Path | None = None) -> int:
     """Append a note. Returns the 1-based index."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    data.notes.append(text)
-    save_primer(data, primer_file)
-    return len(data.notes)
+    with _primer_transaction(primer_file) as data:
+        data.notes.append(text)
+        return len(data.notes)
 
 
 def remove_note(index: int, path: Path | None = None) -> str:
     """Remove a note by 1-based index. Returns the removed text."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    if index < 1 or index > len(data.notes):
-        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
-    removed = data.notes.pop(index - 1)
-    save_primer(data, primer_file)
-    return removed
+    with _primer_transaction(primer_file) as data:
+        if index < 1 or index > len(data.notes):
+            raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+        return data.notes.pop(index - 1)
 
 
 def update_note(index: int, text: str, path: Path | None = None) -> str:
     """Replace a note by 1-based index. Returns the old text."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    if index < 1 or index > len(data.notes):
-        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
-    old = data.notes[index - 1]
-    data.notes[index - 1] = text
-    save_primer(data, primer_file)
-    return old
+    with _primer_transaction(primer_file) as data:
+        if index < 1 or index > len(data.notes):
+            raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+        old = data.notes[index - 1]
+        data.notes[index - 1] = text
+        return old
 
 
 def clear_notes(path: Path | None = None) -> int:
     """Remove all notes. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.notes)
-    data.notes.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.notes)
+        data.notes.clear()
+        return count
 
 
 def add_article(
@@ -219,71 +237,63 @@ def add_article(
 ) -> PrimerArticle:
     """Pin an article. Raises if already pinned."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for existing in data.articles:
-        if existing.id == article_id:
-            raise ValidationError(f"Article '{article_id}' is already pinned")
-    article = PrimerArticle(id=article_id, summary=summary)
-    data.articles.append(article)
-    save_primer(data, primer_file)
-    return article
+    with _primer_transaction(primer_file) as data:
+        for existing in data.articles:
+            if existing.id == article_id:
+                raise ValidationError(f"Article '{article_id}' is already pinned")
+        article = PrimerArticle(id=article_id, summary=summary)
+        data.articles.append(article)
+        return article
 
 
 def remove_article(article_id: str, path: Path | None = None) -> PrimerArticle:
     """Unpin an article by ID. Returns the removed entry."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for i, article in enumerate(data.articles):
-        if article.id == article_id:
-            removed = data.articles.pop(i)
-            save_primer(data, primer_file)
-            return removed
-    raise ValidationError(f"Article '{article_id}' is not pinned")
+    with _primer_transaction(primer_file) as data:
+        for i, article in enumerate(data.articles):
+            if article.id == article_id:
+                return data.articles.pop(i)
+        raise ValidationError(f"Article '{article_id}' is not pinned")
 
 
 def clear_articles(path: Path | None = None) -> int:
     """Remove all pinned articles. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.articles)
-    data.articles.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.articles)
+        data.articles.clear()
+        return count
 
 
 def add_tag(name: str, summary: str | None = None, path: Path | None = None) -> PrimerTag:
     """Pin a tag. Raises if already pinned."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for existing in data.tags:
-        if existing.name == name:
-            raise ValidationError(f"Tag '{name}' is already pinned")
-    tag = PrimerTag(name=name, summary=summary)
-    data.tags.append(tag)
-    save_primer(data, primer_file)
-    return tag
+    with _primer_transaction(primer_file) as data:
+        for existing in data.tags:
+            if existing.name == name:
+                raise ValidationError(f"Tag '{name}' is already pinned")
+        tag = PrimerTag(name=name, summary=summary)
+        data.tags.append(tag)
+        return tag
 
 
 def remove_tag(name: str, path: Path | None = None) -> PrimerTag:
     """Unpin a tag by name. Returns the removed entry."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for i, tag in enumerate(data.tags):
-        if tag.name == name:
-            removed = data.tags.pop(i)
-            save_primer(data, primer_file)
-            return removed
-    raise ValidationError(f"Tag '{name}' is not pinned")
+    with _primer_transaction(primer_file) as data:
+        for i, tag in enumerate(data.tags):
+            if tag.name == name:
+                return data.tags.pop(i)
+        raise ValidationError(f"Tag '{name}' is not pinned")
 
 
 def clear_tags(path: Path | None = None) -> int:
     """Remove all pinned tags. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.tags)
-    data.tags.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.tags)
+        data.tags.clear()
+        return count
 
 
 # ---------------------------------------------------------------------------

{kd_cli-2.4.0 → kd_cli-2.4.1}/kd/resources/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.4.1] — 2026-04-19
+
+### Fixed
+- Concurrent `kd /primer/note`, `/primer/tag`, and `/primer/article` commands against the same `.kd/primer.yaml` no longer silently lose writes. Before: running three `kd /primer/note update` calls in parallel (common in agent-driven sessions) all reported `ok: true` but only one update survived. Now: each command runs inside an advisory file lock on a sidecar `.kd/primer.yaml.lock`, so concurrent kd processes queue rather than clobber each other and every successful call is reflected in the final file. Concurrent acquirers wait up to 30 s before erroring with `Another kd process is writing to …; retry in a moment`; the error includes the path of the sidecar lockfile for stale-holder recovery. POSIX only; first lock attempt on Windows raises a clear error pointing at sequential invocation (KDCLI-98).
+
 ## [2.4.0] — 2026-04-19
 
 ### Added

{kd_cli-2.4.0 → kd_cli-2.4.1}/kd/resources/operating-guide.md

@@ -146,6 +146,8 @@ When both pinned tags and pinned articles exist, read them in order: notes tell
 
 Keep the primer local and curated. If a note becomes generally true for kd, move it into docs or this guide. If it is workspace-specific, keep it in `.kd/primer.yaml`.
 
+Primer mutations are serialized per file through an advisory lock on `.kd/primer.yaml.lock`; concurrent kd processes writing to the same primer queue rather than conflict, so agent-launched parallel `/primer/note`, `/primer/tag`, and `/primer/article` commands all converge without lost updates.
+
 ## Articles And Push
 
 Use `/article show` for metadata plus rendered content. Use `/article pull` when you need raw article content on stdout; `pull` is format-agnostic and ignores `--output`.

{kd_cli-2.4.0 → kd_cli-2.4.1/kd_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.4.0
+Version: 2.4.1
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.4.0 → kd_cli-2.4.1}/kd_cli.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ kd/connection.py
 kd/debug.py
 kd/exceptions.py
 kd/history.py
+kd/locking.py
 kd/operating_guide.py
 kd/primer.py
 kd/query_parser.py

{kd_cli-2.4.0 → kd_cli-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.4.0"
+version = "2.4.1"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"