kd-cli 2.6.3__tar.gz → 2.6.5__tar.gz

{kd_cli-2.6.3/kd_cli.egg-info → kd_cli-2.6.5}/PKG-INFO

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

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/api/youtrack.py

@@ -20,7 +20,7 @@ import re
 from typing import Any
 
 from kd.api.http import HttpClient
-from kd.exceptions import KdError
+from kd.exceptions import FieldDiscoveryError, KdError
 from kd.models import (
     AssistResponse,
     Attachment,
@@ -257,13 +257,15 @@ class YouTrackAPI:
         admin_fields: list[dict[str, Any]] = admin.get("customFields") or []
         if admin_fields:
             return admin_fields
-        raise KdError(
+        raise FieldDiscoveryError(
             f"No custom fields discovered for project '{project_id}'.",
             suggestion=(
                 "Either the project has no issues to sample from, or the "
                 "active token lacks Read Project Full on this project. "
                 "Create one issue (any contributor token works), or use a "
-                "token with project-administration rights. See KDCLI-A-22."
+                "token with project-administration rights. Or omit "
+                "--type / --priority / --state to create a minimal first "
+                "issue, then update it via `/issue update`. See KDCLI-A-22."
             ),
         )
 

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/cli/input.py

@@ -25,9 +25,23 @@ def resolve_text_input(value: str | None) -> str | None:
     if not value:
         return value
     if value == "-":
-        return sys.stdin.read()
+        try:
+            return sys.stdin.read()
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f"Stdin input could not be decoded as UTF-8: {e.reason}",
+                suggestion="Ensure the upstream shell pipes UTF-8 bytes "
+                "(heredoc, pipe, or redirected file).",
+            ) from e
     if value == "@-":
-        text = sys.stdin.read()
+        try:
+            text = sys.stdin.read()
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f"Stdin input could not be decoded as UTF-8: {e.reason}",
+                suggestion="Ensure the upstream shell pipes UTF-8 bytes "
+                "(heredoc, pipe, or redirected file).",
+            ) from e
         if not text:
             raise ValidationError("No input received from stdin")
         return text
@@ -35,7 +49,13 @@ def resolve_text_input(value: str | None) -> str | None:
         file_path = Path(value[1:])
         if not file_path.is_file():
             raise ValidationError(f"File not found: {file_path}")
-        text = file_path.read_text(encoding="utf-8")
+        try:
+            text = file_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f"File {file_path} could not be decoded as UTF-8: {e.reason}",
+                suggestion="Save the file as UTF-8 (without a BOM) and retry.",
+            ) from e
         if not text:
             raise ValidationError(f"File is empty: {file_path}")
         return text

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/cli/main.py

@@ -142,17 +142,24 @@ def _print_error(error: KdError) -> None:
 
 
 def _configure_windows_stdio() -> None:
-    """Force UTF-8 on stdout/stderr when running on Windows.
-
-    No-op on POSIX. Errors during reconfigure are swallowed; the wrapper's
-    UnicodeEncodeError handler is the defensive backstop for the rare
-    embedded-interpreter case where reconfigure is unavailable.
+    """Force UTF-8 on stdin/stdout/stderr when running on Windows.
+
+    No-op on POSIX. Stdout/stderr use ``errors="replace"`` so a single
+    corrupted byte never aborts a whole command's output. Stdin uses
+    ``errors="strict"`` so invalid bytes raise loudly rather than silently
+    writing replacement chars to disk via the input layer (see
+    ``kd/cli/input.py``). Errors during reconfigure are swallowed; embedded
+    interpreters and pytest captures may lack ``reconfigure`` on any of the
+    three streams.
     """
     if sys.platform != "win32":
         return
-    for stream in (sys.stdout, sys.stderr):
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
         try:
-            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr,unused-ignore]
+            stream.reconfigure(  # type: ignore[union-attr,unused-ignore]
+                encoding="utf-8",
+                errors="strict" if stream is sys.stdin else "replace",
+            )
         except Exception:
             pass
 

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/cli/namespaces/system/__init__.py

@@ -709,7 +709,7 @@ def _resolve_target(name: str) -> tuple[Path, Path, str]:
 
 def _diff_summary(snapshot: SnapshotInfo, current_text: str) -> str:
     """One-line diff summary: ``+N -M`` lines vs current file."""
-    snap_lines = snapshot.path.read_text().splitlines()
+    snap_lines = snapshot.path.read_text(encoding="utf-8").splitlines()
     curr_lines = current_text.splitlines()
     added = removed = 0
     for line in difflib.unified_diff(snap_lines, curr_lines, n=0):
@@ -751,7 +751,7 @@ class SystemHistoryCommand(Command):
         rows: list[dict[str, Any]] = []
         for target_name in targets:
             live_path, history_dir, filename = _resolve_target(target_name)
-            current_text = live_path.read_text() if live_path.exists() else ""
+            current_text = live_path.read_text(encoding="utf-8") if live_path.exists() else ""
             for snap in list_snapshots(history_dir, filename):
                 rows.append(
                     {
@@ -791,7 +791,7 @@ class SystemRestoreCommand(Command):
         snap_path = get_snapshot_path(history_dir, filename, timestamp)
         # Snapshot current before restoring (so restore is undoable)
         snapshot_before_write(live_path)
-        restored_text = snap_path.read_text()
+        restored_text = snap_path.read_text(encoding="utf-8")
         atomic_write_text(live_path, restored_text)
         return {
             "ok": True,
@@ -830,15 +830,15 @@ class SystemDiffCommand(Command):
         live_path, history_dir, filename = _resolve_target(target_name)
 
         snap_a = get_snapshot_path(history_dir, filename, args[1])
-        text_a = snap_a.read_text()
+        text_a = snap_a.read_text(encoding="utf-8")
         label_a = f"{filename}.{args[1]}"
 
         if len(args) >= 3:
             snap_b = get_snapshot_path(history_dir, filename, args[2])
-            text_b = snap_b.read_text()
+            text_b = snap_b.read_text(encoding="utf-8")
             label_b = f"{filename}.{args[2]}"
         else:
-            text_b = live_path.read_text() if live_path.exists() else ""
+            text_b = live_path.read_text(encoding="utf-8") if live_path.exists() else ""
             label_b = filename
 
         result = diff_text(text_a, text_b, label_a, label_b)

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/client.py

@@ -45,7 +45,14 @@ from kd.article_marker import (
 from kd.config import ResolvedConfig
 from kd.connection import ConnectionContext
 from kd.debug import DebugLog
-from kd.exceptions import APIError, ConfigError, KdError, NotFoundError, ValidationError
+from kd.exceptions import (
+    APIError,
+    ConfigError,
+    FieldDiscoveryError,
+    KdError,
+    NotFoundError,
+    ValidationError,
+)
 from kd.query_parser import youtrack_query_literal
 from kd.models import (
     Article,
@@ -178,6 +185,19 @@ _SLOT_DEFAULTS: dict[str, str] = {
 }
 
 
+# Bootstrap synthesis dispatch: semantic slot -> project-side field
+# ``$type`` used to look up the issue-side ``$type`` and payload builder
+# in :data:`_FIELD_DISPATCH` when schema discovery returned no fields
+# (KDCLI-171). All three semantic slots are wired: HITL #2 confirmed
+# YouTrack accepts a synthetic ``StateIssueCustomField`` payload with a
+# ``name``-only value reference on an empty fresh project.
+_BOOTSTRAP_SLOT_TO_PROJECT_TYPE: dict[str, str] = {
+    "type": "EnumProjectCustomField",
+    "priority": "EnumProjectCustomField",
+    "state": "StateProjectCustomField",
+}
+
+
 # ---------------------------------------------------------------------------
 # Article push — types and helpers
 # ---------------------------------------------------------------------------
@@ -806,9 +826,61 @@ class IssueOperations:
         ``project`` is the project shortName (KEY).
         ``slots`` maps semantic names to values, e.g. ``{"type": "Bug"}``.
         ``aliases`` maps semantic names to actual field names from config.
+
+        On a fresh (zero-issue + non-admin) project, schema discovery
+        returns no fields and ``resolve_semantic_fields`` raises
+        :class:`FieldDiscoveryError`. For semantic-slot creates we
+        synthesize a best-effort payload using the post-discovery
+        ``$type`` mapping and let YouTrack accept or reject (KDCLI-171).
+        Generic ``--field`` flows route through
+        :meth:`resolve_generic_fields` instead and stay uncaught — without
+        server-side ``$type`` knowledge, synthesizing a guess is unsafe.
         """
         project_obj = self._yt.get_project(project)
-        return self._field_schema.resolve_semantic_fields(project_obj.id, slots, aliases)
+        try:
+            return self._field_schema.resolve_semantic_fields(project_obj.id, slots, aliases)
+        except FieldDiscoveryError as e:
+            return self._synthesize_for_empty_discovery(slots, aliases, original=e)
+
+    def _synthesize_for_empty_discovery(
+        self,
+        slots: dict[str, str],
+        aliases: dict[str, str] | None,
+        original: FieldDiscoveryError,
+    ) -> builtins.list[CustomField]:
+        """Synthesize CustomField payloads when schema discovery is empty.
+
+        Honors the alias layer (``state`` -> ``Stage`` for Scrum projects)
+        via ``aliases.get(slot, _SLOT_DEFAULTS[slot])`` — same shape as
+        :meth:`FieldSchema.resolve_semantic_fields`. Re-raises the
+        *original* :class:`FieldDiscoveryError` (full three-bullet hint
+        preserved verbatim) when any slot is not in
+        :data:`_BOOTSTRAP_SLOT_TO_PROJECT_TYPE` — partial-bootstrap is
+        not a valid posture; the operator either gets all slots they
+        asked for, or the unchanged improved hint pointing at all three
+        workarounds (sample issue, admin token, or omit-and-update).
+        """
+        aliases = aliases or {}
+        unsupported = [s for s in slots if s not in _BOOTSTRAP_SLOT_TO_PROJECT_TYPE]
+        if unsupported:
+            raise original
+
+        result: builtins.list[CustomField] = []
+        for slot, value in slots.items():
+            project_field_type = _BOOTSTRAP_SLOT_TO_PROJECT_TYPE[slot]
+            issue_type, builder = _FIELD_DISPATCH[(project_field_type, "")]
+            field_name = aliases.get(slot, _SLOT_DEFAULTS.get(slot, slot))
+            self._debug.debug(
+                "fields",
+                f"synthesizing slot '{slot}' -> field '{field_name}' "
+                f"($type={issue_type}) on empty discovery",
+            )
+            result.append(
+                CustomField.model_validate(
+                    {"name": field_name, "value": builder(value), "$type": issue_type}
+                )
+            )
+        return result
 
     def resolve_generic_fields(
         self,

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/config.py

@@ -406,7 +406,7 @@ def load_config(path: Path | None = None) -> YtctlConfig:
     if not config_path.exists():
         return YtctlConfig()
     try:
-        raw = yaml.safe_load(config_path.read_text()) or {}
+        raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
         return YtctlConfig(**raw)
     except (yaml.YAMLError, TypeError, ValueError) as e:
         raise ConfigError(f"Invalid config at {config_path}: {e}") from e
@@ -511,7 +511,7 @@ def update_config_path(path: str, value: str, config_path: Path) -> tuple[str, A
     # Load raw YAML, capture original text for rollback.
     raw = _load_raw_yaml(config_path)
     original_text: str | None
-    original_text = config_path.read_text() if config_path.exists() else None
+    original_text = config_path.read_text(encoding="utf-8") if config_path.exists() else None
 
     retention = _retention_from_raw(raw, DEFAULT_RETENTION)
     snapshot_before_write(config_path, retention=retention)
@@ -619,7 +619,7 @@ def _load_raw_yaml(path: Path) -> dict[str, Any]:
     if not path.exists():
         return {}
     try:
-        data = yaml.safe_load(path.read_text())
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
     except yaml.YAMLError as e:
         raise ConfigError(f"Invalid YAML in {path}: {e}") from e
     return data or {}
@@ -1395,16 +1395,16 @@ def _manage_gitignore(directory: Path) -> str:
 
     gitignore = git_root / ".gitignore"
     if gitignore.exists():
-        content = gitignore.read_text()
+        content = gitignore.read_text(encoding="utf-8")
         lines = {line.strip() for line in content.splitlines()}
         if lines & _GITIGNORE_PATTERNS:
             return "already_ignored"
         # Append with a trailing newline if file doesn't end with one
         sep = "" if content.endswith("\n") else "\n"
-        gitignore.write_text(f"{content}{sep}\n# kd local config\n.kd/\n")
+        gitignore.write_text(f"{content}{sep}\n# kd local config\n.kd/\n", encoding="utf-8")
         return "added"
 
-    gitignore.write_text("# kd local config\n.kd/\n")
+    gitignore.write_text("# kd local config\n.kd/\n", encoding="utf-8")
     return "created"
 
 
@@ -1466,7 +1466,7 @@ def init_project_config(
         )
 
     config_dir.mkdir(parents=True, exist_ok=True)
-    config_path.write_text(template)
+    config_path.write_text(template, encoding="utf-8")
 
     if global_tier:
         gitignore_action = "not_applicable"

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/config_read.py

@@ -174,7 +174,7 @@ def _get_history(path: str, key: str) -> dict[str, Any] | None:
         if value is None:
             continue
         # Only surface values actually written to the file, not schema defaults.
-        raw = yaml.safe_load(tier_path.read_text()) or {}
+        raw = yaml.safe_load(tier_path.read_text(encoding="utf-8")) or {}
         history_block = raw.get("history") if isinstance(raw.get("history"), dict) else {}
         if not isinstance(history_block, dict) or key not in history_block:
             continue

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/exceptions.py

@@ -95,6 +95,19 @@ class ValidationError(KdError):
     """Invalid input before API call."""
 
 
+class FieldDiscoveryError(KdError):
+    """Schema discovery returned no fields for a project.
+
+    Raised by ``list_project_custom_fields`` when both the per-issue
+    projection and the admin projection produce empty results — the
+    'fresh project + non-admin token' bootstrap shape. Caught at the
+    SDK layer (``IssueOperations.resolve_custom_fields``) so semantic
+    create-with-slots flows can synthesize a best-effort payload;
+    generic ``--field`` flows let it propagate so the operator sees
+    the improved hint.
+    """
+
+
 class QueryLiteralError(KdError):
     """Name cannot be encoded as a YouTrack DSL value literal.
 

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/primer.py

@@ -121,7 +121,7 @@ def load_primer(path: Path | None = None) -> PrimerData:
     if not primer_file.exists():
         return PrimerData()
     try:
-        raw = yaml.safe_load(primer_file.read_text()) or {}
+        raw = yaml.safe_load(primer_file.read_text(encoding="utf-8")) or {}
         return PrimerData(**raw)
     except (yaml.YAMLError, TypeError, ValueError) as e:
         raise ConfigError(f"Invalid primer at {primer_file}: {e}") from e

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/resources/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.6.5] — 2026-04-30
+
+This release closes M011 by adding empty-project bootstrap support to
+`/issue create`. Together with M011 S1 + S2 (the Windows UTF-8 audit in
+2.6.4), the milestone delivers a kd-only path from a fresh primer to
+the first ticket on a brand-new project on Windows: file IO, stdin,
+and field-resolution all work without falling back to the web UI.
+
+### Fixed
+- `/issue create` semantic bootstrap now succeeds on fresh
+  (zero-issue, contributor-token) projects: when both schema-discovery
+  paths return empty, kd synthesizes a best-effort payload for
+  `--type`, `--priority`, and `--state` using the post-discovery
+  `$type` mapping and lets YouTrack accept or reject. Pre-fix, kd
+  bailed before the API call with `Error: No custom fields discovered
+  for project '<id>'`, telling the operator to fall back to the web UI
+  for the very first issue — a kd-only bootstrap workflow could not
+  populate Type / Priority / State on a brand-new project.
+  `--field NAME=VALUE` still raises with the improved hint (kd cannot
+  guess server-side `$type` for arbitrary fields). The hint gains a
+  third bullet pointing at the simplest workaround: `Or omit --type /
+  --priority / --state to create a minimal first issue, then update it
+  via `/issue update``. See KDCLI-A-22 for the empty-project bootstrap
+  detail (KDCLI-171).
+
+## [2.6.4] — 2026-04-30
+
+This release closes the Windows UTF-8 audit started in 2.6.3. The
+stream-encoding side (stdout/stderr) shipped earlier; 2.6.4 closes the
+file-IO and stdin sides so primer notes, `--content @file`, and heredoc
+or piped input round-trip non-cp1252 characters cleanly.
+
+### Fixed
+- File reads and writes on Windows are now explicit UTF-8 at every
+  kd-owned text-IO call site (primer, config, history/diff snapshots,
+  `--description @file` / `--content @file` content). The headline
+  reproducer was `kd /primer show` raising `'charmap' codec can't
+  decode byte 0x9d` whenever `.kd/primer.yaml` contained any non-cp1252
+  byte (em-dash, arrow, right double quotation mark) — a single primer
+  note authored on macOS/Linux was enough to read-block every
+  downstream Windows session (KDCLI-170).
+- Stdin on Windows is now forced to UTF-8 with strict error handling,
+  so heredocs and pipes carrying non-ASCII content (em-dash, arrow,
+  right double quotation mark) into `kd /primer/note update -`,
+  `kd /article create --content @-`, `--description -`, or any other
+  stdin-consuming command no longer get cp1252-mojibaked at the input
+  layer before being persisted. Invalid UTF-8 bytes on stdin (and
+  non-UTF-8 `@file` content) now surface as a clean
+  `Error: Stdin input could not be decoded as UTF-8 ... / Hint: Ensure
+  the upstream shell pipes UTF-8 bytes ...` (or
+  `Hint: Save the file as UTF-8 ...`) instead of the generic "internal
+  error: ... This is a bug." block (KDCLI-169).
+
 ## [2.6.3] — 2026-04-30
 
 This release focuses on Windows shakedown: encoding crashes, primer

{kd_cli-2.6.3 → kd_cli-2.6.5}/kd/resources/operating-guide.md

@@ -126,6 +126,8 @@ Clear optional custom fields with an empty value, for example `kd /issue update
 
 `--field` supports bundle families (enum, state, owned, version, build), user fields, period, and string `SimpleProjectCustomField` subtypes; whitespace inside the value is preserved. Unsupported families (text, `Multi*` enum/user variants, and `SimpleProjectCustomField` with `integer` / `float` / `date` subtypes) fail client-side with a message naming both the project `$type` and the `fieldType.id` subtype so a follow-on bug report can skip the probe.
 
+On fresh (zero-issue, contributor-token) projects where schema discovery returns no fields, kd synthesizes a best-effort bootstrap payload for `--type`, `--priority`, and `--state` and lets YouTrack accept or reject; YouTrack's rejection text surfaces unchanged so an unusual project setup is auditable upstream. `--field NAME=VALUE` still requires a sample issue or admin token because kd lacks server-side `$type` knowledge to synthesize generic fields safely. KDCLI-A-22 carries the detail.
+
 Attachment metadata download URLs may start with `/api/`. kd handles this internally on download commands; do not assume the raw URL can be appended unchanged to an API base URL in custom scripts.
 
 Tag existence, tag visibility, and tag sharing rights are different concerns. A visible tag may not be usable for every operation, and sharing settings are provider-specific security posture, not just display metadata.
@@ -244,7 +246,7 @@ kd -DDD /issue list --project KDCLI
 
 Debug output goes to stderr and tokens are redacted. Use `-DDD` when investigating upstream API behavior because it includes request and response details.
 
-On Windows, kd forces UTF-8 stdout and stderr at the entry point so non-ASCII characters (`→`, `—`, `≤`, em-dash) render correctly regardless of the console's default code page (cp1252 on most installs). No `PYTHONIOENCODING` workaround is needed.
+On Windows, kd forces UTF-8 on stdin, stdout, and stderr at the entry point so non-ASCII characters (`→`, `—`, `≤`, em-dash) render correctly regardless of the console's default code page (cp1252 on most installs), and every kd-owned file read/write (primer, config, history snapshots, `--content @file` and `--description @file`) uses explicit UTF-8 so primer/config files written by macOS or Linux load cleanly on Windows. Stdin uses strict decoding so invalid UTF-8 piped into `kd /primer/note update -` or `kd /article create --content @-` fails loudly with a clear diagnostic (`Error: Stdin input could not be decoded as UTF-8 ...`) rather than silently corrupting persisted content. No `PYTHONIOENCODING` or `PYTHONUTF8` workaround is needed.
 
 Unhandled exceptions render a one-line or one-paragraph friendly diagnostic and exit non-zero. To see the full traceback (for bug reports or local debugging), re-run with `--debug` / `-D`; the wrapper re-raises the original exception so the runtime prints the traceback. `KdError` (expected user-facing failures) keep their existing one-line `Error: ...` / optional `Hint: ...` shape on every platform.
 

{kd_cli-2.6.3 → kd_cli-2.6.5/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.6.3 → kd_cli-2.6.5}/pyproject.toml

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