kd-cli 2.9.0__tar.gz → 2.10.0__tar.gz

{kd_cli-2.9.0/kd_cli.egg-info → kd_cli-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.9.0
+Version: 2.10.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT
@@ -167,7 +167,7 @@ pytest tests/ -v --tb=short
 
 ruff format kd/ tests/
 ruff check --fix kd/ tests/
-mypy kd/
+uv run mypy
 ```
 
 ---

{kd_cli-2.9.0 → kd_cli-2.10.0}/README.md

@@ -127,7 +127,7 @@ pytest tests/ -v --tb=short
 
 ruff format kd/ tests/
 ruff check --fix kd/ tests/
-mypy kd/
+uv run mypy
 ```
 
 ---

{kd_cli-2.9.0 → kd_cli-2.10.0}/kd/api/http.py

@@ -23,6 +23,7 @@ from kd.exceptions import (
     ConflictError,
     NotFoundError,
     PermissionDeniedError,
+    ValidationError,
     enrich_error,
 )
 
@@ -30,6 +31,22 @@ _RETRYABLE_STATUSES = {429, 502, 503}
 _MAX_RETRIES = 3
 
 
+def _refuse_control_characters(path: str) -> None:
+    """Refuse a path that no URL can carry, before it is sent.
+
+    The refused set is exactly what httpx rejects as non-printable ASCII:
+    C0 controls and DEL. The user values kd puts in a path are entity ids,
+    one per segment, so the error names the segment that carries the
+    character, escaped onto one line.
+    """
+    for segment in path.split("/"):
+        if any(c < " " or c == "\x7f" for c in segment):
+            raise ValidationError(
+                f"Invalid id {segment!r}: it contains a control character "
+                "(line break, tab or similar). Pass one id per argument."
+            )
+
+
 class HttpClient:
     """Low-level HTTP client with auth, retry, and error mapping."""
 
@@ -116,6 +133,7 @@ class HttpClient:
 
     def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         """Execute request with retry and error mapping."""
+        _refuse_control_characters(path)
         d = self._debug
 
         # Log request details before first attempt

{kd_cli-2.9.0 → kd_cli-2.10.0}/kd/article_marker.py

@@ -18,6 +18,9 @@ Grammar (informal):
 Rules (pinned down by ``tests/test_article_marker.py``):
 
 - Open and close lines must be exact (``<!-- kd-meta`` / ``-->``).
+- Only a marker that opens on the first non-blank line counts; a
+  marker-open line after body content is body. A second marker block
+  directly below the top one (only blank lines between) is an error.
 - Keys match ``[a-z][a-z0-9-]*``; uppercase and underscores are
   rejected to keep the grammar ASCII-boring.
 - Unknown keys are preserved verbatim on round-trip — the load-bearing
@@ -49,8 +52,9 @@ Legacy marker synonym (transitional, proposal 28 / M003 §S4):
     upstream population of ``ytctl-meta`` is empty. No auto-disable,
     no timer — a deliberate future milestone.
 
-Stdlib only; no third-party deps. The push workflow (in
-``kd.client.ArticleOperations.push``) and its tests are the only
+Stdlib only; no third-party deps. The push workflow
+(``kd.client.ArticleOperations.push``), ``/article update``
+(``kd.client.ArticleOperations.update``) and their tests are the only
 importers.
 """
 
@@ -248,13 +252,17 @@ def parse_content(text: str) -> ParsedFile:
     if close_idx is None:
         raise MarkerError("marker block not closed (expected '-->' on its own line)")
 
-    # Refuse a second marker anywhere later in the file — native or
-    # legacy. Prevents a stray ``<!-- ytctl-meta`` further down from
-    # being silently accepted as body content on a file that also
-    # carries a native header at the top.
-    for k in range(close_idx + 1, len(lines)):
-        if lines[k] in _RECOGNIZED_OPENS:
-            raise MarkerError("file contains more than one kd-meta block")
+    # A second marker block with only blank lines above it would become
+    # the identity once the top block is stripped (``/article update
+    # --content``) or edited away, so it is refused. A marker-open line
+    # after body content stays body. This check only refuses, so it
+    # compares leniently (whitespace, stray CR, BOM): an editor or
+    # encoding round trip can turn a near-exact open into an exact one.
+    k = close_idx + 1
+    while k < len(lines) and _loose(lines[k]) == "":
+        k += 1
+    if k < len(lines) and _loose(lines[k]) in _RECOGNIZED_OPENS:
+        raise MarkerError("a second kd-meta block directly follows the top marker; keep one")
 
     # Parse key:value lines between open and close.
     marker = ArticleMarker()
@@ -291,6 +299,12 @@ def parse_content(text: str) -> ParsedFile:
     )
 
 
+def _loose(line: str) -> str:
+    """Normalize a line for the stacked-block refusal only: drop BOMs and
+    surrounding whitespace. Never used to detect the top marker."""
+    return line.replace("\ufeff", "").strip()
+
+
 def _join_body(lines: list[str], trailing_newline: bool) -> str:
     """Join body lines with ``\\n``, restoring the final terminator if any."""
     if not lines:

{kd_cli-2.9.0 → kd_cli-2.10.0}/kd/cli/core/command_base.py

@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
 from kd.cli.core.option_registry import OptionDeclaration, ResolvedOptions
+from kd.exceptions import ValidationError
 
 if TYPE_CHECKING:
     from kd.config import ResolvedConfig
@@ -20,6 +21,18 @@ if TYPE_CHECKING:
 CommandResult = list[dict[str, Any]] | dict[str, Any] | str | None
 
 
+def reject_extra_args(args: list[str], allowed: int, usage: str) -> None:
+    """Refuse positionals beyond the first *allowed* ones.
+
+    For commands whose positional count is fixed and whose effect is
+    outward or irreversible: a word left over by the parser (for example
+    ``off`` after a boolean option) must not be dropped silently. The
+    error names the first extra word and the command's usage line.
+    """
+    if len(args) > allowed:
+        raise ValidationError(f"Unexpected argument '{args[allowed]}'. Usage: {usage}")
+
+
 class Command(ABC):
     """Base class for all CLI commands."""
 
@@ -31,6 +44,7 @@ class Command(ABC):
         requires_client: bool = False,
         requires_config: bool = False,
         usage: str = "",
+        joins_text: bool = False,
         long_description: str = "",
         examples: list[str] | None = None,
         see_also: list[str] | None = None,
@@ -40,6 +54,10 @@ class Command(ABC):
         self.requires_client = requires_client
         self.requires_config = requires_config
         self.usage = usage
+        # The command joins its arguments into one text (a summary, comment,
+        # note, name or query). The parser then refuses a bare switch that is
+        # directly followed by a word when an argument comes before it.
+        self.joins_text = joins_text
         self.long_description = long_description
         self.examples: list[str] = examples or []
         self.see_also: list[str] = see_also or []

kd_cli-2.10.0/kd/cli/core/command_parser.py

@@ -0,0 +1,348 @@
+"""Two-phase command parser.
+
+Phase 1 (parse_command): Resolve namespace + command from positional
+args and tokenize options into a raw dict.  No validation.
+
+Phase 2 (resolve_options): Validate types, choices, and required
+options, producing the final ResolvedOptions.
+
+The convenience method ``parse()`` runs both phases in one call.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from kd.cli.core.command_base import Command
+from kd.cli.core.namespaces import Namespace, NamespaceRegistry
+from kd.cli.core.option_registry import (
+    OUTPUT_OPTIONS,
+    OptionError,
+    OptionRegistry,
+    ResolvedOptions,
+    is_spaced_bool_word,
+)
+
+
+class ParseError(Exception):
+    """Raised when command parsing fails."""
+
+
+@dataclass
+class UnresolvedCommand:
+    """Phase-1 result: command identified, options tokenized but not validated."""
+
+    namespace: Namespace
+    command_name: str
+    command: Command | None  # None if command not found
+    args: list[str] = field(default_factory=list)
+    raw_options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParsedCommand:
+    """Result of parsing a command line."""
+
+    namespace: Namespace
+    command_name: str
+    command: Command | None  # None if command not found
+    args: list[str] = field(default_factory=list)
+    options: ResolvedOptions = field(default_factory=ResolvedOptions)
+    raw_options: dict[str, Any] = field(default_factory=dict)
+
+
+def _is_option_token(token: str) -> bool:
+    """``-x`` / ``--name`` style token; a lone ``-`` is a value (stdin convention)."""
+    return token.startswith("-") and len(token) > 1
+
+
+class CommandParser:
+    """Parses argv into a resolved command with options."""
+
+    def __init__(self, registry: NamespaceRegistry) -> None:
+        self._registry = registry
+
+    def parse_command(self, argv: list[str]) -> UnresolvedCommand:
+        """Phase 1: resolve command and tokenize options.  No validation.
+
+        1. Split argv knowing only the output options, and resolve the
+           namespace + command from the positionals
+        2. Split argv again with that command's option registry, so each
+           option takes exactly the tokens it declares and positionals keep
+           the order they were typed in
+        3. Parse the option tokens into a raw dict
+
+        The command's options are not known until its name is read. The two
+        splits resolve different commands only when a switch of the command
+        sits before the command name and the first split let it take a word
+        that is not ``true``/``false``; that form is refused with a message
+        naming the form that works. A switch directly before a namespace or
+        command word swallows that word in the first split too, so the
+        command is never found and the usual unknown-command path reports it.
+
+        On a command that joins its arguments into one text
+        (``Command.joins_text``), a bare switch directly followed by a word
+        is refused when any argument, the id included, comes before the
+        switch: the word would otherwise become text or the target. ``--``,
+        an option between the switch and the word, the ``=`` form and a
+        ``true``/``false`` the switch takes all break the adjacency.
+        """
+        first_positionals, first_tokens, _ = self._split_args(
+            argv, self._build_option_registry(None)
+        )
+        namespace, command_name, _ = self._registry.resolve(first_positionals)
+        command = namespace.get_command(command_name) if command_name else None
+
+        option_reg = self._build_option_registry(command)
+        positionals, option_tokens, after_switch = self._split_args(argv, option_reg)
+        second_namespace, second_name, remaining = self._registry.resolve(positionals)
+        if second_namespace is not namespace or second_name != command_name:
+            raise ParseError(
+                self._misplaced_switch_message(
+                    first_tokens, option_tokens, namespace, command_name, option_reg
+                )
+            )
+        if command is not None and command.joins_text:
+            self._reject_switch_between_args(
+                positionals, len(positionals) - len(remaining), after_switch, command, option_reg
+            )
+
+        raw_options = self._parse_option_tokens(option_tokens, option_reg)
+
+        return UnresolvedCommand(
+            namespace=namespace,
+            command_name=command_name,
+            command=command,
+            args=remaining,
+            raw_options=raw_options,
+        )
+
+    def resolve_options(self, unresolved: UnresolvedCommand) -> ParsedCommand:
+        """Phase 2: validate and resolve options.
+
+        Builds the option registry, validates types/choices/required,
+        and returns a fully resolved ``ParsedCommand``.
+        """
+        option_reg = self._build_option_registry(unresolved.command)
+        try:
+            resolved = option_reg.resolve(unresolved.raw_options)
+        except OptionError as e:
+            raise ParseError(str(e)) from e
+
+        return ParsedCommand(
+            namespace=unresolved.namespace,
+            command_name=unresolved.command_name,
+            command=unresolved.command,
+            args=unresolved.args,
+            options=resolved,
+            raw_options=unresolved.raw_options,
+        )
+
+    def parse(self, argv: list[str]) -> ParsedCommand:
+        """Full parse: resolve command + validate options in one call.
+
+        Convenience wrapper equivalent to ``parse_command()`` then
+        ``resolve_options()``.
+        """
+        return self.resolve_options(self.parse_command(argv))
+
+    def _split_args(
+        self, argv: list[str], registry: OptionRegistry
+    ) -> tuple[list[str], list[str], list[tuple[int, str]]]:
+        """Split argv into positional args, option tokens, and switch-adjacent words.
+
+        Supports GNU-style mixed placement: options can appear anywhere
+        in the command line (before, between, or after positionals).
+
+        Slash-path expansion: the first positional token starting with
+        ``/`` is expanded into namespace segments (``/a/b`` → ``a``, ``b``).
+        Once any positional has been emitted, later ``/``-prefixed tokens
+        are treated as literal arguments (file paths, etc.).
+        A bare ``/`` expands to nothing (root namespace).
+
+        The ``--`` separator ends option parsing: everything after it
+        is positional.
+
+        Which token an option takes comes from *registry*: a boolean
+        option takes the next token only when it is ``true`` or ``false``
+        (any case); any other option, known or not, takes the next token
+        unless it is ``--`` or another option. A lone ``-`` is a value
+        (stdin convention). An unknown option is reported later by
+        ``_parse_option_tokens`` or phase 2.
+
+        The third value lists each positional that directly follows a bare
+        switch (a boolean option without ``=`` that took no token), as its
+        index in the positionals and the switch token. A word after ``--``
+        or after another option is never listed.
+        """
+        positionals: list[str] = []
+        option_tokens: list[str] = []
+        after_switch: list[tuple[int, str]] = []
+
+        i = 0
+        while i < len(argv):
+            token = argv[i]
+
+            # -- separator: everything after is positional
+            if token == "--":
+                positionals.extend(argv[i + 1 :])
+                break
+
+            if _is_option_token(token):
+                option_tokens.append(token)
+                if (
+                    "=" not in token
+                    and i + 1 < len(argv)
+                    and self._takes_next(token, argv[i + 1], registry)
+                ):
+                    option_tokens.append(argv[i + 1])
+                    i += 2
+                    continue
+                # A bare switch directly followed by a word (not an option, ``--`` included).
+                if (
+                    "=" not in token
+                    and i + 1 < len(argv)
+                    and not _is_option_token(argv[i + 1])
+                    and registry.is_boolean_flag(token.lstrip("-"))
+                ):
+                    after_switch.append((len(positionals), token))
+                i += 1
+            else:
+                # Positional token — expand slash path only for the first one
+                if not positionals and token.startswith("/"):
+                    segments = [s for s in token.split("/") if s]
+                    positionals.extend(segments)
+                else:
+                    positionals.append(token)
+                i += 1
+
+        return positionals, option_tokens, after_switch
+
+    @staticmethod
+    def _reject_switch_between_args(
+        positionals: list[str],
+        offset: int,
+        after_switch: list[tuple[int, str]],
+        command: Command,
+        registry: OptionRegistry,
+    ) -> None:
+        """Refuse a word right after a bare switch when an argument precedes it.
+
+        *offset* is the number of namespace and command tokens at the front
+        of *positionals*, so ``index - offset`` is the word's place in the
+        command's arguments; anything past the first has an argument before
+        the switch.
+        """
+        for index, switch in after_switch:
+            if index - offset > 0:
+                name = switch.lstrip("-")
+                canonical = registry.resolve_name(name) or name
+                raise ParseError(
+                    f"Unexpected argument '{positionals[index]}' after --{canonical}: "
+                    f"a switch takes no word after it. Put --{canonical} after the "
+                    f"last argument, or write --{canonical}=false. Usage: {command.usage}"
+                )
+
+    @staticmethod
+    def _takes_next(token: str, next_token: str, registry: OptionRegistry) -> bool:
+        """Whether option *token* takes *next_token* as its value."""
+        if registry.is_boolean_flag(token.lstrip("-")):
+            return is_spaced_bool_word(next_token)
+        return next_token != "--" and not _is_option_token(next_token)
+
+    def _build_option_registry(self, command: Command | None) -> OptionRegistry:
+        """Build option registry from command declarations + standard OUTPUT options."""
+        registry = OptionRegistry()
+        registry.register_all(OUTPUT_OPTIONS)
+        if command:
+            registry.register_all(command.get_options())
+        return registry
+
+    def _parse_option_tokens(self, tokens: list[str], registry: OptionRegistry) -> dict[str, Any]:
+        """Parse option tokens into a raw name->value dict.
+
+        Handles: --key value, --key=value, -k value, -k=value, and boolean
+        options bare or followed by their value. ``_split_args`` only places
+        a non-option token right after the option that takes it, so a
+        following non-option token is always that option's value.
+        """
+        raw: dict[str, Any] = {}
+        i = 0
+
+        while i < len(tokens):
+            token = tokens[i]
+
+            if "=" in token:
+                # --key=value or -k=value
+                name_part, value = token.split("=", 1)
+                name = name_part.lstrip("-")
+                canonical = registry.resolve_name(name) or name
+                self._set_option(raw, canonical, value, registry)
+                i += 1
+                continue
+
+            name = token.lstrip("-")
+            canonical = registry.resolve_name(name) or name
+            has_value = i + 1 < len(tokens) and not _is_option_token(tokens[i + 1])
+
+            if registry.is_boolean_flag(name):
+                # Bare boolean option means true; a value was paired by _split_args.
+                if has_value:
+                    self._set_option(raw, canonical, tokens[i + 1], registry)
+                    i += 2
+                else:
+                    raw[canonical] = True
+                    i += 1
+                continue
+
+            if has_value:
+                self._set_option(raw, canonical, tokens[i + 1], registry)
+                i += 2
+            elif registry.get_declaration(name) is not None:
+                raise ParseError(f"Option --{canonical} requires a value")
+            else:
+                raise ParseError(f"Unknown option: --{name}")
+
+        return raw
+
+    @staticmethod
+    def _misplaced_switch_message(
+        first_tokens: list[str],
+        second_tokens: list[str],
+        namespace: Namespace,
+        command_name: str,
+        registry: OptionRegistry,
+    ) -> str:
+        """Name the switch written before its command name, and the working form.
+
+        The two splits list the same option tokens up to the word the first
+        split let an option take and the second did not; that option is the
+        switch. Both lists come from ``_split_args``, which places a taken
+        word right after its option.
+        """
+        index = next(
+            (
+                i
+                for i in range(len(first_tokens))
+                if i >= len(second_tokens) or first_tokens[i] != second_tokens[i]
+            ),
+            len(first_tokens),
+        )
+        switch = first_tokens[index - 1] if index > 0 else ""
+        assert _is_option_token(switch), "splits diverged without an option taking a word"
+        name = switch.lstrip("-")
+        canonical = registry.resolve_name(name) or name
+        display = f"/{namespace.path} {command_name}" if namespace.path else command_name
+        return (
+            f"Option --{canonical} belongs to {display}; put it after the "
+            f"command name: kd {display} ... --{canonical}"
+        )
+
+    @staticmethod
+    def _set_option(raw: dict[str, Any], name: str, value: str, registry: OptionRegistry) -> None:
+        """Set an option value, appending to a list for repeatable options."""
+        if registry.is_list_option(name):
+            raw.setdefault(name, []).append(value)
+        else:
+            raw[name] = value

{kd_cli-2.9.0 → kd_cli-2.10.0}/kd/cli/core/option_registry.py

@@ -15,6 +15,19 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
 
+# Words a boolean option accepts as its value. The ``=`` form
+# (``--flag=no``) reads all six. The space form (``--flag false``) reads
+# only the two documented literals: there the next token may be a
+# positional instead (an INDEX of ``1``, prose that starts with "no").
+_BOOL_TRUE_WORDS = ("true", "1", "yes")
+_BOOL_FALSE_WORDS = ("false", "0", "no")
+_SPACED_BOOL_WORDS = ("true", "false")
+
+
+def is_spaced_bool_word(token: str) -> bool:
+    """Whether a boolean option takes *token*, the next argv token, as its value."""
+    return token.lower() in _SPACED_BOOL_WORDS
+
 
 class OptionLayer(Enum):
     """Option layers — separates options by concern."""
@@ -92,7 +105,7 @@ class OptionRegistry:
         return self._short_names.get(name) or self._aliases.get(name)
 
     def is_boolean_flag(self, name: str) -> bool:
-        """Check if an option is a boolean flag (no value expected)."""
+        """Check if an option is boolean: true when bare, or set by a following true/false."""
         decl = self.get_declaration(name)
         return decl is not None and decl.type is bool
 
@@ -144,9 +157,9 @@ class OptionRegistry:
             if isinstance(value, bool):
                 return value
             if isinstance(value, str):
-                if value.lower() in ("true", "1", "yes"):
+                if value.lower() in _BOOL_TRUE_WORDS:
                     return True
-                if value.lower() in ("false", "0", "no"):
+                if value.lower() in _BOOL_FALSE_WORDS:
                     return False
             raise OptionError(f"Invalid boolean value for --{decl.name}: {value}")
 
@@ -249,9 +262,11 @@ def state_option(
 # 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.
+# but it only affects writes: a write on the write-output contract
+# (``display_hint="mutation"``) prints only its ``ok:`` line, and a write
+# outside it (``display_hint="write"``) has none, so it prints nothing. On
+# reads and structured output modes (``-o yaml`` / ``-o json``),
+# ``--quiet`` is silently no-op.
 OUTPUT_OPTIONS: list[OptionDeclaration] = [
     OptionDeclaration(
         name="output",
@@ -274,8 +289,9 @@ OUTPUT_OPTIONS: list[OptionDeclaration] = [
         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)."
+            "Print only the ok: line of a write; a write without one (the /primer "
+            "writes, kd init, /system/config set, /system restore, /tag add) prints "
+            "nothing. No-op on reads and structured modes (-o yaml/json)."
         ),
     ),
 ]