kd-cli 2.1.4__tar.gz → 2.1.5__tar.gz

{kd_cli-2.1.4/kd_cli.egg-info → kd_cli-2.1.5}/PKG-INFO

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

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/cli/core/command_base.py

@@ -114,8 +114,6 @@ class Command(ABC):
                 if opt.aliases:
                     alias_str = ", ".join(f"--{a}" for a in opt.aliases)
                     flag += f" (alias: {alias_str})"
-                if opt.choices:
-                    flag += f"  ({', '.join(opt.choices)})"
                 if opt.help_text:
                     flag += f"    {opt.help_text}"
                 lines.append(flag)

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/cli/core/option_registry.py

@@ -253,7 +253,7 @@ OUTPUT_OPTIONS: list[OptionDeclaration] = [
         layer=OptionLayer.OUTPUT,
         type=str,
         choices=["table", "json", "yaml", "md"],
-        help_text="Output format (table, json, yaml, md)",
+        help_text="Output format: table|json|yaml|md (default: table)",
     ),
     OptionDeclaration(
         name="fields",

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/cli/main.py

@@ -503,8 +503,6 @@ def _show_reference(
             flag += f"/-{decl.short_name}"
         if decl.type is not bool:
             flag += f" {decl.name.upper()}"
-        if decl.choices:
-            flag += f" ({'/'.join(decl.choices)})"
         parts.append(flag)
     print(f"Global options: {', '.join(parts)}")
     print()
@@ -539,8 +537,6 @@ def _print_namespace_reference(ns: Namespace, depth: int = 0) -> None:
             flag = f"--{opt.name}"
             if opt.short_name:
                 flag += f"/-{opt.short_name}"
-            if opt.choices:
-                flag += f" ({', '.join(opt.choices)})"
             line = f"      {flag}"
             if opt.help_text:
                 line += f"  {opt.help_text}"
@@ -621,8 +617,5 @@ def _show_discovery(namespace: Namespace, *, file: Any = None) -> None:
             flag = f"--{decl.name}"
             if decl.short_name:
                 flag += f", -{decl.short_name}"
-            extra = ""
-            if decl.choices:
-                extra = f" ({', '.join(decl.choices)})"
-            print(f"  {flag:<16}{decl.help_text}{extra}", file=file)
+            print(f"  {flag:<16}{decl.help_text}", file=file)
         print(file=file)

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/cli/namespaces/primer/__init__.py

@@ -10,7 +10,12 @@ from typing import Any
 
 from kd.cli.core.command_base import Command, CommandResult
 from kd.cli.core.namespaces import Namespace
-from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, ResolvedOptions
+from kd.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+    project_option,
+)
 from kd.cli.input import resolve_text_input
 from kd.exceptions import ValidationError
 from kd.primer import (
@@ -25,6 +30,26 @@ from kd.primer import (
 )
 
 
+def _assert_workspace_project(command: Command, options: ResolvedOptions) -> None:
+    """Enforce the ``--project`` assertion on workspace-scoped primer commands.
+
+    The primer lives in ``.kd/primer.yaml`` and has no project dimension.
+    ``--project`` is accepted as an assertion of which workspace's primer the
+    caller thinks it's editing: matches ``default_project`` → silent no-op;
+    mismatches → raise so an agent running from the wrong workspace fails loud.
+    """
+    asserted = options.command.get("project")
+    if not asserted:
+        return
+    current = command.config.default_project
+    if current and asserted != current:
+        raise ValidationError(
+            f"Primer is workspace-scoped. --project={asserted} does not match "
+            f"this workspace's default_project={current}. To edit {asserted}'s "
+            f"primer, run from that workspace."
+        )
+
+
 # ---------------------------------------------------------------------------
 # /primer show (root default)
 # ---------------------------------------------------------------------------
@@ -46,19 +71,16 @@ class PrimerShowCommand(Command):
             ],
             see_also=["/primer/note list", "/primer/article list"],
         )
+        self.display_hint = "primer_show"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
         data = load_primer()
-        if not data.notes and not data.articles:
-            return None
-        result: dict[str, Any] = {}
-        if data.notes:
-            result["notes"] = [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)]
-        if data.articles:
-            result["articles"] = [{"id": a.id, "summary": a.summary or ""} for a in data.articles]
-        return result
+        return {
+            "notes": [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)],
+            "articles": [{"id": a.id, "summary": a.summary or ""} for a in data.articles],
+        }
 
 
 # ---------------------------------------------------------------------------
@@ -93,6 +115,7 @@ class PrimerNoteAddCommand(Command):
         super().__init__(
             "add",
             "Add a primer note",
+            requires_config=True,
             usage="kd /primer/note add TEXT",
             long_description="Appends a note to the project primer.  TEXT can be inline, "
             "@file to read from a file, or - to read from stdin.",
@@ -103,9 +126,13 @@ class PrimerNoteAddCommand(Command):
             see_also=["/primer/note list", "/primer/note remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/note add TEXT")
         text = resolve_text_input(" ".join(args))
@@ -122,6 +149,7 @@ class PrimerNoteRemoveCommand(Command):
         super().__init__(
             "remove",
             "Remove a primer note by index or all notes",
+            requires_config=True,
             usage="kd /primer/note remove INDEX | --all",
             long_description="Removes the note at the given 1-based index, or all notes "
             "if --all is passed.  Use '/primer/note list' to see current indices.",
@@ -142,10 +170,12 @@ class PrimerNoteRemoveCommand(Command):
                 help_text="Remove all notes",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if options.command.get("all"):
             count = clear_notes()
             return {"ok": True, "action": "clear", "removed": count}
@@ -166,6 +196,7 @@ class PrimerNoteUpdateCommand(Command):
         super().__init__(
             "update",
             "Replace a primer note by index",
+            requires_config=True,
             usage="kd /primer/note update INDEX TEXT",
             long_description="Replaces the note at the given 1-based index with new text.  "
             "TEXT can be inline, @file to read from a file, or - to read from stdin.  "
@@ -177,9 +208,13 @@ class PrimerNoteUpdateCommand(Command):
             see_also=["/primer/note list", "/primer/note remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/note update INDEX TEXT")
         try:
@@ -227,6 +262,7 @@ class PrimerArticleAddCommand(Command):
         super().__init__(
             "add",
             "Pin an article to the primer",
+            requires_config=True,
             usage="kd /primer/article add ARTICLE_ID [--summary S]",
             long_description="Adds a YouTrack article reference to the project primer.  "
             "Use --summary to store a description alongside the ID.",
@@ -246,10 +282,12 @@ class PrimerArticleAddCommand(Command):
                 help_text="Description to store with the article reference",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/article add ARTICLE_ID")
         article_id = args[0]
@@ -268,6 +306,7 @@ class PrimerArticleRemoveCommand(Command):
         super().__init__(
             "remove",
             "Unpin an article or all articles",
+            requires_config=True,
             usage="kd /primer/article remove ARTICLE_ID | --all",
             long_description="Removes the article with the given ID from the primer, "
             "or all pinned articles if --all is passed.",
@@ -288,10 +327,12 @@ class PrimerArticleRemoveCommand(Command):
                 help_text="Remove all pinned articles",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if options.command.get("all"):
             count = clear_articles()
             return {"ok": True, "action": "clear", "removed": count}

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/cli/output.py

@@ -1,13 +1,14 @@
 """Output formatting.
 
 Renders command results in multiple formats:
-- table: human-readable tabular output (default for TTY)
+- table: human-readable tabular output (unconditional default)
 - json: JSON output for piping to jq
 - yaml: YAML output
 - md: Markdown table
 
-Auto-detects TTY vs pipe: uses table format for interactive terminals,
-falls back to json when piped.
+Default is ``table`` regardless of stdout context; TTY state does not
+influence format (ADR-006 — TTY detection stays config-first). Consumers
+that want JSON or YAML pass ``-o json`` / ``-o yaml`` explicitly.
 
 Value normalization runs before serialization: epoch-ms timestamps become
 ISO 8601, enums become their ``.value``, and nested collections render
@@ -17,7 +18,6 @@ cleanly in every format.
 from __future__ import annotations
 
 import json
-import sys
 from datetime import datetime, timezone
 from typing import Any
 
@@ -75,7 +75,8 @@ class OutputFormatter:
 
         Args:
             data: Structured data from a command.
-            fmt: Output format. Auto-detected if None (TTY->table, pipe->json).
+            fmt: Output format. Defaults to ``"table"`` when None; TTY state
+                does not influence the default (ADR-006).
             fields: Comma-separated field names to include.
             display_hint: Rendering hint from the command (e.g. ``"tree"``).
         """
@@ -87,12 +88,28 @@ class OutputFormatter:
         normalized: list[dict[str, Any]] | dict[str, Any] = self._normalize(data)
 
         if fmt is None:
-            fmt = "table" if sys.stdout.isatty() else "json"
+            fmt = "table"
 
         # Tree display: table/md render as pretty tree, json/yaml serialize structure.
         if display_hint == "tree" and isinstance(normalized, dict) and fmt in ("table", "md"):
             return self._render_tree_display(normalized)
 
+        # Primer show: table/md formats drop empty sections so a notes-only
+        # primer renders without an empty "articles" row. When both sections
+        # are empty, show a populate hint. json/yaml pass through unchanged.
+        if (
+            display_hint == "primer_show"
+            and fmt in ("table", "md")
+            and isinstance(normalized, dict)
+        ):
+            if not normalized.get("notes") and not normalized.get("articles"):
+                return (
+                    "Primer is empty.\n"
+                    '  Populate with: kd /primer/note add "<text>"\n'
+                    "                 kd /primer/article add <ARTICLE_ID>"
+                )
+            normalized = {k: v for k, v in normalized.items() if v}
+
         field_list = [f.strip() for f in fields.split(",")] if fields else None
 
         match fmt:

{kd_cli-2.1.4 → kd_cli-2.1.5}/kd/resources/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.1.5] — 2026-04-17
+
+Milestone 005 — CLI friction audit, session S1. Four first-time-user surface fixes on the `--help` / `--output` axis.
+
+### Fixed
+- `--help`, `--reference`, and per-command help now render the `--output` choices list exactly once. The literal help text carries the list and the default (`Output format: table|json|yaml|md (default: table)`); four renderer sites that previously auto-appended `(table, json, yaml, md)` a second time stopped doing so (KDCLI-73).
+- `kd` no longer flips the default output format to JSON when stdout is a pipe. `table` is the unconditional default across TTY, pipes, and subprocess contexts, per [ADR-006](../../docs/design/ADR-006-tty-detection-config-first.md). Consumers wanting JSON or YAML pass `-o json` / `-o yaml` explicitly (KDCLI-74).
+- `kd /primer show` on an empty primer now prints a populate hint in `table` and `md` output, instead of rendering zero bytes. JSON and YAML continue to return the canonical empty container `{"notes": [], "articles": []}` (KDCLI-76).
+- `kd /primer/note add`, `kd /primer/article add`, and their sibling `remove` / `update` commands accept `--project/-p` as a workspace assertion. A match against the active connection's `default_project` is a silent no-op; a mismatch raises a `ValidationError` naming both the asserted and resolved keys so an agent running from the wrong workspace fails loud instead of silently writing to the wrong primer (KDCLI-70).
+
 ## [2.1.4] — 2026-04-15
 
 ### Fixed

{kd_cli-2.1.4 → kd_cli-2.1.5/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.1.4 → kd_cli-2.1.5}/pyproject.toml

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