tcw-cli 2.6.0__tar.gz → 2.6.1__tar.gz

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.0
+Version: 2.6.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -727,7 +727,7 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket and puts the ticket back where it was, still assigned to you. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
 | an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
@@ -797,9 +797,9 @@ e-mail address or token themselves.
 
 ```sh
 tcw work tracker list                  # TCW: lists tickets the query selects.   Jira: unchanged
-tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 → In Progress, assigned to you
+tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 stays in To Do, assigned to you
 #   …the request, spec and plan stages run as usual…
-tcw work start <slug>                   # TCW: backlog → active.                  Jira: confirms the claim import made
+tcw work start <slug>                   # TCW: backlog → active.                  Jira: ENG-482 → In Progress
 tcw work submit <slug>                  # TCW: active → review.                   Jira: ENG-482 → In Review
 tcw work complete <slug> --resolution done --confirm
                                         # TCW: review → completed.                Jira: ENG-482 → Done

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/README.md

@@ -511,7 +511,7 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket and puts the ticket back where it was, still assigned to you. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
 | an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
@@ -581,9 +581,9 @@ e-mail address or token themselves.
 
 ```sh
 tcw work tracker list                  # TCW: lists tickets the query selects.   Jira: unchanged
-tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 → In Progress, assigned to you
+tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 stays in To Do, assigned to you
 #   …the request, spec and plan stages run as usual…
-tcw work start <slug>                   # TCW: backlog → active.                  Jira: confirms the claim import made
+tcw work start <slug>                   # TCW: backlog → active.                  Jira: ENG-482 → In Progress
 tcw work submit <slug>                  # TCW: active → review.                   Jira: ENG-482 → In Review
 tcw work complete <slug> --resolution done --confirm
                                         # TCW: review → completed.                Jira: ENG-482 → Done

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tcw-cli"
-version = "2.6.0"
+version = "2.6.1"
 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.6.1/tcw/__init__.py

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

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tcw/tracker/intake.py

@@ -445,6 +445,9 @@ class ClaimOutcome:
     # when no such step ran. Set on success and on a refusal alike: either way the
     # ticket has left triage, and the caller has to say so (`moved_out`).
     left_status: str = ""
+    # The status the claim found the ticket in, after any `pre-backlog` step: where
+    # `import` puts a ticket its claim moved (`put_back`). Set only on a claim.
+    claimed_from: str = ""
 
 
 def _fields(issue: dict) -> tuple[str, str, str, str]:
@@ -625,7 +628,8 @@ def claim(client, ticket: TicketRead) -> ClaimOutcome:
         if left:
             error.left_status = left
         raise
-    return replace(outcome, left_status=left)
+    return replace(outcome, left_status=left,
+                   claimed_from=ticket.status if outcome.claimed else "")
 
 
 def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
@@ -745,3 +749,47 @@ def _claim_from(client, ticket: TicketRead) -> ClaimOutcome:
     return refused("3f", f"could not tell whether this run's claim applied: {key} is "
                          f"in '{now_status}', unassigned. Check the ticket's history "
                          f"in the tracker before assigning it.", detail)
+
+
+def put_back(client, outcome: ClaimOutcome) -> tuple[str, str]:
+    """Move a ticket this run's claim took back to `outcome.claimed_from`, where the
+    claim found it. `import` does this once its backlog item exists, so the ticket
+    does not say the work has started while the item says it has not.
+
+    The claim's own transition is what kept a second claimant out, so it is taken
+    first and only undone here, after the item is bound. The way back is the one
+    transition the ticket offers to that status, chosen as a lifecycle move with no
+    named transition chooses it (`assess_move`); none, or more than one, sends
+    nothing.
+
+    Returns `(the status the ticket is in, why it is not back or "")`. Never raises a
+    tracker error: by now the item exists, so a ticket left where the claim put it is
+    something to report, not a reason to fail.
+    """
+    from tcw.tracker.claim import _normalize
+    from tcw.tracker.jira import TrackerError
+    from tcw.tracker.sync import CURRENT, assess_move
+
+    target = outcome.claimed_from
+    try:
+        ticket = read_ticket(client, outcome.issue_id)
+        state, found = assess_move(ticket, target=target, expected=(), move=None)
+        if state == CURRENT:
+            return ticket.status, ""
+        if state != "apply":
+            return ticket.status, found
+        client.apply_transition(ticket.issue_id, found.id)
+        status = _fields(client.issue(ticket.issue_id))[0]
+    except TrackerError as error:
+        # The transition may have landed with its answer lost, so where the ticket
+        # is has to be read rather than assumed.
+        try:
+            status = _fields(client.issue(outcome.issue_id))[0]
+        except TrackerError:
+            return outcome.status, f"{error}; where it is now could not be read"
+        if _normalize(status) == _normalize(target):
+            return status, ""
+        return status, str(error)
+    if _normalize(status) != _normalize(target):
+        return status, f"it is in '{status}' after '{found.name}'"
+    return status, ""

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tcw/work/cli.py

@@ -2600,11 +2600,13 @@ def _tracker_import(args: argparse.Namespace, label: str = "tracker import",
     locally is finished by running the command again: the ticket is then already
     assigned to this account, which the claim accepts without a second transition.
     """
+    from dataclasses import replace
     from datetime import date
 
+    from tcw.tracker.claim import _normalize
     from tcw.tracker.intake import (BINDING_SIDECAR, BindingProblem, claim,
                                     find_binding, moved_out, pre_backlog_hint,
-                                    read_ticket, validate_part)
+                                    put_back, read_ticket, validate_part)
     from tcw.tracker.jira import TrackerError
 
     client = _tracker_client(label)
@@ -2706,8 +2708,28 @@ def _tracker_import(args: argparse.Namespace, label: str = "tracker import",
         print(f"tcw work {label}: claimed {outcome.key}, but the binding could "
               f"not be written: {e}. Run this command again.", file=sys.stderr)
         return 1
+    # The item is in the backlog, so a ticket this run's claim moved goes back where
+    # the claim found it. Only now: every failure above is finished by running the
+    # command again, which finds the ticket already assigned (row `1e`) and moves
+    # nothing — so a ticket put back earlier would be left claimed with no item.
+    # Not under strict mode, whose proof that nobody else can claim the ticket is
+    # that it sits where the exclusive transition led. Only for a ticket this run's
+    # transition moved: a claim can also count when somebody else moved a ticket
+    # already yours (row `3a` with a refused transition), and that is work under way,
+    # not a move of ours to undo. And not for a ticket still where the claim found
+    # it, which saves an already-held ticket (row `1e`) the tracker reads — a failure
+    # in them would warn about work nobody moved.
+    put_back_failed = ""
+    if (outcome.transitioned and outcome.claimed_from and not client.config.strict
+            and _normalize(outcome.claimed_from) != _normalize(outcome.status)):
+        status, put_back_failed = put_back(client, outcome)
+        outcome = replace(outcome, status=status)
     print(slug)
     print(f"→ {_claim_summary(outcome)}; bound to {slug}", file=sys.stderr)
+    if put_back_failed:
+        print(f"warning: {outcome.key} stays in '{outcome.status}', although its item "
+              f"is in the backlog: {put_back_failed.rstrip('.')}. Move it back in the "
+              f"tracker, or leave it until the item starts.", file=sys.stderr)
     if not outcome.transitioned:
         print(f"→ {outcome.message}", file=sys.stderr)
     if outcome.row == "1e" and (hint := pre_backlog_hint(client.config, outcome.status,

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tcw_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.0
+Version: 2.6.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -727,7 +727,7 @@ to the transitions.
 
 | Lifecycle step                          | Without Jira                   | With Jira configured                                                                                                                           |
 | --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
+| an item is created                      | `tcw work inbox accept`, `new` | `tcw work tracker import <ticket>` claims the ticket (starts it and assigns it to you), then creates a backlog item whose intake is the ticket and puts the ticket back where it was, still assigned to you. With `inbox-query` set, `tcw work inbox accept <ticket>` does the same |
 | `request`, `spec`, `plan` stages        | unchanged                      | unchanged                                                                                                                                      |
 | at any time                             | —                              | `tcw work tracker link` / `unlink` records or removes the link between an existing item and a ticket; Jira itself is not touched               |
 | an item has no ticket                   | —                              | `tcw work tracker create <slug>` makes one for it and binds it; `--all` sweeps every open item without one. Needs `work.tracker.create` and `statuses.backlog`. With `create.on-new`, filing an item makes its ticket |
@@ -797,9 +797,9 @@ e-mail address or token themselves.
 
 ```sh
 tcw work tracker list                  # TCW: lists tickets the query selects.   Jira: unchanged
-tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 → In Progress, assigned to you
+tcw work tracker import ENG-482         # TCW: creates a backlog item.            Jira: ENG-482 stays in To Do, assigned to you
 #   …the request, spec and plan stages run as usual…
-tcw work start <slug>                   # TCW: backlog → active.                  Jira: confirms the claim import made
+tcw work start <slug>                   # TCW: backlog → active.                  Jira: ENG-482 → In Progress
 tcw work submit <slug>                  # TCW: active → review.                   Jira: ENG-482 → In Review
 tcw work complete <slug> --resolution done --confirm
                                         # TCW: review → completed.                Jira: ENG-482 → Done

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tcw_cli.egg-info/SOURCES.txt

@@ -161,6 +161,7 @@ tests/test_tracker_gate.py
 tests/test_tracker_help.py
 tests/test_tracker_hold.py
 tests/test_tracker_import.py
+tests/test_tracker_import_returns.py
 tests/test_tracker_inheritance.py
 tests/test_tracker_link.py
 tests/test_tracker_ownership.py

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tests/test_tracker_claim.py

@@ -74,6 +74,16 @@ def test_a_ready_unassigned_ticket_is_transitioned_then_assigned(fake, alice):
     assert outcome.url == f"{BASE_URL}/browse/TCWCLAIM-6"
 
 
+def test_a_claim_records_the_status_it_found_the_ticket_in(fake, alice):
+    """What `import` puts the ticket back to once its item exists."""
+    assert _claim(alice).claimed_from == "To Do"
+
+
+def test_a_refused_claim_records_no_status(fake, alice):
+    fake.tickets["10052"].assignee = B
+    assert _claim(alice).claimed_from == ""
+
+
 def test_the_key_the_user_typed_resolves_to_the_canonical_one(fake, alice):
     assert _claim(alice, "tcwclaim-6").key == "TCWCLAIM-6"
 

tcw_cli-2.6.1/tests/test_tracker_import_returns.py

@@ -0,0 +1,162 @@
+"""`import` and `inbox accept` put a ticket their claim moved back where the claim
+found it, so it reads as not started, like the backlog item they create.
+
+The claim itself still moves the ticket first: that transition is what keeps two
+people importing the same ticket apart. Only once the item exists and is bound is
+the ticket put back — and only when this run moved it, never under strict mode, and
+never at the cost of the import: a ticket that cannot go back is a warning.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tcw.store.fs import FsWorkStore
+from tcw.tracker.jira import TrackerUnavailable
+from test_tracker_pre_backlog import TRIAGE, post_fails, set_pre_backlog
+from test_tracker_strict import set_tracker_key, strict_node
+from test_tracker_sync import A, KEY, SENTINEL, TICKET_ID, cli, ladder_node
+from tracker_fake import SYNC, FakeJira
+
+STOP = ("71", "Stop", "To Do")
+# `SYNC` with a way back from the working statuses to the backlog, as the TCW Jira
+# workflow has had since 2026-09-24.
+WITH_STOP = {**SYNC, "In Progress": [*SYNC["In Progress"], STOP],
+             "In Review": [*SYNC["In Review"], STOP]}
+START, BACK = "21", "71"
+TRANSITIONS = f"/rest/api/3/issue/{TICKET_ID}/transitions"
+ASSIGNEE = f"/rest/api/3/issue/{TICKET_ID}/assignee"
+
+
+def items(root):
+    return FsWorkStore.open(root).board()
+
+
+def ticket(fake_):
+    t = fake_.tickets[TICKET_ID]
+    return t.status, t.assignee
+
+
+def warnings(err: str) -> list[str]:
+    return [line for line in err.splitlines() if line.startswith("warning:")]
+
+
+@pytest.mark.parametrize("verb", [("tracker", "import"), ("inbox", "accept")])
+def test_the_ticket_goes_back_to_where_the_claim_found_it(tmp_path, monkeypatch, verb):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP))
+    set_tracker_key(root, "inbox-query", "project = SYNC")
+    code, out, err = cli(root, "work", *verb, KEY)
+    assert code == 0, err
+    [item] = items(root)
+    assert item.status == "backlog" and item.tracker is not None
+    assert ticket(fake_) == ("To Do", A)
+    assert fake_.applied == [START, BACK]
+    assert fake_.writes() == [("POST", TRANSITIONS), ("PUT", ASSIGNEE),
+                              ("POST", TRANSITIONS)]
+    assert f"{KEY} is in 'To Do', claimed by this run" in err
+    assert warnings(err) == []
+
+
+def test_a_ticket_taken_out_of_triage_goes_back_to_the_backlog_not_triage(
+        tmp_path, monkeypatch):
+    workflow = {**TRIAGE, "In Progress": [*TRIAGE["In Progress"], STOP]}
+    root, fake_ = ladder_node(tmp_path, monkeypatch, workflow, status="Triage")
+    set_pre_backlog(root, {"Triage": "Accept"})
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    assert ticket(fake_) == ("To Do", A)
+    assert fake_.applied == ["11", START, BACK]
+
+
+def test_a_ticket_already_yours_and_under_way_is_left_alone(tmp_path, monkeypatch):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP),
+                              status="In Progress", assignee=A)
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    assert len(items(root)) == 1
+    assert ticket(fake_) == ("In Progress", A)
+    assert fake_.writes() == []
+    # Not even asked about: the claim's own read is the only one, so a tracker that
+    # fails afterwards cannot turn work already under way into a warning.
+    assert [p for m, p, _a in fake_.requests
+            if m == "GET" and p == TRANSITIONS] == [TRANSITIONS]
+
+
+def test_a_workflow_with_no_way_back_warns_and_still_imports(tmp_path, monkeypatch):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(SYNC))
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    [item] = items(root)
+    assert item.tracker is not None
+    assert ticket(fake_) == ("In Progress", A)
+    assert fake_.applied == [START]
+    [warning] = warnings(err)
+    assert KEY in warning and "'In Progress'" in warning and "backlog" in warning
+    assert ".." not in warning
+    assert f"{KEY} is in 'In Progress', claimed by this run" in err
+
+
+def test_a_tracker_error_on_the_way_back_warns_and_still_imports(tmp_path, monkeypatch):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP))
+    post_fails(fake_, 2, TrackerUnavailable("the tracker went away (fake)"))
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    [item] = items(root)
+    assert item.tracker is not None
+    assert ticket(fake_) == ("In Progress", A)
+    [warning] = warnings(err)
+    assert KEY in warning and "went away" in warning
+
+
+def test_strict_mode_leaves_the_ticket_where_the_claim_put_it(tmp_path, monkeypatch):
+    monkeypatch.setenv("TCW_A_EMAIL", "a@example.test")
+    monkeypatch.setenv("TCW_PROBE_TOKEN", SENTINEL)
+    monkeypatch.setenv("TCW_WORK_OWNER", "a@example.test")
+    fake_ = FakeJira(workflow=dict(WITH_STOP))
+    fake_.account("a@example.test", A, "Alice")
+    fake_.ticket(id=TICKET_ID, key=KEY, summary="t")
+    fake_.install(monkeypatch)
+    root = strict_node(tmp_path, strict=True, claim_transition="Start Progress")
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    assert len(items(root)) == 1
+    assert ticket(fake_) == ("In Progress", A)
+    assert fake_.applied == [START]
+
+
+def test_a_ticket_moved_by_someone_else_during_the_claim_is_left_alone(
+        tmp_path, monkeypatch):
+    """The claim still counts — the ticket is yours and where the claim leads — but
+    this run's transition did not move it: somebody else did. That is work under
+    way, not a move of ours to undo."""
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP), assignee=A)
+
+    def moved_first():
+        fake_.tickets[TICKET_ID].status = "In Progress"
+
+    fake_.before("POST", "/transitions", moved_first)
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    assert len(items(root)) == 1
+    assert ticket(fake_) == ("In Progress", A)
+    assert fake_.applied == []
+
+
+def test_an_unanswered_way_back_reports_where_the_ticket_really_is(tmp_path, monkeypatch):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP))
+    post_fails(fake_, 2, TrackerUnavailable("no answer (fake)"), apply_first=True)
+    code, _out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    assert ticket(fake_) == ("To Do", A)
+    assert f"{KEY} is in 'To Do', claimed by this run" in err
+    assert warnings(err) == []
+
+
+def test_starting_an_imported_item_moves_its_ticket_on(tmp_path, monkeypatch):
+    root, fake_ = ladder_node(tmp_path, monkeypatch, dict(WITH_STOP))
+    code, out, err = cli(root, "work", "tracker", "import", KEY)
+    assert code == 0, err
+    code, _out, err = cli(root, "work", "start", out.strip())
+    assert code == 0, err
+    assert ticket(fake_) == ("In Progress", A)
+    assert fake_.applied == [START, BACK, START]

{tcw_cli-2.6.0 → tcw_cli-2.6.1}/tests/test_tracker_pre_backlog.py

@@ -157,6 +157,11 @@ def test_an_unassigned_triage_ticket_is_accepted_then_claimed(fake):
     assert (fake.tickets[ID].status, fake.tickets[ID].assignee) == ("In Progress", A)
 
 
+def test_a_triage_ticket_is_recorded_as_found_in_the_backlog_status(fake):
+    """The step's landing, not Triage: an import puts the ticket back there."""
+    assert _claim().claimed_from == "To Do"
+
+
 def test_a_triage_ticket_already_yours_is_accepted_then_claimed(fake):
     """The reporter's case: a creator is often the ticket's assignee, and today that
     is row 1e — "already held" — with the ticket left in Triage."""
@@ -661,7 +666,9 @@ def test_import_of_a_triage_ticket_already_yours(tmp_path, monkeypatch):
     code, _out, err = cli(root, "work", "tracker", "import", KEY)
     assert code == 0, err
     assert fake_.applied == ACCEPT_THEN_START
-    assert "warning:" not in err
+    # No "stays in Triage" warning. `TRIAGE` offers no way back from In Progress,
+    # so the ticket's own put-back warning is expected and is not what this is about.
+    assert "stays in 'Triage'" not in err and HINT not in err
 
 
 def test_without_the_setting_import_of_a_triage_ticket_already_yours_warns(tmp_path,

tcw_cli-2.6.0/tcw/__init__.py

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