tcw-cli 2.7.0__tar.gz → 2.8.1__tar.gz

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.7.0
+Version: 2.8.1
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -688,9 +688,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -702,7 +702,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; its worktree holds commits on no branch; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/README.md

@@ -472,9 +472,9 @@ The stages, and the document each one writes:
 | Stage        | Runs while the item is | Writes                                                            |
 | ------------ | ---------------------- | ----------------------------------------------------------------- |
 | `inbox`      | not yet an item        | nothing; it creates the item, keeping the raw text as `intake.md` |
-| `request`    | backlog                | `initial-request.md`: what is asked for, and why                  |
-| `spec`       | backlog                | `spec.md`: what to build, with acceptance criteria                |
-| `plan`       | backlog                | `plan.md`: how to build it, as ordered tasks                      |
+| `request`    | backlog (or active)    | `initial-request.md`: what is asked for, and why                  |
+| `spec`       | backlog (or active)    | `spec.md`: what to build, with acceptance criteria                |
+| `plan`       | backlog (or active)    | `plan.md`: how to build it, as ordered tasks                      |
 | `implement`  | active                 | `outcome.md`: what was built, and what the plan got wrong         |
 | `verify`     | review (or active)     | `refined-outcome.md` if accepted, `rework.md` if not              |
 | `postmortem` | review or completed    | `post-mortem.md`: which stage could first have caught a problem   |
@@ -486,7 +486,7 @@ The transitions, and what each one checks before it moves an item:
 | `start`      | `tcw work start <slug>`                                                          | backlog → active                      | a blocker is unresolved; the item belongs to an epic that is not active                                                                   |
 | `submit`     | `tcw work submit <slug>`                                                         | active → review                       | never                                                                                                                                     |
 | `rework`     | `tcw work rework <slug>`                                                         | review → active                       | `refined-outcome.md` is present (it says the work was accepted)                                                                           |
-| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; the item's folder in its worktree has uncommitted changes; no `--confirm` |
+| `complete`   | `tcw work complete <slug> --resolution done --confirm`                           | review or active → completed          | a blocker is unresolved; an epic has open children; declared capabilities are not reconciled; a worktree merge-back fails; with `--already-integrated`, the branch is not merged into `HEAD`; the item's folder in its worktree has uncommitted changes; its worktree holds commits on no branch; no `--confirm` |
 | discard      | `tcw work complete <slug> --resolution wontfix\|duplicate\|superseded --confirm` | backlog, active or review → discarded | no `--confirm`                                                                                                                            |
 | `drop`       | `tcw work drop <slug> --confirm`                                                 | backlog → removed                     | the item is not in backlog; no `--confirm`                                                                                                |
 | not retained | happens during `complete` or discard                                             | completed or discarded → removed      | only happens when `work.retain` says that status is not kept; `tcw work delete` finishes one that was interrupted                         |

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/pyproject.toml

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

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

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/tcw/cli.py

@@ -10,6 +10,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from tcw.cli_suggest import SuggestingParser, attach_index
 from tcw import __version__
 from tcw.capabilities import cli as capabilities_cli
 from tcw.serve import DEFAULT_PORT, serve
@@ -18,7 +19,9 @@ from tcw.store.fs import (
     FsWorkStore, declared_repository, find_node_root, git_root, init,
     provisioned_store_root,
 )
+from tcw.store.base import MultipleMatch
 from tcw.store.project import FsProjectRegistry
+from tcw.store.yaml_source import load as _load_named_yaml
 import yaml
 from tcw.taxonomy import cli as taxonomy_cli
 from tcw.work import cli as work_cli
@@ -55,7 +58,8 @@ def run_init(components: list[str], project_id: str | None = None,
     sentinel = root / SENTINEL
     if project_id is None:
         try:
-            configured = yaml.safe_load(sentinel.read_text(encoding="utf-8")) if sentinel.exists() else {}
+            configured = (_load_named_yaml(sentinel.read_text(encoding="utf-8"), sentinel)
+                          if sentinel.exists() else {})
         except yaml.YAMLError as error:
             print(f"tcw init: invalid {SENTINEL}: {error}", file=sys.stderr)
             return 1
@@ -479,7 +483,7 @@ def _cmd_serve(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
+    parser = SuggestingParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
     parser.add_argument("--version", action="version", version=f"tcw {__version__}")
     sub = parser.add_subparsers(dest="group", required=True)
 
@@ -528,6 +532,7 @@ def build_parser() -> argparse.ArgumentParser:
         p = sub.add_parser(name, help=f"{name} commands (not yet implemented)")
         p.set_defaults(func=_not_yet(name))
 
+    attach_index(parser)
     return parser
 
 
@@ -546,7 +551,10 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(_normalize(argv))
     try:
         return args.func(args)
-    except ValueError as error:
+    except (ValueError, MultipleMatch) as error:
+        # `MultipleMatch` is not a `ValueError`, so a verb that does not catch it
+        # itself — `start`, `submit` — printed a traceback for a slug two folders
+        # hold. Its message names both folders; this is only the safety net.
         print(f"tcw: {error}", file=sys.stderr)
         return 1
     except yaml.YAMLError as error:
@@ -555,14 +563,14 @@ def main(argv: list[str] | None = None) -> int:
         # twenty-odd `load_yaml` calls that do not catch it: refusing is already
         # the right answer at every one of them — `init` must not overwrite a
         # config it cannot read — and only the presentation was wrong. The
-        # loader's message names the file.
+        # loader's message names the file (`tcw.store.yaml_source.load`).
         print(f"tcw: {error}", file=sys.stderr)
         return 1
     except subprocess.CalledProcessError as error:
         # Deliberately generic: the only policy here is "a git subprocess
-        # failed", which is true of every component. git's own diagnostic has
-        # already reached the terminal — no `check=True` call in the filesystem
-        # adapter captures output — so re-printing `error.stderr` would double it.
+        # failed", which is true of every component. The index-touching calls
+        # capture git's output (so a retried failure does not print once per
+        # try), and it is printed here; an uncaptured call has already shown it.
         # `cmd` is a sequence *or* a string (stdlib contract); joining a string
         # iterates its characters. No shipped raiser passes one, but a handler
         # whose whole justification is that it assumes nothing about its caller
@@ -571,6 +579,8 @@ def main(argv: list[str] | None = None) -> int:
             shlex.join(str(a) for a in error.cmd)
         print(f"tcw: git command failed (exit {error.returncode}): {cmd}",
               file=sys.stderr)
+        if isinstance(error.stderr, str) and error.stderr.strip():
+            print(error.stderr.rstrip("\n"), file=sys.stderr)
         return 1
 
 

tcw_cli-2.8.1/tcw/cli_suggest.py

@@ -0,0 +1,199 @@
+"""Answer a mistyped subcommand with the command that was probably meant.
+
+argparse reports a wrong subcommand by listing every valid choice at that level,
+which says nothing when the word exists one level down (`tcw tracker` for
+`tcw work tracker`) or is a synonym (`status` for `show`). `SuggestingParser`
+keeps argparse's message word for word and adds one line after it.
+
+Three rules, first match wins:
+
+1. The word is a subcommand somewhere else in the tree: name each full command,
+   and complete it with the word that followed when that is wrong there too —
+   `tcw tracker status` → `tcw work tracker show`.
+2. A small table of synonyms, offered only where their target is valid.
+3. Close spellings among the choices valid at that level.
+
+Only subcommands that `--help` lists are ever offered. That is what keeps the
+removed `tcw work stage <id>` spellings — registered without `help=` so that the
+old form can print its replacement — out of every suggestion, without naming
+them here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+
+# One clear target each. Words for removal are left out on purpose: `drop`,
+# `delete` and `rm` destroy things, and pointing at one is worse than no hint.
+SYNONYMS: dict[str, tuple[str, ...]] = {
+    "status": ("show", "list"),
+    "info": ("show",),
+    "view": ("show",),
+    "get": ("show",),
+    "cat": ("show",),
+    "ls": ("list",),
+}
+
+# Never offered by any rule, and never answered either: pointing somebody at a
+# command that destroys things, when they typed something else, is worse than
+# no hint — and so is guessing what a mistyped removal was meant to remove
+# (`tcw work tracker delete` is not `tcw work delete`, which deletes an item).
+REMOVAL = frozenset({"rm", "drop", "delete"})
+
+_MAX = 3
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def visible_choices(action: argparse._SubParsersAction) -> list[str]:
+    """The subcommands this action lists in its help, in its own order."""
+    listed = {choice.dest for choice in action._choices_actions}
+    return [name for name in action.choices if name in listed]
+
+
+def _offered(word: str, choices: list[str]) -> list[str]:
+    """Rules 2 and 3 for one level: synonyms valid here, else close spellings."""
+    safe = [c for c in choices if c not in REMOVAL]
+    synonyms = [s for s in SYNONYMS.get(word, ()) if s in safe]
+    if synonyms:
+        return synonyms
+    return difflib.get_close_matches(word, safe, n=_MAX, cutoff=0.6)
+
+
+def _command(path: tuple[str, ...]) -> str:
+    return "`" + " ".join(path) + "`"
+
+
+def _phrase(commands: list[str]) -> str:
+    if len(commands) == 1:
+        return f"did you mean {commands[0]}?"
+    if len(commands) == 2:
+        return f"did you mean {commands[0]} or {commands[1]}?"
+    return f"did you mean one of {', '.join(commands)}?"
+
+
+class SuggestingParser(argparse.ArgumentParser):
+    """An `ArgumentParser` whose wrong-subcommand error suggests what was meant.
+
+    Every subparser gets this class too, since `add_subparsers` defaults to the
+    parent's. `attach_index` gives the whole tree what the hint needs."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Python 3.14 has argparse's own close-spelling hint. Off, explicitly,
+        # so a later default cannot print a second, different suggestion.
+        self.suggest_on_error = False
+
+    def parse_known_args(self, args=None, namespace=None):
+        # The root keeps what it was asked to parse: a nested parser reports its
+        # own error and needs the word after the one it rejected.
+        if getattr(self, "_tcw_root", None) is self:
+            self._tcw_argv = list(args) if args is not None else None
+        return super().parse_known_args(args, namespace)
+
+    def _check_value(self, action, value):
+        if not isinstance(action, argparse._SubParsersAction) or value in action.choices:
+            return super()._check_value(action, value)
+        choices = visible_choices(action)
+        hint = self._hint(str(value), choices)
+        if len(choices) == len(action.choices):
+            # Nothing hidden: argparse's own message, exactly as this Python
+            # version words it (3.12 and 3.13 leave the choices unquoted).
+            try:
+                super()._check_value(action, value)
+            except argparse.ArgumentError as error:
+                if not hint:
+                    raise
+                raise argparse.ArgumentError(action, f"{error.message}\n{hint}") from None
+        message = (f"invalid choice: {value!r} (choose from "
+                   f"{', '.join(repr(c) for c in choices)})")
+        if hint:
+            message += f"\n{hint}"
+        raise argparse.ArgumentError(action, message)
+
+    def _hint(self, word: str, choices: list[str]) -> str:
+        root = getattr(self, "_tcw_root", None)
+        here = getattr(self, "_tcw_path", None)
+        if root is None or here is None or word in REMOVAL:
+            return ""
+        # Same component first — `tcw work tags show` means a `tcw work …` show,
+        # not `tcw taxonomy show` — then shallowest: `tcw show` means
+        # `tcw work show` before `tcw work inbox show`. `sorted` is stable, so
+        # ties keep tree order.
+        elsewhere = sorted(
+            (p for p in root._tcw_index.get(word, ()) if p[:-1] != here),
+            key=lambda p: (-_shared(p, here), len(p)))
+        if elsewhere:
+            following = _following(root, here, word)
+            commands = []
+            for path in elsewhere[:_MAX]:
+                commands += [_command(path + tail) for tail in _completion(root, path, following)]
+            return _phrase(commands[:_MAX])
+        offered = _offered(word, choices)
+        return _phrase([_command(here + (o,)) for o in offered]) if offered else ""
+
+
+def _shared(path: tuple[str, ...], here: tuple[str, ...]) -> int:
+    """How many leading words `path` shares with `here`."""
+    n = 0
+    for a, b in zip(path, here):
+        if a != b:
+            break
+        n += 1
+    return n
+
+
+def _following(root: SuggestingParser, here: tuple[str, ...], word: str) -> str:
+    """The word after `word` on the command line, if it is not an option."""
+    argv = getattr(root, "_tcw_argv", None) or []
+    start = len(here) - 1                           # `here` includes "tcw"
+    for index in range(start, len(argv)):
+        if argv[index] == word:
+            after = argv[index + 1] if index + 1 < len(argv) else ""
+            return "" if after.startswith("-") else after
+    return ""
+
+
+def _completion(root: SuggestingParser, path: tuple[str, ...],
+                following: str) -> list[tuple[str, ...]]:
+    """How to finish `path` with the word typed after it: kept when it is valid
+    there or there is nothing to finish, else what that word was likely meant as."""
+    parser = root._tcw_parsers.get(path)
+    action = _subparsers(parser) if parser is not None else None
+    if not following or action is None:
+        return [()]
+    choices = visible_choices(action)
+    if following in choices:
+        return [(following,)]
+    offered = _offered(following, choices)
+    return [(o,) for o in offered] or [()]
+
+
+def attach_index(root: SuggestingParser) -> None:
+    """Walk the finished tree once: every parser learns its own path and the
+    root, and the root learns every listed subcommand's full paths."""
+    index: dict[str, list[tuple[str, ...]]] = {}
+    parsers: dict[tuple[str, ...], argparse.ArgumentParser] = {}
+
+    def walk(parser: argparse.ArgumentParser, path: tuple[str, ...]) -> None:
+        parser._tcw_root = root
+        parser._tcw_path = path
+        parsers[path] = parser
+        action = _subparsers(parser)
+        if action is None:
+            return
+        listed = set(visible_choices(action))
+        for name, child in action.choices.items():
+            if name in listed:
+                index.setdefault(name, []).append(path + (name,))
+            walk(child, path + (name,))
+
+    walk(root, (root.prog,))
+    root._tcw_index = index
+    root._tcw_parsers = parsers

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/tcw/refs.py

@@ -135,6 +135,10 @@ def resolve_tcw_ref(node_root: Path | None, uri: str) -> ResolveResult:
             return ResolveResult(
                 False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
         store, bare = resolved
+        # A renamed item answers to its old slug too: a link is exactly the kind
+        # of reference a rename cannot rewrite.
+        if store.get(bare) is None and (renamed := store.renamed(bare)):
+            bare = renamed
         # Locating the store that would hold the item is not the item existing.
         # `resolve_qualified_work_ref` answers "which store addresses this ref",
         # which is what `tcw serve`'s routing wants; `ok` answers "does this

{tcw_cli-2.7.0 → tcw_cli-2.8.1}/tcw/serve/__init__.py

@@ -20,7 +20,8 @@ from urllib.parse import unquote, urlparse
 from tcw.work.projection import work_item_json
 from tcw.store.base import (
     CAP_FIELDS, CAP_STATUSES, WORK_ARTIFACTS, WORK_SIDECARS, _UNSET,
-    IllegalTransition, PublicationError, RefError, StaleRevision, TransitionCommitError,
+    IllegalTransition, MultipleMatch, PublicationError, RefError, StaleRevision,
+    TransitionCommitError,
 )
 from tcw.store.fs import (
     FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, descendant_nodes,
@@ -300,6 +301,9 @@ def _map_store_error(e: Exception) -> tuple[int, bytes]:
         # because strict-tracker and generated-sidecar refusals are 409 too and
         # must show their own message instead.
         return _err(HTTPStatus.CONFLICT, str(e), code="stale-revision")
+    if isinstance(e, MultipleMatch):
+        # Two folders hold the slug: the data needs fixing, not the request.
+        return _err(HTTPStatus.CONFLICT, str(e))
     if isinstance(e, IllegalTransition):
         return _err(HTTPStatus.UNPROCESSABLE_ENTITY, str(e))
     if isinstance(e, RefError):
@@ -551,8 +555,17 @@ class TcwHandler(BaseHTTPRequestHandler):
         for root, prefix in self._board_roots():
             work = FsWorkStore.open(root)
             for it in work.board():
-                items.append(_item_payload(work, it.slug, it,
-                                           f"{prefix}{it.slug}" if prefix else None))
+                try:
+                    items.append(_item_payload(work, it.slug, it,
+                                               f"{prefix}{it.slug}" if prefix else None))
+                except MultipleMatch:
+                    # Two folders hold the slug, so its artifacts cannot be
+                    # read. Listed with none, so one duplicate does not take the
+                    # board down; the item's own route says why.
+                    data = work_item_json(it, [])
+                    if prefix:
+                        data["slug"] = f"{prefix}{it.slug}"
+                    items.append(data)
         return items
 
     def _board_roots(self) -> list[tuple[Path, str]]:
@@ -580,6 +593,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._get()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -588,6 +603,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._post()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -596,6 +613,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._patch()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -604,6 +623,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._put()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -612,6 +633,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             return
         try:
             self._delete()
+        except MultipleMatch as e:
+            self._send(HTTPStatus.CONFLICT, str(e).encode("utf-8"))
         except Exception as e:
             self._send(HTTPStatus.INTERNAL_SERVER_ERROR, str(e).encode("utf-8"))
 
@@ -967,6 +990,7 @@ class TcwHandler(BaseHTTPRequestHandler):
                 initiative = body.get("initiative", "")
                 type_val = body.get("type", "")
                 tags = body.get("tags") or None
+                work.refresh_for_creation()
                 detail = work.create_work(
                     title=title,
                     created=created,
@@ -987,6 +1011,14 @@ class TcwHandler(BaseHTTPRequestHandler):
                     # stale — which the next sidecar write from the page would
                     # be rejected on.
                     detail = work.get_detail(detail.item.slug) or detail
+                # After the owed record, so it is in the same commit. A refusal
+                # is logged, not returned: the item exists, and an error here
+                # would invite the browser to create it a second time.
+                folder = work.path(detail.item.slug)
+                if folder is not None and (reason := work.commit_writes(
+                        f"tcw work: new {detail.item.slug}", folder)):
+                    print(f"tcw serve: created {detail.item.slug}, but {reason}",
+                          file=sys.stderr)
                 response = {
                     "item": _item_payload(work, detail.item.slug, detail.item),
                     "coreRevision": detail.core_revision,