kd-cli 2.6.1__tar.gz → 2.6.2__tar.gz

{kd_cli-2.6.1/kd_cli.egg-info → kd_cli-2.6.2}/PKG-INFO

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

{kd_cli-2.6.1 → kd_cli-2.6.2}/kd/cli/core/option_registry.py

@@ -246,7 +246,12 @@ def state_option(
     )
 
 
-# Standard OUTPUT options available to all commands
+# Standard OUTPUT options available to all commands.
+#
+# ``--quiet`` is registered globally so any command's parser accepts it,
+# but it only affects mutation commands that opt into the write-output
+# contract (``display_hint="mutation"``). On reads and structured output
+# modes (``-o yaml`` / ``-o json``), ``--quiet`` is silently no-op.
 OUTPUT_OPTIONS: list[OptionDeclaration] = [
     OptionDeclaration(
         name="output",
@@ -263,4 +268,14 @@ OUTPUT_OPTIONS: list[OptionDeclaration] = [
         type=str,
         help_text="Comma-separated field list",
     ),
+    OptionDeclaration(
+        name="quiet",
+        layer=OptionLayer.OUTPUT,
+        type=bool,
+        default=False,
+        help_text=(
+            "Suppress detail block on mutation commands; print only the "
+            "single-line ack. No-op on reads and structured modes (-o yaml/json)."
+        ),
+    ),
 ]

{kd_cli-2.6.1 → kd_cli-2.6.2}/kd/cli/main.py

@@ -324,8 +324,11 @@ def main(argv: list[str] | None = None) -> None:
     if result is not None:
         fmt = parsed.options.output.get("output")
         fields = parsed.options.output.get("fields")
+        quiet = bool(parsed.options.output.get("quiet"))
         display_hint = getattr(parsed.command, "display_hint", None)
-        output = formatter.format(result, fmt=fmt, fields=fields, display_hint=display_hint)
+        output = formatter.format(
+            result, fmt=fmt, fields=fields, display_hint=display_hint, quiet=quiet
+        )
         if output:
             # String results (e.g. /article pull) own their trailing newline.
             # Everything else goes through print() which appends one newline.
@@ -335,6 +338,11 @@ def main(argv: list[str] | None = None) -> None:
                     sys.stdout.write("\n")
             else:
                 print(output)
+        # Route warnings extracted in text/md modes to stderr so stdout
+        # stays parseable for ``tail -1 | awk`` recipes. Structured modes
+        # leave warnings in the payload — last_warnings is empty there.
+        if formatter.last_warnings:
+            print(formatter.render_warnings(formatter.last_warnings), file=sys.stderr)
 
 
 def _extract_globals(args: list[str]) -> tuple[dict[str, Any], list[str]]:

{kd_cli-2.6.1 → kd_cli-2.6.2}/kd/cli/namespaces/article/__init__.py

@@ -213,7 +213,16 @@ class ArticlePushCommand(Command):
                 "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."
+                "cached locally. "
+                "Returns a parseable single-line ack: the last stdout line "
+                "is ``ok: <ID> created [slug=<slug> ...]`` for the create "
+                "branch or ``ok: <ID> updated [slug=<slug> ...]`` for the "
+                "update branch. Dry-run create has no upstream article yet "
+                "and ``id`` is null in the structured envelope; the tail "
+                "line carries ``dry_run=true`` and is **not "
+                "ID-extractable** via ``tail -1 | awk '{print $2}'``. "
+                "Drop --dry-run before relying on tail extraction. Pass "
+                "--quiet to suppress the detail block above the ack."
             ),
             examples=[
                 'kd /article push docs/infra/dns-setup.md --project FB --title "DNS Setup Guide"',
@@ -233,6 +242,7 @@ class ArticlePushCommand(Command):
                 "/article move",
             ],
         )
+        self.display_hint = "mutation"
 
     def _register_options(self) -> None:
         self.register_option(project_option(help_text="Project key for new articles (required)"))
@@ -345,10 +355,27 @@ class ArticlePushCommand(Command):
                     f"Wrote kd-meta marker to {result.path} (one-time; commit alongside content).",
                     file=sys.stderr,
                 )
+        # Map SDK PushResult.action ("create"/"update") to the contract's
+        # past-tense vocabulary at the CLI boundary. The SDK shape stays
+        # imperative; the contract lives here.
+        contract_action = {
+            "create": "created",
+            "update": "updated",
+        }.get(result.action, result.action)
+        # Dry-run create has no upstream article yet. The SDK returns
+        # ``article_id=""`` (empty string) on that path; the contract
+        # normalizes that to ``None`` so the tail-line formatter renders
+        # the ``<none>`` placeholder and structured consumers can detect
+        # the carve-out via ``id is None``. Production creates and
+        # production updates carry the article ID as expected, and
+        # dry-run updates carry the existing article ID.
+        envelope_id: str | None = result.article_id
+        if not envelope_id:
+            envelope_id = None
         return {
             "ok": True,
-            "action": result.action,
-            "article": result.article_id,
+            "action": contract_action,
+            "id": envelope_id,
             "slug": result.slug,
             "path": str(result.path),
             "dry_run": result.dry_run,
@@ -403,9 +430,14 @@ class ArticleCreateCommand(Command):
                 "two-step in migration scripts. Pass --tag (repeatable) to "
                 "apply tags at creation time: every --tag must exist, the "
                 "article is refused before creation if any tag is missing "
-                "(no orphan article on unknown tags), and the structured "
-                "response reflects post-tag state so it matches a "
-                "subsequent /article show on the returned id."
+                "(no orphan article on unknown tags). "
+                "Returns a parseable single-line ack. The last stdout line is "
+                "``ok: <ID> created [parent=<P>] [tags=<a>,<b>]`` so "
+                "``id=$(kd /article create ... --quiet | tail -1 | "
+                "awk '{print $2}')`` extracts the new article ID. Pass "
+                "--quiet to suppress the detail block; structured output "
+                "(-o yaml/json) returns the full envelope including the "
+                "submitted summary and project."
             ),
             examples=[
                 'kd /article create "Setup Guide" --project FB --content @guide.md',
@@ -416,6 +448,7 @@ class ArticleCreateCommand(Command):
             ],
             see_also=["/article show", "/article update", "/article move"],
         )
+        self.display_hint = "mutation"
 
     def _register_options(self) -> None:
         self.register_option(project_option(required=True))
@@ -461,7 +494,19 @@ class ArticleCreateCommand(Command):
             parent=parent,
             tags=tags or None,
         )
-        return _article_to_detail(article)
+        envelope: dict[str, Any] = {
+            "ok": True,
+            "action": "created",
+            "id": article.id_readable,
+            "summary": article.summary,
+            "project": project_key,
+        }
+        if parent:
+            envelope["parent"] = parent
+        applied = [t.name for t in (article.tags or [])]
+        if applied:
+            envelope["tags"] = applied
+        return envelope
 
 
 class ArticleUpdateCommand(Command):
@@ -484,7 +529,16 @@ class ArticleUpdateCommand(Command):
                 "POST. The marker stays at body position 0 regardless of splice "
                 "direction. --content, --append, and --prepend are mutually "
                 "exclusive; --title (alias --summary) stays orthogonal and may "
-                "be combined with any one of them."
+                "be combined with any one of them. "
+                "Returns a parseable single-line ack: the last stdout line is "
+                "``ok: <ID> updated [<key>=<value> ...]`` listing each field "
+                "the operator just changed (title/summary). The structured "
+                "envelope also carries ``changed: [...]`` listing every "
+                "mutated key — including ``content`` for body-only updates, "
+                "which carries no tail-line token. Article body, full custom "
+                "field dumps, comments, and tags are dropped — run "
+                "/article show for the canonical post-write read. Pass "
+                "--quiet to suppress the detail block."
             ),
             examples=[
                 'kd /article update FB-A-1 --title "New Title"',
@@ -495,6 +549,7 @@ class ArticleUpdateCommand(Command):
             ],
             see_also=["/article show", "/article pull", "/article push"],
         )
+        self.display_hint = "mutation"
 
     def _register_options(self) -> None:
         self.register_option(
@@ -561,7 +616,23 @@ class ArticleUpdateCommand(Command):
             append=append,
             prepend=prepend,
         )
-        return _article_to_detail(article)
+        envelope: dict[str, Any] = {
+            "ok": True,
+            "action": "updated",
+            "id": article.id_readable,
+        }
+        changed: list[str] = []
+        if title:
+            envelope["summary"] = title
+            changed.append("summary")
+        # Body mutations (content / append / prepend) all surface as
+        # ``changed: ["content"]`` so structured consumers see a single
+        # signal regardless of which body op was used. The body itself is
+        # intentionally dropped — /article show is the post-write read.
+        if content is not None or append is not None or prepend is not None:
+            changed.append("content")
+        envelope["changed"] = changed
+        return envelope
 
 
 class ArticleDeleteCommand(Command):
@@ -573,9 +644,15 @@ class ArticleDeleteCommand(Command):
             "Delete an article",
             requires_client=True,
             usage="kd /article delete ARTICLE_ID",
+            long_description=(
+                "Returns a parseable single-line ack: the last stdout line is "
+                "``ok: <ID> deleted``. Pass --quiet to suppress the detail "
+                "block above the ack."
+            ),
             examples=["kd /article delete FB-A-1"],
             see_also=["/article list"],
         )
+        self.display_hint = "mutation"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -584,7 +661,7 @@ class ArticleDeleteCommand(Command):
             raise ValidationError("Usage: kd /article delete ARTICLE_ID")
         article_id = args[0]
         client.articles.delete(article_id)
-        return {"ok": True, "action": "delete", "article": article_id}
+        return {"ok": True, "action": "deleted", "id": article_id}
 
 
 # --- Comment Commands ---
@@ -630,12 +707,20 @@ class ArticleCommentAddCommand(Command):
             "Add a comment to an article",
             requires_client=True,
             usage='kd /article/comment add ARTICLE_ID "Text"',
+            long_description=(
+                "Returns a parseable single-line ack. The tail line is "
+                "``ok: <ARTICLE_ID> added comment_id=<id>``: the parent "
+                "article ID is the primary tail-line ID (``$2``), and the "
+                "new comment's internal ID is in ``comment_id=<id>``. "
+                "Pass --quiet to suppress the detail block."
+            ),
             examples=[
                 'kd /article/comment add FB-A-1 "Needs review"',
                 "kd /article/comment add FB-A-1 @note.md",
             ],
             see_also=["/article/comment list"],
         )
+        self.display_hint = "mutation"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -646,9 +731,11 @@ class ArticleCommentAddCommand(Command):
         text = resolve_text_input(" ".join(args[1:]))
         comment = client.articles.add_comment(article_id, text)
         return {
-            "id": comment.id,
+            "ok": True,
+            "action": "added",
+            "id": article_id,
+            "comment_id": comment.id,
             "author": comment.author.name if comment.author else "",
-            "text": comment.text,
         }
 
 
@@ -698,12 +785,23 @@ class ArticleAttachmentAddCommand(Command):
             "Add attachments to an article",
             requires_client=True,
             usage="kd /article/attachment add ARTICLE_ID FILE [FILE...]",
+            long_description=(
+                "Returns a parseable single-line ack: the last stdout line is "
+                "``ok: <ID> added attachments=<name1>,<name2>,...``. The "
+                "structured envelope carries ``attachments: [<name>, ...]`` "
+                "(scalar names — the source of the tail-line token) and "
+                "``applied: [{name, size, id}, ...]`` (per-file detail). "
+                "The shape is consistent for both single-file and "
+                "multi-file calls. Pass --quiet to suppress the detail "
+                "block above the ack."
+            ),
             examples=[
                 "kd /article/attachment add FB-A-1 diagram.png",
                 "kd /article/attachment add FB-A-1 log.txt report.pdf",
             ],
             see_also=["/article/attachment list"],
         )
+        self.display_hint = "mutation"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -713,7 +811,14 @@ class ArticleAttachmentAddCommand(Command):
         article_id = args[0]
         file_paths = [Path(p) for p in args[1:]]
         attachments = client.articles.add_attachments(article_id, file_paths)
-        return [_attachment_to_row(a) for a in attachments]
+        applied = [{"name": a.name, "size": a.size, "id": a.id} for a in attachments]
+        return {
+            "ok": True,
+            "action": "added",
+            "id": article_id,
+            "attachments": [a.name for a in attachments],
+            "applied": applied,
+        }
 
 
 class ArticleAttachmentShowCommand(Command):
@@ -794,9 +899,18 @@ class ArticleAttachmentDeleteCommand(Command):
             "Delete an article attachment",
             requires_client=True,
             usage="kd /article/attachment delete ARTICLE_ID ATTACHMENT_ID",
+            long_description=(
+                "Returns a parseable single-line ack: the last stdout line is "
+                "``ok: <ARTICLE_ID> deleted attachment=<ATTACHMENT_ID>``. "
+                "The parent article ID is the primary tail-line ID (``$2``); "
+                "the removed attachment's internal ID is in "
+                "``attachment=<id>``. Pass --quiet to suppress the detail "
+                "block above the ack."
+            ),
             examples=["kd /article/attachment delete FB-A-1 att-1"],
             see_also=["/article/attachment list"],
         )
+        self.display_hint = "mutation"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -804,7 +918,7 @@ class ArticleAttachmentDeleteCommand(Command):
         if len(args) < 2:
             raise ValidationError("Usage: kd /article/attachment delete ARTICLE_ID ATTACHMENT_ID")
         client.articles.delete_attachment(args[0], args[1])
-        return {"ok": True, "action": "delete", "article": args[0], "attachment": args[1]}
+        return {"ok": True, "action": "deleted", "id": args[0], "attachment": args[1]}
 
 
 # --- Move Command ---
@@ -819,13 +933,21 @@ class ArticleMoveCommand(Command):
             "Move an article to a new parent",
             requires_client=True,
             usage="kd /article move ARTICLE_ID --parent PARENT_ID",
-            long_description="Use --parent none to move an article to project root.",
+            long_description=(
+                "Use --parent none to move an article to project root. "
+                "Returns a parseable single-line ack: the last stdout line "
+                "is ``ok: <ID> moved parent=<PARENT_ID>`` (or "
+                "``ok: <ID> moved parent=root`` when reparented to project "
+                "root). Pass --quiet to suppress the detail block above "
+                "the ack."
+            ),
             examples=[
                 "kd /article move FB-A-3 --parent FB-A-1",
                 "kd /article move FB-A-3 --parent none",
             ],
             see_also=["/article tree", "/article children"],
         )
+        self.display_hint = "mutation"
 
     def _register_options(self) -> None:
         self.register_option(
@@ -847,7 +969,12 @@ class ArticleMoveCommand(Command):
         article_id = args[0]
         parent = None if parent_value.lower() == "none" else parent_value
         article = client.articles.move(article_id, parent=parent)
-        return _article_to_detail(article)
+        return {
+            "ok": True,
+            "action": "moved",
+            "id": article.id_readable,
+            "parent": _parent_label(article) if article.parent_article else "root",
+        }
 
 
 # --- Tree Command ---