kd-cli 2.3.0__tar.gz → 2.4.0__tar.gz

{kd_cli-2.3.0/kd_cli.egg-info → kd_cli-2.4.0}/PKG-INFO

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

kd_cli-2.4.0/kd/cli/core/confirm.py

@@ -0,0 +1,43 @@
+"""Confirmation guard for irreversible destructive commands.
+
+Some destructive commands bypass YouTrack's Deleted Items safety net —
+project, tag, and user deletes in particular. This helper enforces an
+opt-in ``--confirm`` flag: without it the command aborts with an
+actionable multi-line error; with it the delete proceeds.
+
+The error follows the ``_missing_tag_resolution`` pattern from
+``kd.client``: a human-readable explanation plus a ``suggestion`` line
+that spells out the literal retry command so an LLM reading the
+stderr can proceed without extra reasoning.
+"""
+
+from __future__ import annotations
+
+import shlex
+
+from kd.exceptions import ValidationError
+
+
+def require_confirm(
+    *,
+    confirmed: bool,
+    command: str,
+    entity_id: str,
+    caveat: str,
+) -> None:
+    """Abort unless ``--confirm`` was passed.
+
+    Args:
+        confirmed: Whether the caller passed ``--confirm``.
+        command: Full command path, e.g. ``/project delete``.
+        entity_id: The target identifier as given on the command line.
+        caveat: One or two sentences explaining why this particular
+            delete is unsafe — the per-entity failure mode (issues
+            vanishing, tag membership gone, identity refs detaching).
+    """
+    if confirmed:
+        return
+    raise ValidationError(
+        f"kd {command} {entity_id} is irreversible. {caveat}",
+        suggestion=(f"Retry with: kd {command} {shlex.quote(entity_id)} --confirm"),
+    )

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/core/option_registry.py

@@ -38,6 +38,7 @@ class OptionDeclaration:
     help_text: str = ""
     is_list: bool = False
     aliases: list[str] = field(default_factory=list)
+    hidden_from_reference: bool = False
 
 
 @dataclass

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/main.py

@@ -547,6 +547,8 @@ def _print_namespace_reference(ns: Namespace, depth: int = 0) -> None:
 
         # Options
         for opt in cmd.get_options():
+            if opt.hidden_from_reference:
+                continue
             flag = f"--{opt.name}"
             if opt.short_name:
                 flag += f"/-{opt.short_name}"

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/namespaces/primer/__init__.py

@@ -26,6 +26,7 @@ from kd.primer import (
     clear_articles,
     clear_notes,
     clear_tags,
+    init_primer,
     load_primer,
     remove_article,
     remove_note,
@@ -107,6 +108,53 @@ class PrimerShowCommand(Command):
         }
 
 
+# ---------------------------------------------------------------------------
+# /primer init
+# ---------------------------------------------------------------------------
+
+
+class PrimerInitCommand(Command):
+    """Scaffold ``.kd/primer.yaml`` from a packaged template."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "init",
+            "Scaffold .kd/primer.yaml from a template",
+            usage="kd /primer init [TEMPLATE]",
+            long_description=(
+                "Creates .kd/primer.yaml from a packaged template.  Default "
+                "template is `hitl` — a human-in-the-loop session workflow "
+                "scaffold with placeholder prose in the scope-guard, session-"
+                "workflow, and canonical-reference slots.  The template is "
+                "copied through unchanged so its banner and example-shape "
+                "comments survive.  Refuses if a primer already exists; "
+                "there is no --force (deletion is explicit operator work)."
+            ),
+            examples=[
+                "kd /primer init",
+                "kd /primer init hitl",
+            ],
+            see_also=["/primer show", "/primer/note list"],
+        )
+
+    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)
+        template = args[0] if args else "hitl"
+        created = init_primer(template)
+        return {
+            "ok": True,
+            "action": "init",
+            "template": template,
+            "created": str(created),
+            "next": "kd /primer show -o yaml",
+        }
+
+
 # ---------------------------------------------------------------------------
 # /primer/note
 # ---------------------------------------------------------------------------
@@ -534,6 +582,7 @@ def create_primer_namespace() -> Namespace:
         path="primer",
     )
     ns.register_command("show", PrimerShowCommand())
+    ns.register_command("init", PrimerInitCommand())
 
     # /primer/note
     note_ns = Namespace("note", "Primer notes and conventions", path="primer/note")

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/namespaces/project/__init__.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 from typing import Any
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
 from kd.cli.core.option_registry import (
     OptionDeclaration,
@@ -153,9 +154,22 @@ class ProjectDeleteCommand(Command):
             "Delete a project",
             requires_client=True,
             usage="kd /project delete KEY",
-            examples=["kd /project delete TST"],
+            examples=["kd /project delete TST --confirm"],
             see_also=["/project list"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — project delete is not recoverable from "
+                    "Deleted Items (issues and articles are permanently removed)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -163,6 +177,16 @@ class ProjectDeleteCommand(Command):
         if not args:
             raise ValidationError("Usage: kd /project delete KEY")
         key = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/project delete",
+            entity_id=key,
+            caveat=(
+                "All issues and articles in the project are permanently "
+                "deleted (they are not moved to Deleted Items) — recovery "
+                "requires a database backup restore."
+            ),
+        )
         client.projects.delete(key)
         return {"ok": True, "action": "delete", "project": key}
 

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/namespaces/tag/__init__.py

@@ -10,6 +10,7 @@ import sys
 from typing import Any, Literal
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
 from kd.cli.core.option_registry import (
     OptionDeclaration,
@@ -203,9 +204,22 @@ class TagDeleteCommand(Command):
             "Delete a tag",
             requires_client=True,
             usage="kd /tag delete TAG_NAME",
-            examples=["kd /tag delete sprint-47"],
+            examples=["kd /tag delete sprint-47 --confirm"],
             see_also=["/tag list", "/tag create"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — tag delete is not recoverable from Deleted "
+                    "Items (tag membership is lost across all entities)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -213,6 +227,16 @@ class TagDeleteCommand(Command):
         if not args:
             raise ValidationError("Usage: kd /tag delete TAG_NAME")
         name = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/tag delete",
+            entity_id=name,
+            caveat=(
+                "Tag membership is removed from every tagged issue and "
+                "article; recreating the tag does not restore assignments. "
+                "Full recovery requires a database backup restore."
+            ),
+        )
         client.tags.delete(name)
         return {"ok": True, "action": "delete", "tag": name}
 

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/cli/namespaces/user/__init__.py

@@ -9,8 +9,13 @@ from __future__ import annotations
 from typing import Any
 
 from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.confirm import require_confirm
 from kd.cli.core.namespaces import Namespace
-from kd.cli.core.option_registry import ResolvedOptions
+from kd.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+)
 from kd.exceptions import ValidationError
 
 
@@ -77,17 +82,42 @@ class UserDeleteCommand(Command):
             "Delete a user",
             requires_client=True,
             usage="kd /user delete HUB_USER_ID",
-            examples=["kd /user delete abc-123"],
+            examples=["kd /user delete abc-123 --confirm"],
             see_also=["/user list"],
         )
+        self.register_option(
+            OptionDeclaration(
+                name="confirm",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Required — user delete is not recoverable from Deleted "
+                    "Items (consider banning via the Hub UI instead)"
+                ),
+                hidden_from_reference=True,
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
         if not args:
             raise ValidationError("Usage: kd /user delete HUB_USER_ID")
-        client.users.delete(args[0])
-        return {"ok": True, "action": "delete", "user": args[0]}
+        user_id = args[0]
+        require_confirm(
+            confirmed=bool(options.command.get("confirm")),
+            command="/user delete",
+            entity_id=user_id,
+            caveat=(
+                "Identity references in issue history become detached, and "
+                "the account is removed from the Hub. Consider banning the "
+                "user in the Hub UI instead; full recovery requires a "
+                "database backup restore."
+            ),
+        )
+        client.users.delete(user_id)
+        return {"ok": True, "action": "delete", "user": user_id}
 
 
 def create_user_namespace() -> Namespace:

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/primer.py

@@ -10,6 +10,7 @@ knowledge).  The file is created lazily on first write operation.
 
 from __future__ import annotations
 
+import importlib.resources
 from pathlib import Path
 from typing import Any
 
@@ -283,3 +284,49 @@ def clear_tags(path: Path | None = None) -> int:
     data.tags.clear()
     save_primer(data, primer_file)
     return count
+
+
+# ---------------------------------------------------------------------------
+# Scaffolding
+# ---------------------------------------------------------------------------
+
+_PRIMER_TEMPLATE_PACKAGE = "kd.resources.primers"
+
+
+def list_primer_templates() -> list[str]:
+    """Return sorted names of shipped primer templates (without ``.yaml``)."""
+    root = importlib.resources.files(_PRIMER_TEMPLATE_PACKAGE)
+    return sorted(p.name[: -len(".yaml")] for p in root.iterdir() if p.name.endswith(".yaml"))
+
+
+def init_primer(template: str = "hitl", path: Path | None = None) -> Path:
+    """Scaffold ``.kd/primer.yaml`` from a packaged template.
+
+    Copies the template file through unchanged so its banner and inline
+    comments survive; no YAML load/dump round-trip.  Refuses if a primer
+    already exists — deletion is explicit operator work and there is no
+    ``--force``.
+    """
+    from kd.history import atomic_write_text
+
+    available = list_primer_templates()
+    if template not in available:
+        raise ValidationError(
+            f"Unknown primer template '{template}'. Available: {', '.join(available)}"
+        )
+
+    primer_file = path or _primer_path()
+    if primer_file.exists():
+        raise ValidationError(
+            f"Primer already exists at {primer_file}. "
+            f"Run `kd /primer show` to inspect it, or delete the file to start over."
+        )
+
+    content = (
+        importlib.resources.files(_PRIMER_TEMPLATE_PACKAGE)
+        .joinpath(f"{template}.yaml")
+        .read_text(encoding="utf-8")
+    )
+    primer_file.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(primer_file, content)
+    return primer_file

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-04-19
+
+### Added
+- `kd /primer init [TEMPLATE]` scaffolds `.kd/primer.yaml` from a packaged template so fresh workspaces don't start from a blank page. The default `hitl` template ships placeholder prose in three slots (scope guard, session workflow, canonical reference); the banner and example-shape comments are preserved verbatim. Refuses if a primer already exists; unknown template names reject with the available-templates list (KDCLI-97).
+- `--confirm` flag on `/project delete`, `/tag delete`, and `/user delete` — these three deletes bypass YouTrack's Deleted Items and require a backup restore to undo, so kd now rejects them without `--confirm` and prints the literal retry command in the error. The flag is hidden from `kd --reference` but visible in per-command `--help` (KDCLI-96).
+
 ## [2.3.0] — 2026-04-18
 
 ### Added

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd/resources/operating-guide.md

@@ -82,6 +82,14 @@ kd /issue update KDCLI-42 --state Fixed -o yaml
 For article push, use `--dry-run` before a risky write and inspect conflicts with `/article pull`.
 `/article push --tag` rejects missing tags by default and prints the concrete recovery commands. Use `--create-tags` only for scripted flows that already own the tag namespace.
 
+Three delete commands bypass YouTrack's Deleted Items safety net and require an explicit `--confirm` flag:
+
+- `/project delete` — all issues and articles in the project are permanently removed, not moved to Deleted Items.
+- `/tag delete` — tag membership is lost across every tagged issue and article; recreating the tag does not restore assignments.
+- `/user delete` — identity references in issue history become detached; consider banning in the Hub UI instead.
+
+Without `--confirm` these commands exit non-zero with an error that names the failure mode and prints the literal retry command. Recovery for any of the three requires a database backup restore. `/issue delete`, `/article delete`, and attachment deletes do not require `--confirm` — they go to Deleted Items and are admin-restorable for roughly 14 days.
+
 ## YouTrack Gotchas
 
 YouTrack articles are not queryable like issues. `/api/articles` has no issue-style `query` parameter, and there is no server-side article-by-tag endpoint. kd article tag lookup scans article pages that include `tags(id,name)` and filters locally.
@@ -106,6 +114,8 @@ Tag existence, tag visibility, and tag sharing rights are different concerns. A
 
 ## Primer Practices
 
+For a fresh workspace, scaffold the primer with `kd /primer init`. The default `hitl` template drops placeholder prose into three slots — scope guard, session workflow, canonical reference — that the operator fills in an editor. The command refuses if a primer already exists and has no `--force`; deletion is explicit operator work.
+
 Primer notes should capture durable project rules, not temporary status. Good notes explain naming conventions, required workflows, dangerous assumptions, and pointers to canonical references.
 
 Do not use the primer as a session log. Avoid recording current focus, completed session lists, release-cadence details copied from a plan, or other progress facts that can become false by the next agent session. If the primer needs to point at active work, stop at the current master plan or equivalent planning document; the agent should open that document and derive the next step from there.
@@ -211,4 +221,4 @@ Use these sources together:
 - `docs/design/architecture.md` and ADRs for architectural constraints.
 
 ---
-Updated: 2026-04-18
+Updated: 2026-04-19

kd_cli-2.4.0/kd/resources/primers/hitl.yaml

@@ -0,0 +1,41 @@
+# DO NOT EDIT THIS FILE DIRECTLY. Use `kd /primer --help` to manage it.
+#
+# This is the `hitl` template — human-in-the-loop session workflow. Edit the
+# placeholders below to fit this workspace. Three slots:
+#   1. Scope guard — what this workspace is / is not; how to reject drift.
+#   2. Session workflow — the repeatable loop and local conventions.
+#   3. Canonical reference — pinned article(s) with durable background.
+
+notes:
+- '<WORKSPACE> is <one-sentence identity: what kind of tool, codebase, or knowledge
+  base this workspace represents>. Primary loop: <describe the repeatable action —
+  for example, pull context → reason → push focused updates back>. <State what this
+  workspace is NOT — adjacent shapes it should not drift toward, such as migration
+  platform, data warehouse, silent local mirror>. Before adding features that look
+  like the adjacent shape, re-read this guard. Test question: does this keep the
+  workspace <identity>-shaped, or does it drag it toward <adjacent shape>? Reject
+  drift toward the latter.'
+- 'Active planning entry point: <path to master plan, roadmap doc, or tracking
+  project>. The primer must not record session-level progress, current focus,
+  completed-session lists, or release-cadence details copied from the plan; those
+  stale quickly. A fresh agent reads this pointer, checks the active plan or
+  assigned ticket for scope, then follows the default session workflow recorded
+  in this primer.'
+- 'Default session workflow: 1) Load primer with `kd /primer show -o yaml`. 2) Read
+  the assigned ticket or active planning source; if tracked work lacks a ticket,
+  create one with `kd /issue create ... --project <PROJECT> --type <Feature|Bug|Task>`
+  and use the returned ID. 3) Enter plan mode for a full tracked session and write
+  the session doc from the local template, naming the file with the ticket ID when
+  present. 4) Execute code, tests, and docs together; run the project''s test, lint,
+  and type checks before commit. 5) Commit with `<TICKET-PREFIX>-NN: <subject>` for
+  tracked work. 6) Install the built artifact, run applicable HITL against a real
+  target, append the session conclusion, comment on the ticket, transition it to
+  <done-state>, and update the relevant plan and docs. If no ticket or user-visible
+  HITL surface exists, record that explicitly in the session doc.'
+
+tags: []
+
+# Pin canonical reference articles after `kd /primer init`. Example shape:
+#   - id: <ARTICLE-ID>
+#     summary: <one-line hook — what this pinned article gives the operator>
+articles: []

{kd_cli-2.3.0 → kd_cli-2.4.0/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.3.0 → kd_cli-2.4.0}/kd_cli.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ kd/cli/tree.py
 kd/cli/core/__init__.py
 kd/cli/core/command_base.py
 kd/cli/core/command_parser.py
+kd/cli/core/confirm.py
 kd/cli/core/namespaces.py
 kd/cli/core/option_registry.py
 kd/cli/namespaces/__init__.py
@@ -68,6 +69,8 @@ kd/resources/command-synonyms.yaml
 kd/resources/config-template.yaml
 kd/resources/error-messages.yaml
 kd/resources/operating-guide.md
+kd/resources/primers/__init__.py
+kd/resources/primers/hitl.yaml
 kd_cli.egg-info/PKG-INFO
 kd_cli.egg-info/SOURCES.txt
 kd_cli.egg-info/dependency_links.txt

{kd_cli-2.3.0 → kd_cli-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.3.0"
+version = "2.4.0"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -57,7 +57,7 @@ kd = "kd.cli.main:main"
 include = ["kd*"]
 
 [tool.setuptools.package-data]
-kd = ["resources/*.yaml", "resources/*.md"]
+kd = ["resources/*.yaml", "resources/*.md", "resources/primers/*.yaml"]
 
 [tool.ruff]
 exclude = ["docs"]