kd-cli 2.5.1__tar.gz → 2.6.0__tar.gz

{kd_cli-2.5.1/kd_cli.egg-info → kd_cli-2.6.0}/PKG-INFO

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

{kd_cli-2.5.1 → kd_cli-2.6.0}/kd/article_marker.py

@@ -3,7 +3,8 @@
 The marker block is the upsert key for ``/article push``. It lives as
 an HTML comment at the top of an article's content and in the local
 source file. See ``docs/proposals/19-article-push-proposal.md`` for
-the full rationale.
+the original design and ``docs/proposals/41-minimal-article-marker-proposal.md``
+for the identity-only shrink.
 
 Grammar (informal):
 
@@ -23,11 +24,20 @@ Rules (pinned down by ``tests/test_article_marker.py``):
   property that lets future kd versions add keys without breaking
   older versions' round-trips.
 - Known keys are emitted first in the canonical order ``slug``,
-  ``upstream-id``, ``upstream-updated``. Unknown keys follow in their
+  ``upstream-id``. Unknown keys (including the legacy
+  ``upstream-updated`` produced by pre-S1 pushes) follow in their
   original insertion order.
 - Line endings and trailing newlines are preserved so that a
   ``parse → render`` cycle is a fixed point.
 
+Write-back semantics (proposal 41): push writes the local marker only
+when identity must be established or repaired (no marker, missing
+``upstream-id``, or resolved article id differs). It never rewrites the
+file just to refresh tool-generated state. ``upstream-updated`` is
+parsed and preserved when present (forward-compat for the existing
+passive-timestamp conflict path) but is no longer emitted by new
+pushes.
+
 Legacy marker synonym (transitional, proposal 28 / M003 §S4):
 
     The parser accepts any ``<!-- kd-meta`` or ``<!-- ytctl-meta``
@@ -95,8 +105,9 @@ _LINE_RE = re.compile(r"^([a-z][a-z0-9-]*)\s*:\s*(.*)$")
 _SLUG_RE = re.compile(r"^[A-Za-z0-9._][A-Za-z0-9._/\-]*$")
 
 # Canonical emission order for keys kd itself writes. Anything else
-# is an "unknown key" and appended in original order.
-_KNOWN_KEYS: tuple[str, ...] = ("slug", "upstream-id", "upstream-updated")
+# (including the legacy ``upstream-updated`` from pre-S1 pushes) is an
+# "unknown key" and appended in original order.
+_KNOWN_KEYS: tuple[str, ...] = ("slug", "upstream-id")
 
 
 class MarkerError(ValidationError):
@@ -108,9 +119,10 @@ class ArticleMarker:
     """Parsed kd-meta marker block.
 
     ``data`` is an insertion-ordered dict of every key/value pair found
-    in the block, including unknown keys. The three known keys expose
-    typed properties for convenience; everything else is accessed via
-    ``data``.
+    in the block, including unknown keys. The two canonical known keys
+    (``slug``, ``upstream-id``) and the tolerated legacy key
+    ``upstream-updated`` expose typed properties for convenience;
+    everything else is accessed via ``data``.
     """
 
     data: "OrderedDict[str, str]" = field(default_factory=OrderedDict)
@@ -134,6 +146,13 @@ class ArticleMarker:
 
     @property
     def upstream_updated(self) -> str | None:
+        """Legacy ``upstream-updated`` value if present.
+
+        Forward-compat accessor: pre-S1 pushes emitted this in the
+        canonical set; new pushes never emit it. The existing passive-
+        timestamp conflict path in ``ArticleOperations.push`` still
+        reads it when present.
+        """
         return self.data.get("upstream-updated")
 
 
@@ -290,8 +309,9 @@ def _join_body(lines: list[str], trailing_newline: bool) -> str:
 def render_content(parsed: ParsedFile) -> str:
     """Render a ``ParsedFile`` back to text, preserving byte-identity.
 
-    - Known keys first (``slug``, ``upstream-id``, ``upstream-updated``),
-      then unknown keys in their original insertion order.
+    - Canonical known keys first (``slug``, ``upstream-id``), then any
+      remaining keys (including the tolerated legacy ``upstream-updated``)
+      in their original insertion order.
     - Blank line separator between ``-->`` and the first body line
       (canonical form; also the shape the YouTrack web UI normalizes
       into).