tcw-cli 2.1.1__tar.gz → 2.1.3__tar.gz

{tcw_cli-2.1.1 → tcw_cli-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.1.1
+Version: 2.1.3
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -229,6 +229,28 @@ They link by one-directional pointers — a capability names the taxonomy terms
 involves, a work item names the capability it changes — and never copy each
 other's content.
 
+## Contents
+
+- [The problem](#the-problem)
+- [What it looks like](#what-it-looks-like)
+- [Why many repositories is the case it is built for](#why-many-repositories-is-the-case-it-is-built-for)
+- [What it deliberately refuses](#what-it-deliberately-refuses)
+- [What adopting it costs](#what-adopting-it-costs)
+- [Who it's for](#who-its-for)
+- [Storage abstraction (the prime directive)](#storage-abstraction-the-prime-directive)
+- [Install](#install)
+  - [As a plugin (recommended)](#as-a-plugin-recommended)
+  - [As a Python package](#as-a-python-package)
+  - [In a cloud environment](#in-a-cloud-environment)
+- [Quickstart](#quickstart)
+- [Working from your Jira tickets](#working-from-your-jira-tickets)
+- [Documentation](#documentation)
+- [Skills — the judgment layer](#skills--the-judgment-layer)
+  - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
+  - [Review agents and slash commands](#review-agents-and-slash-commands)
+- [Status](#status)
+- [Further reading](#further-reading)
+
 ---
 
 ## The problem
@@ -548,15 +570,17 @@ studies your code, proposes a first draft, refines it with you, and writes it.
 
 ---
 
-## Reading your Jira tickets
+## Working from your Jira tickets
 
-A project can name the Jira Cloud site it uses, and then read from it. Both
-commands are read-only: nothing here changes a ticket, and nothing yet turns a
-ticket into a work item.
+A project can name the Jira Cloud site it uses, read its tickets, and take one as
+a work item.
 
 ```sh
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
+tcw work tracker import ENG-482    # take the ticket and get a work item for it
+tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker unlink <slug> --reason "wrong ticket"
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -579,6 +603,32 @@ work:
 environment variables; TCW reads them at the moment it makes a request, so a token
 cannot be committed by accident.
 
+**Write the shared settings once.** In a workspace of connected nodes, a node's
+`tracker` block takes any setting it leaves out from its parent nodes, all the way
+up. So the site, credentials and claim transition can live in the workspace root,
+and each package writes only the tickets it wants to see:
+
+```yaml
+# packages/api/tcw-config.yaml
+work:
+    tracker:
+        candidate-query: project = EX AND component = api AND status = "To Do"
+```
+
+The nearest file wins each setting, and `credentials` and `transitions` merge
+setting by setting too. A node with no `tracker` block of its own has no tracker,
+whatever its parents say. Two rules keep this safe:
+
+- **`credentials` must sit beside `base-url`.** A node that sets its own `base-url`
+  must also set both of its own `credentials` keys, even if the address is the same
+  as its parent's, so a token is never sent to a site chosen in a different file.
+- **A node with its own board is checked like any tracking node.** If it holds the
+  shared settings, it needs a `candidate-query` of its own. Keeping shared settings
+  in a node without a board avoids that.
+
+A mistake in a parent's settings is reported by `tcw validate` in every node that
+inherits it, naming the parent's file.
+
 `tracker show` reports two different things, and the distinction matters:
 
 - **claimable** — whether this ticket currently offers the transition you
@@ -594,6 +644,25 @@ reports `not determined`, because it cannot show you what happens to the second
 person. Making a workflow exclusive is a Jira administration change, not something
 TCW can do for you.
 
+**Taking a ticket.** `tracker import` moves the ticket through your configured
+claim transition, assigns it to you if nobody had it, and then checks Jira again:
+only when the ticket really is started and yours does it create a backlog item. The
+ticket's text goes into the item as its raw input, with a link back, and the item's
+request still gets written the usual way. A ticket assigned to someone else is
+refused, and so is one that is already closed.
+
+Running `import` again for the same ticket in the same node gives you the same item
+rather than a second one, and if the first run took the ticket but stopped before creating the
+item, the second run finishes the job. One ticket can deliberately become several
+items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
+and keeps a record of it with your reason; it never changes the ticket in Jira.
+
+Three limits to know. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that. Two runs by the
+same Jira account at the same moment can both create an item. And each node keeps its
+own bindings: importing one ticket in two nodes of a workspace, even nodes sharing
+inherited settings, gives two items, one in each.
+
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
 `tcw validate` never contacts the tracker, which matters because projects commonly

{tcw_cli-2.1.1 → tcw_cli-2.1.3}/README.md

@@ -13,6 +13,28 @@ They link by one-directional pointers — a capability names the taxonomy terms
 involves, a work item names the capability it changes — and never copy each
 other's content.
 
+## Contents
+
+- [The problem](#the-problem)
+- [What it looks like](#what-it-looks-like)
+- [Why many repositories is the case it is built for](#why-many-repositories-is-the-case-it-is-built-for)
+- [What it deliberately refuses](#what-it-deliberately-refuses)
+- [What adopting it costs](#what-adopting-it-costs)
+- [Who it's for](#who-its-for)
+- [Storage abstraction (the prime directive)](#storage-abstraction-the-prime-directive)
+- [Install](#install)
+  - [As a plugin (recommended)](#as-a-plugin-recommended)
+  - [As a Python package](#as-a-python-package)
+  - [In a cloud environment](#in-a-cloud-environment)
+- [Quickstart](#quickstart)
+- [Working from your Jira tickets](#working-from-your-jira-tickets)
+- [Documentation](#documentation)
+- [Skills — the judgment layer](#skills--the-judgment-layer)
+  - [Reading a lifecycle stage](#reading-a-lifecycle-stage)
+  - [Review agents and slash commands](#review-agents-and-slash-commands)
+- [Status](#status)
+- [Further reading](#further-reading)
+
 ---
 
 ## The problem
@@ -332,15 +354,17 @@ studies your code, proposes a first draft, refines it with you, and writes it.
 
 ---
 
-## Reading your Jira tickets
+## Working from your Jira tickets
 
-A project can name the Jira Cloud site it uses, and then read from it. Both
-commands are read-only: nothing here changes a ticket, and nothing yet turns a
-ticket into a work item.
+A project can name the Jira Cloud site it uses, read its tickets, and take one as
+a work item.
 
 ```sh
 tcw work tracker list              # tickets the configured query selects
 tcw work tracker show ENG-482      # one ticket, and whether it is yours to take
+tcw work tracker import ENG-482    # take the ticket and get a work item for it
+tcw work tracker link <slug> ENG-482       # take it for an item you already have
+tcw work tracker unlink <slug> --reason "wrong ticket"
 ```
 
 Configuration goes in the node's `tcw-config.yaml`:
@@ -363,6 +387,32 @@ work:
 environment variables; TCW reads them at the moment it makes a request, so a token
 cannot be committed by accident.
 
+**Write the shared settings once.** In a workspace of connected nodes, a node's
+`tracker` block takes any setting it leaves out from its parent nodes, all the way
+up. So the site, credentials and claim transition can live in the workspace root,
+and each package writes only the tickets it wants to see:
+
+```yaml
+# packages/api/tcw-config.yaml
+work:
+    tracker:
+        candidate-query: project = EX AND component = api AND status = "To Do"
+```
+
+The nearest file wins each setting, and `credentials` and `transitions` merge
+setting by setting too. A node with no `tracker` block of its own has no tracker,
+whatever its parents say. Two rules keep this safe:
+
+- **`credentials` must sit beside `base-url`.** A node that sets its own `base-url`
+  must also set both of its own `credentials` keys, even if the address is the same
+  as its parent's, so a token is never sent to a site chosen in a different file.
+- **A node with its own board is checked like any tracking node.** If it holds the
+  shared settings, it needs a `candidate-query` of its own. Keeping shared settings
+  in a node without a board avoids that.
+
+A mistake in a parent's settings is reported by `tcw validate` in every node that
+inherits it, naming the parent's file.
+
 `tracker show` reports two different things, and the distinction matters:
 
 - **claimable** — whether this ticket currently offers the transition you
@@ -378,6 +428,25 @@ reports `not determined`, because it cannot show you what happens to the second
 person. Making a workflow exclusive is a Jira administration change, not something
 TCW can do for you.
 
+**Taking a ticket.** `tracker import` moves the ticket through your configured
+claim transition, assigns it to you if nobody had it, and then checks Jira again:
+only when the ticket really is started and yours does it create a backlog item. The
+ticket's text goes into the item as its raw input, with a link back, and the item's
+request still gets written the usual way. A ticket assigned to someone else is
+refused, and so is one that is already closed.
+
+Running `import` again for the same ticket in the same node gives you the same item
+rather than a second one, and if the first run took the ticket but stopped before creating the
+item, the second run finishes the job. One ticket can deliberately become several
+items with `--part api`, `--part web`, and so on. `unlink` removes a wrong binding
+and keeps a record of it with your reason; it never changes the ticket in Jira.
+
+Three limits to know. On a workflow that lets anyone start a ticket from any status,
+two people can both take the same ticket, and TCW does not stop that. Two runs by the
+same Jira account at the same moment can both create an item. And each node keeps its
+own bindings: importing one ticket in two nodes of a workspace, even nodes sharing
+inherited settings, gives two items, one in each.
+
 Two guarantees worth stating plainly. A project with no `tracker` block behaves
 exactly as before, with no new required setting and no network access. And
 `tcw validate` never contacts the tracker, which matters because projects commonly

{tcw_cli-2.1.1 → tcw_cli-2.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.1.1"
+version = "2.1.3"
 description = "Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project."
 readme = "README.md"
 requires-python = ">=3.11"

tcw_cli-2.1.3/tcw/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.1.3"

{tcw_cli-2.1.1 → tcw_cli-2.1.3}/tcw/capabilities/cli.py

@@ -9,7 +9,8 @@ from tcw.store.base import AmbiguousRef
 from tcw.store.fs import FsCapabilitiesStore, find_node, git_root
 
 NAME = "capabilities"
-SUBCOMMANDS = {"init", "list", "show", "path", "add", "search", "check", "set", "reset", "extends", "drift"}
+SUBCOMMANDS = {"init", "list", "show", "path", "add", "search", "check", "set", "reset", "rm",
+               "extends", "drift"}
 DEFAULT_SUBCOMMAND = "show"  # `tcw capabilities <path>` == `tcw capabilities show <path>`
 
 
@@ -129,6 +130,19 @@ def _reset(args: argparse.Namespace) -> int:
     return 0
 
 
+def _rm(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        st.remove(args.id)
+    except (ValueError, RefError) as e:              # AmbiguousRef carries its own message
+        print(f"tcw capabilities rm: {e}", file=sys.stderr)
+        return 1
+    print(f"Removed capability {args.id}")
+    return 0
+
+
 def _search(args: argparse.Namespace) -> int:
     st = _store()
     if st is None:
@@ -294,6 +308,10 @@ def add_subparser(sub: argparse._SubParsersAction) -> None:
     prst.add_argument("id", metavar="path")
     prst.set_defaults(func=_reset)
 
+    prm = g.add_parser("rm", help="remove a local capability")
+    prm.add_argument("id", metavar="path")
+    prm.set_defaults(func=_rm)
+
     pse = g.add_parser("search", help="search names + bodies")
     pse.add_argument("query")
     pse.set_defaults(func=_search)

{tcw_cli-2.1.1 → tcw_cli-2.1.3}/tcw/store/base.py

@@ -14,6 +14,7 @@ extracted in Phase 4 — not pre-abstracted here.
 # time. Python 3.14 defers natively (PEP 649); this keeps <3.14 working too.
 from __future__ import annotations
 
+import copy
 import re
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -287,24 +288,27 @@ class ProjectRegistry(ABC):
 
 def declared_capabilities(capabilities: Any) -> dict[str, list[str]]:
     """Canonical read of a work item's ``capabilities.yaml`` into
-    ``{"new": [...], "changed": [...]}`` — the work→capability back-pointers the
-    DoD gate enforces.
+    ``{"new": [...], "changed": [...], "removed": [...]}`` — the work→capability
+    back-pointers the DoD gate enforces.
 
     ``capabilities`` is the already-parsed sidecar object (``WorkItem.capabilities``):
-    a mapping with ``new:``/``changed:`` lists of canonical ``namespace/path``
-    strings. ``added:`` is accepted as a deprecated alias of ``new:``. A trailing
+    a mapping with ``new:``/``changed:``/``removed:`` lists of canonical
+    ``namespace/path`` strings. ``removed:`` names capabilities the item deleted,
+    which cannot sit under ``changed:`` because they no longer resolve.
+    ``added:`` is accepted as a deprecated alias of ``new:``. A trailing
     `` # comment`` on a value is stripped (YAML strips it already; belt and
     suspenders). The reconcile list-form sidecar and any other shape declare
     nothing here. The ``_tcw_parse_error`` sentinel the FS adapter produces on bad
     YAML raises ``SidecarError`` so the gate fails closed rather than reading
     "no deltas".
     """
-    out: dict[str, list[str]] = {"new": [], "changed": []}
+    out: dict[str, list[str]] = {"new": [], "changed": [], "removed": []}
     if not capabilities or not isinstance(capabilities, dict):
         return out
     if "_tcw_parse_error" in capabilities:
         raise SidecarError(str(capabilities["_tcw_parse_error"]))
-    for key, bucket in (("new", "new"), ("added", "new"), ("changed", "changed")):
+    for key, bucket in (("new", "new"), ("added", "new"), ("changed", "changed"),
+                        ("removed", "removed")):
         vals = capabilities.get(key)
         if vals is None:
             continue
@@ -564,13 +568,27 @@ class CapabilitiesStore(ABC):
 
     @abstractmethod
     def remove(self, identifier: str) -> None:
-        ...
+        """Delete the local capability at `identifier`, writing nothing when
+        refused. Raise `AmbiguousRef` when a bare ref matches multiple extended
+        stores, and `ValueError` when:
+
+        - nothing resolves;
+        - the capability is inherited, overridden locally or not (an override
+          is dropped with `reset`, never with `remove`);
+        - another capability or override is nested under its path;
+        - another local capability or override still references it through
+          `Superseded by`, `Blocked by`, `Roles` or `When`.
+
+        Refusing rather than cascading is the contract: a delete never takes a
+        second capability with it or leaves a reference pointing at nothing.
+        Never mutates an extended store."""
 
     @abstractmethod
     def reset(self, identifier: str) -> None:
         """Drop the local override at `identifier`, re-inheriting the upstream
         capability verbatim. Raise `ValueError` when there is no override (a
-        standalone local capability is not an override — use `remove`; a bare
+        standalone local capability is not an override — the `remove` operation,
+        driven by `tcw capabilities rm`, deletes it; a bare
         inherited path has nothing to drop), or `AmbiguousRef` when a bare ref
         matches multiple extended stores. Never mutates an extended store."""
 
@@ -926,7 +944,7 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
 
     problems: list[str] = []
 
-    for key in sorted(set(raw) - TRACKER_KEYS):
+    for key in sorted(set(raw) - TRACKER_KEYS, key=str):
         problems.append(f"work.tracker.{key}: unknown key")
 
     def required_str(key: str) -> str:
@@ -957,7 +975,7 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
             problems.append(f"work.tracker.{key}: expected a mapping, "
                             f"got {type(value).__name__}")
             return {}
-        for sub in sorted(set(value) - allowed):
+        for sub in sorted(set(value) - allowed, key=str):
             problems.append(f"work.tracker.{key}.{sub}: unknown key")
         return value
 
@@ -1004,6 +1022,135 @@ def parse_tracker_config(raw: Any) -> tuple["TrackerConfig | None", list[str]]:
     ), []
 
 
+TrackerKeyPath = tuple[Any, ...]
+
+
+def merge_tracker_blocks(
+    blocks: list[tuple[str, Any]],
+) -> tuple[Any, dict[TrackerKeyPath, str], str | None]:
+    """Lay `work.tracker` blocks over each other, nearest first, key by key.
+
+    Pure, like `parse_tracker_config`: the caller gathers the blocks from its own
+    project graph, so a store that is not a filesystem merges the same way. Each
+    block is `(label, raw)`, and labels must be distinct — the node itself first,
+    then its ancestors, direct parent first. Whether a node takes part at all
+    (opt-in) is the caller's decision; this only merges what it is given.
+
+    Returns `(merged, record, whole_block_label)`:
+
+    - `merged` goes to `parse_tracker_config` unchanged.
+    - `record` maps each key path in `merged` to the label that supplied its
+      value. A nearer null that let a farther value show through does not move
+      it: the credentials rule reads it, and naming the null's file there would
+      let a token follow a changed `base-url`.
+    - `whole_block_label` is set when an ancestor's block is not a mapping. The
+      merge stops there and returns that block, so the parser's "expected a
+      mapping" is reported against the ancestor and every node beneath it fails
+      closed.
+    """
+    if not blocks:
+        return None, {}, None
+    own = blocks[0][1]
+    if not isinstance(own, dict):
+        return own, {}, None
+    layers = [blocks[0]]
+    for label, raw in blocks[1:]:
+        if raw is None or raw == {}:
+            continue
+        if not isinstance(raw, dict):
+            return raw, {}, label
+        layers.append((label, raw))
+
+    merged: dict = {}
+    record: dict[TrackerKeyPath, str] = {}
+    for label, raw in reversed(layers):
+        _lay_tracker_block(merged, copy.deepcopy(raw), label, (), record)
+    return merged, record, None
+
+
+def _lay_tracker_block(target: dict, source: dict, label: str,
+                       path: TrackerKeyPath, record: dict[TrackerKeyPath, str]) -> None:
+    for key, value in source.items():
+        key_path = (*path, key)
+        if value is None:
+            if key not in target:          # nothing farther: kept, for the parser
+                target[key] = None
+                record[key_path] = label
+            continue                       # otherwise the farther value shows through
+        if isinstance(value, dict) and isinstance(target.get(key), dict):
+            record[key_path] = label
+            _lay_tracker_block(target[key], value, label, key_path, record)
+            continue
+        for stale in [p for p in record if p[:len(key_path)] == key_path]:
+            del record[stale]
+        target[key] = value
+        record[key_path] = label
+        if isinstance(value, dict):
+            _record_tracker_paths(value, label, key_path, record)
+
+
+def _record_tracker_paths(block: dict, label: str, path: TrackerKeyPath,
+                          record: dict[TrackerKeyPath, str]) -> None:
+    for key, value in block.items():
+        key_path = (*path, key)
+        record[key_path] = label
+        if isinstance(value, dict):
+            _record_tracker_paths(value, label, key_path, record)
+
+
+def tracker_credentials_problem(record: dict[TrackerKeyPath, str],
+                                labels: list[str]) -> str | None:
+    """A problem when `credentials` came from farther up than `base-url`.
+
+    `JiraClient` sends a token built from the named variables to whatever
+    `base-url` names. Before inheritance both sat in one block, so whoever chose
+    the site chose the token. This keeps that true: a node that sets `base-url`
+    also sets `credentials`, even when the URL repeats its parent's. Credentials
+    partly inherited count by their farthest key. Run on a config that parsed.
+    """
+    position = {label: index for index, label in enumerate(labels)}
+    base_url = record.get(("base-url",))
+    credentials = [label for key_path, label in record.items()
+                   if len(key_path) > 1 and key_path[0] == "credentials"]
+    if base_url is None or not credentials:
+        return None
+    if max(position[label] for label in credentials) <= position[base_url]:
+        return None
+    return (f"work.tracker.credentials: inherited from a parent node, but base-url "
+            f"is set nearer, in {base_url}; set credentials in the same file as "
+            f"base-url")
+
+
+def attribute_tracker_problems(problems: list[str], record: dict[TrackerKeyPath, str],
+                               own_label: str, whole_block_label: str | None) -> list[str]:
+    """Prefix each parser problem with the label of the file that caused it.
+
+    Matched on the problem's exact key path, never the nearest enclosing
+    mapping: `transitions.claim: required` under a `transitions` an ancestor
+    supplied is about a key nobody set, and goes to `own_label`. The parser
+    writes a path as its keys joined with `.` followed by `: `, so the longest
+    recorded path whose spelling prefixes the problem that way is the one it is
+    about — which also holds for a key whose own name contains `.` or `: `.
+
+    Two recorded paths can share a spelling (an integer key `5` and a string key
+    `"5"`, or a key named `credentials.x` beside a nested one). Such a block is
+    already invalid and every problem is still reported; only the file named for
+    it may be the other one's.
+    """
+    spelled = sorted(((".".join(map(str, key_path)), label)
+                      for key_path, label in record.items()),
+                     key=lambda entry: len(entry[0]), reverse=True)
+    attributed = []
+    for problem in problems:
+        if problem.startswith("work.tracker: "):
+            label = whole_block_label or own_label
+        else:
+            label = next((label for spelling, label in spelled
+                          if problem.startswith(f"work.tracker.{spelling}: ")), own_label)
+        attributed.append(f"{label}: {problem}")
+    return attributed
+
+
 @dataclass(frozen=True)
 class RepositoryDeclaration:
     """Where a component store comes from, as the project records it.
@@ -1940,6 +2087,16 @@ WORK_SIDECARS: dict[str, dict[str, str]] = {
         "media_type": "text/markdown",
         "generated": "yes",
     },
+    # The binding between an item and the tracker ticket it answers. Written by
+    # `tcw work tracker import | link | unlink`, never by hand, so it is
+    # `generated` like `rollup.md` and edit surfaces must not offer to write it.
+    # Nothing treats it as proof that a claim was made: every command that acts on
+    # a binding re-reads the ticket from the tracker.
+    "tracker.yaml": {
+        "media_type": "application/yaml",
+        "validation": "yaml_mapping",
+        "generated": "yes",
+    },
 }
 
 # Taxonomy term fields that the abstract ``update_term`` operation may modify.
@@ -2258,6 +2415,11 @@ class WorkStore(ABC):
     def tracker_config(self) -> "TrackerConfig | None":
         """The node's external-tracker settings, or `None` when none is configured.
 
+        A node whose own `work.tracker` is a non-empty mapping inherits the keys it
+        does not set from its ancestors: an adapter gathers their blocks from its
+        project graph, lays them with `merge_tracker_blocks`, parses the result,
+        and refuses a config `tracker_credentials_problem` objects to.
+
         Problems discarded, so a malformed key can never break a board read. Fails
         *closed*: the parser returns `None` on any problem, so a half-read config
         is one nobody declared. `tracker_problems` is where a user learns why.