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

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

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

{kd_cli-2.5.1 → kd_cli-2.5.2}/kd/cli/namespaces/article/__init__.py

@@ -181,7 +181,8 @@ class ArticlePushCommand(Command):
             requires_client=True,
             usage=(
                 "kd /article push FILE --project P --title T "
-                "[--slug S] [--parent ID] [--tag T] [--create-tags] [--force] [--dry-run]"
+                "[--slug S] [--parent ID] [--tag T] [--create-tags] "
+                "[--force] [--dry-run] [--no-marker-write]"
             ),
             long_description=(
                 "Push a local markdown file to YouTrack as a knowledge base "
@@ -194,7 +195,13 @@ class ArticlePushCommand(Command):
                 "the marker — treat the file as owned by push after the first "
                 "run, like Cargo.lock. "
                 "Refuses to overwrite a remotely-edited article unless --force "
-                "is passed. --dry-run exits 1 on would-conflict, 0 on would-succeed."
+                "is passed. --dry-run exits 1 on would-conflict, 0 on would-succeed. "
+                "Pass --no-marker-write for one-way migrations where the local "
+                "file will be deleted after the push: the article is still "
+                "created/updated and tags are still applied, but the local file "
+                "is not rewritten. Re-running --no-marker-write pays the "
+                "scan-by-slug cost on every invocation since no upstream-id is "
+                "cached locally."
             ),
             examples=[
                 'kd /article push docs/infra/dns-setup.md --project FB --title "DNS Setup Guide"',
@@ -204,6 +211,8 @@ class ArticlePushCommand(Command):
                 'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --create-tags',
                 'kd /article push guide.md --project FB --title "Guide" --dry-run',
                 'kd /article push guide.md --project FB --title "Guide" --force',
+                'kd /article push migrated.md --project FB --title "Migrated" --no-marker-write',
+                'kd /article push migrated.md --project FB --title "Migrated" --no-marker-write --tag "type:guide"',
             ],
             see_also=[
                 "/article pull",
@@ -274,6 +283,18 @@ class ArticlePushCommand(Command):
                 help_text="Create missing tags before pushing",
             )
         )
+        self.register_option(
+            OptionDeclaration(
+                name="no-marker-write",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Skip the local kd-meta marker rewrite for one-way "
+                    "migrations; the server write and tag apply still run"
+                ),
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -300,6 +321,7 @@ class ArticlePushCommand(Command):
             dry_run=bool(options.command.get("dry-run")),
             tags=tags or None,
             create_tags=bool(options.command.get("create-tags")),
+            write_marker=not bool(options.command.get("no-marker-write")),
         )
         return {
             "ok": True,
@@ -310,6 +332,8 @@ class ArticlePushCommand(Command):
             "dry_run": result.dry_run,
             "tags_applied": result.tags_applied,
             "tags_failed": result.tags_failed,
+            "marker_written": result.marker_written,
+            "parent": result.parent,
         }
 
 

{kd_cli-2.5.1 → kd_cli-2.5.2}/kd/client.py

@@ -195,6 +195,11 @@ class PushResult:
     - ``remote_updated_sec`` is the epoch-seconds timestamp of the
       article's ``updated`` field on the upstream side after the push.
       Zero for dry-runs that did not resolve an existing article.
+    - ``marker_written`` is ``True`` iff the local file was rewritten
+      on this invocation. ``False`` for dry-runs and for
+      ``write_marker=False`` pushes (one-way migrations).
+    - ``parent`` is the ``id_readable`` of the target article's parent
+      on the upstream side, or ``None`` for root articles.
     """
 
     action: Literal["create", "update"]
@@ -205,6 +210,8 @@ class PushResult:
     dry_run: bool
     tags_applied: builtins.list[str] = dataclass_field(default_factory=list)
     tags_failed: builtins.list[str] = dataclass_field(default_factory=list)
+    marker_written: bool = False
+    parent: str | None = None
 
 
 def _derive_slug_from_path(file_path: Path) -> str:
@@ -1304,6 +1311,7 @@ class ArticleOperations:
         dry_run: bool = False,
         tags: builtins.list[str] | None = None,
         create_tags: bool = False,
+        write_marker: bool = True,
     ) -> PushResult:
         """Idempotently upsert a local markdown file as a YouTrack article.
 
@@ -1314,6 +1322,10 @@ class ArticleOperations:
 
         On success, the local file is rewritten atomically to refresh
         the marker's ``upstream-id`` and ``upstream-updated`` fields.
+        Pass ``write_marker=False`` for one-way migrations where the
+        local file will be deleted after the push — the outgoing
+        server payload is unchanged, only the local write-back is
+        skipped. See ``PushResult.marker_written`` (KDCLI-110).
         """
         # Step 1: read the local file and parse the marker.
         try:
@@ -1437,8 +1449,12 @@ class ArticleOperations:
         # Dry-run bails out here with all validation done but no writes.
         if dry_run:
             existing_sec = 0
-            if existing_remote is not None and existing_remote.updated is not None:
-                existing_sec = existing_remote.updated // 1000
+            existing_parent: str | None = None
+            if existing_remote is not None:
+                if existing_remote.updated is not None:
+                    existing_sec = existing_remote.updated // 1000
+                if existing_remote.parent_article is not None:
+                    existing_parent = existing_remote.parent_article.id_readable
             return PushResult(
                 action="update" if is_update else "create",
                 article_id=existing_remote.id_readable if existing_remote else "",
@@ -1446,6 +1462,8 @@ class ArticleOperations:
                 path=file_path,
                 remote_updated_sec=existing_sec,
                 dry_run=True,
+                marker_written=False,
+                parent=existing_parent,
             )
 
         # Step 7: build outgoing content. `upstream-updated` is intentionally
@@ -1514,10 +1532,18 @@ class ArticleOperations:
         )
         final_content = render_content(final)
 
-        # Step 10: atomic local write-back.
-        _atomic_write_text(file_path, final_content)
+        # Step 10: atomic local write-back (skipped for one-way
+        # migration flows that opt out via write_marker=False; the
+        # server payload in Step 7 is unchanged either way).
+        if write_marker:
+            _atomic_write_text(file_path, final_content)
 
         # Step 11: return result.
+        result_parent: str | None = (
+            result_article.parent_article.id_readable
+            if result_article.parent_article is not None
+            else None
+        )
         push_result = PushResult(
             action="update" if is_update else "create",
             article_id=result_article.id_readable,
@@ -1527,6 +1553,8 @@ class ArticleOperations:
             dry_run=False,
             tags_applied=tags_applied,
             tags_failed=tags_failed,
+            marker_written=write_marker,
+            parent=result_parent,
         )
         if tags_failed:
             raise KdError(

{kd_cli-2.5.1 → kd_cli-2.5.2}/kd/resources/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.5.2] — 2026-04-19
+
+### Fixed
+- `kd /article push` one-way migrations no longer force `git rm -f`. Before: push always rewrote the local markdown file with a `kd-meta` marker on success, which left the file "locally modified" and made `git rm` refuse without `-f` on migrations that delete the local copy after push. Now: pass `--no-marker-write` to skip the local rewrite. The upstream article is still created or updated, `--tag` values are still applied, and the outgoing server payload still carries a marker with the slug — so scan-by-slug resolves the article on any later push even without the local file. Default behavior is unchanged; the flag is opt-in (KDCLI-110).
+
+### Added
+- `kd /article push` structured output (`-o yaml` / `-o json`) now carries two sibling keys on every push: `marker_written` (`false` for dry-runs and `--no-marker-write` pushes, `true` on the default path after the local rewrite) and `parent` (readable id of the target article's upstream parent, or `null` for root articles). Scripts can assert local-file state and the article's place in the tree from the push response directly (KDCLI-110).
+
 ## [2.5.1] — 2026-04-19
 
 ### Fixed

{kd_cli-2.5.1 → kd_cli-2.5.2}/kd/resources/operating-guide.md

@@ -158,6 +158,8 @@ Use `/article show` for metadata plus rendered content. Use `/article pull` when
 
 Do not use push for one-off web edits or broad tree migration. It is single-file by design. If the remote changed, pull, diff, merge by hand, then push again. Use `--force` only after inspecting the remote state.
 
+For one-way migrations where the local file will be deleted after the push, pass `--no-marker-write`. The server article is still created or updated and tags are still applied, but kd skips the local `kd-meta` rewrite so `git rm` works without `-f`. The structured response gains `marker_written: false`; re-running `--no-marker-write` pays the scan-by-slug cost every invocation because no `upstream-id` is cached locally.
+
 When pushing with `--tag`, kd validates all tags before the article write. Missing tags abort with commands to list the namespace, create the tag, retry without it, or apply the tag separately after push. `--create-tags` is the explicit opt-in for automation that should create missing tags first.
 
 `/article create --tag` applies the same preflight: every tag must exist, missing tags abort before the article write (no orphan article on a typo), and the structured response reflects post-tag state so it matches an immediate `/article show` on the returned id. There is no `--create-tags` on `/article create` — curate the namespace with `/tag create` first, or omit `--tag` and apply tags after creation via `/tag add ARTICLE-ID TAG`.

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

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

{kd_cli-2.5.1 → kd_cli-2.5.2}/pyproject.toml

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