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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.6.4
+Version: 2.7.0
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -476,7 +476,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -907,7 +910,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

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

@@ -260,7 +260,10 @@ agent through. See [Skills and Agents](#skills-and-agents).
 
 **Many repositories, one model.** Projects are identified by ID, never by path.
 A project can connect to others, inherit their taxonomy and capabilities, and
-address their work items as `<project-id>/<slug>`. A checkout holding only some of
+address their work items as `<project-id>/<slug>`. A connection is normally
+declared by both projects; an `upstream` one is declared only by the reader and
+is read-only from its side, so a private project can read a public one that never
+names it. A checkout holding only some of
 the connected repositories still works: the absent ones drop out rather than
 breaking your commands. See [Working across repositories](docs/guide/multi-repo.md).
 
@@ -691,7 +694,7 @@ driving it to completion, verifying it, processing the inbox) described in
 | Command              | What it does                                                      |
 | -------------------- | ----------------------------------------------------------------- |
 | `tcw work inbox`     | `inbox list`, `inbox show` and `inbox accept` raw requests, and Jira tickets awaiting triage |
-| `tcw work nodes`     | lists this project's parent and child projects                    |
+| `tcw work nodes`     | lists this project's parent, child and upstream projects          |
 | `tcw work delegate`  | writes a request into the nearest child project with a board      |
 | `tcw work escalate`  | writes a request into the parent project's inbox                  |
 | `tcw work reconcile` | reads every project below with a board; writes the epic's roll-up |

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

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

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

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

@@ -210,12 +210,14 @@ def _declared_nodes_in_graph(
         # Every project the registry holds, not `ancestors + descendants`. That
         # triple omits a sibling and a sibling of an ancestor — the shapes a
         # workspace is actually made of — so a declaration living on one was
-        # never read, and the repository it named never obtained.
-        roots += [Path(project.locator) for project in
-                  FsProjectRegistry.open(root).projects()]
+        # never read, and the repository it named never obtained. Except an
+        # upstream: what it connects to is its own to obtain, not its readers'.
+        registry = FsProjectRegistry.open(root)
+        roots += [Path(project.locator) for project in registry.projects()
+                  if registry.read_only_reason(project.id) is None]
     except Exception:
         pass
-    found: list[tuple[Path, str, object]] = []
+    found: list[tuple[Path, str, object, str]] = []
     problems: list[str] = []
     for candidate in roots:
         candidate = candidate.resolve()
@@ -224,7 +226,7 @@ def _declared_nodes_in_graph(
         seen.add(candidate)
         declared, candidate_problems = declared_connected_projects(candidate)
         problems += [f"{candidate / SENTINEL}: {p}" for p in candidate_problems]
-        found += [(candidate, pid, d) for pid, d in declared]
+        found += [(candidate, pid, d, relation) for pid, d, relation in declared]
     return found, problems
 
 
@@ -250,7 +252,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
 
     failed = False
     seen: set[Path] = set()
-    queue: list[tuple[Path, str, object]] = []
+    queue: list[tuple[Path, str, object, str]] = []
     # "A project that is already here always wins" is the rule the whole feature
     # rests on, and the walk is the one place it was not applied: a declaration
     # is written by whichever node knows about that edge, so an ancestor
@@ -298,8 +300,14 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             return None
         return located if located != target.resolve() else None
 
-    def enqueue(root: Path) -> None:
+    def enqueue(root: Path, relation: str = "children") -> None:
         nonlocal failed
+        if relation == "upstream":
+            # Obtained so it can be read; its own connections are not followed,
+            # as the registry does not follow them. A reader must never fetch a
+            # project named only by something it reads — a public upstream can
+            # still name the private repository it is migrating away from.
+            return
         found, problems = _declared_nodes_in_graph(root, enqueued)
         for problem in problems:
             print(f"tcw provision: {problem}", file=sys.stderr)
@@ -314,7 +322,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
     enqueued: set[Path] = set()
     enqueue(node_root)
     while queue:
-        source, project_id, declaration = queue.pop(0)
+        source, project_id, declaration, relation = queue.pop(0)
         target = provisioned_store_root(source, declaration)
         if target in seen:
             continue
@@ -335,13 +343,13 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
             # provisioning precisely when an earlier one was already in place.
             print(f"  {project_id}: already available")
             have.add(project_id)
-            enqueue(present)
+            enqueue(present, relation)
             continue
         provisioner = FsStoreProvisioner(source, NODE_TARGET, declaration)
         if provisioner.is_available() and not refresh:
             print(f"  {project_id}: already available at {target}")
             have.add(project_id)
-            enqueue(target)
+            enqueue(target, relation)
             continue
         print(f"→ {project_id}: {provisioner.describe().split(': ', 1)[1]}")
         try:
@@ -363,7 +371,7 @@ def _provision_nodes(node_root: Path, *, refresh: bool, dry_run: bool) -> bool:
         # routine when a parent and a grandparent both name it — report
         # "already available" in a run that fetched nothing.
         have.add(project_id)
-        enqueue(target)
+        enqueue(target, relation)
     return failed
 
 
@@ -406,6 +414,8 @@ def _cmd_validate(args: argparse.Namespace) -> int:
     for override in registry.overrides():
         print(f"connected project '{override.id}' is overridden by "
               f"{override.source} to {override.locator}", file=sys.stderr)
+        if override.warning:
+            print(f"  warning: {override.warning}", file=sys.stderr)
     registry_problems = registry.check()
     if registry_problems:
         for problem in registry_problems:
@@ -435,6 +445,8 @@ def _cmd_validate(args: argparse.Namespace) -> int:
         print(f"{entry.declared_in}: connected project '{entry.id}' is declared "
               f"at {entry.locator}, which is not in this checkout; it was found "
               f"at {registry.get(entry.id).locator}", file=sys.stderr)
+    for warning in registry.warnings():
+        print(f"warning: {warning}", file=sys.stderr)
     from tcw.validate import validate
     recurse = args.path is None and not args.no_recurse
     projects = [registry.current, *registry.descendants()] if recurse else [registry.current]

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

@@ -24,7 +24,8 @@ from tcw.store.base import (
 )
 from tcw.store.fs import (
     FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, descendant_nodes,
-    find_node_root, heading_slug, registered_project_id, resolve_qualified_work_ref,
+    find_node_root, heading_slug, registered_project_id, qualified_work_ref_read_only,
+    resolve_qualified_work_ref,
 )
 from tcw.refs import resolve_tcw_ref
 from tcw.validate import ValidationTarget, validate
@@ -236,7 +237,7 @@ def _strict_refuses(work, action: str, slug: str = "", body: dict | None = None)
             or work.get(slug)) if slug else None
     epic = (body.get("type") == "epic") if action == "create" else (
         item is not None and item.type == "epic")
-    from tcw.tracker.intake import ever_bound
+    from tcw.tracker.intake import drop_refusal
     lead = "refused under strict tracker mode, which the web app cannot check; "
     if action == "create" and not epic:
         return lead + "create work from a ticket with `tcw work tracker import <ticket>`."
@@ -245,9 +246,8 @@ def _strict_refuses(work, action: str, slug: str = "", body: dict | None = None)
         return lead + f"use `tcw work start {slug}{take_over}`, which claims the ticket."
     if action == "complete" and not epic and body.get("resolution") == "done":
         return lead + f"use `tcw work complete {slug}`, which checks the ticket."
-    if action == "drop" and ever_bound(work, slug):
-        return lead + (f"{slug} is, or was, bound to a ticket. Discard it instead: "
-                       f"`tcw work complete {slug} --resolution wontfix --confirm`.")
+    if action == "drop" and (refusal := drop_refusal(work, slug)):
+        return lead + refusal
     return None
 
 
@@ -508,6 +508,21 @@ class TcwHandler(BaseHTTPRequestHandler):
             return resolve_qualified_work_ref(self.server.node_root, slug)
         return FsWorkStore.open(self.server.node_root), slug
 
+    def _refused_read_only(self, slug: str) -> bool:
+        """Answer 403 and return True when `slug` names an item in a project this
+        node reads but may not write — an upstream project, or one reached only
+        through one. Every route that changes an item or runs its project's
+        scripts asks this first; reads do not, so the board can still show it."""
+        if not self.server.include_descendants:
+            return False
+        reason = qualified_work_ref_read_only(self.server.node_root, slug)
+        if reason is None:
+            return False
+        self._send_err(HTTPStatus.FORBIDDEN,
+                       f"{reason}; change it from that project itself",
+                       code="read-only-project")
+        return True
+
     def _hosted_projects(self) -> set[str]:
         """Project IDs whose items this server actually serves — the descendants it
         aggregates, or nothing when not aggregating.
@@ -635,6 +650,12 @@ class TcwHandler(BaseHTTPRequestHandler):
                 return
             try:
                 resource = work.read_artifact(slug, name)
+            except UnicodeDecodeError:
+                # Before ValueError, which it is: the decoder's own message names
+                # a byte offset, not the file.
+                self._send(HTTPStatus.BAD_REQUEST,
+                           f"{name} is not valid UTF-8; fix or replace the file".encode("utf-8"))
+                return
             except ValueError as e:
                 self._send(HTTPStatus.BAD_REQUEST, str(e).encode("utf-8"))
                 return
@@ -806,6 +827,15 @@ class TcwHandler(BaseHTTPRequestHandler):
                         })
                     else:
                         artifacts_list.append({"name": name, "present": False})
+                except UnicodeDecodeError:
+                    # Not valid UTF-8: listed with the snapshot's revision, so a
+                    # guarded save can replace it; opening it names the file.
+                    artifacts_list.append({
+                        "name": name,
+                        "present": name in lifecycle_present,
+                        "revision": detail.artifact_revisions.get(name, ""),
+                        "mediaType": "text/markdown",
+                    })
                 except ValueError:
                     pass
             # Sidecar discovery in detail
@@ -979,6 +1009,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             slug = _decode_path_param(m.group(1))
             action = _decode_path_param(m.group(2))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1202,6 +1234,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             qslug = slug                          # preserve the addressed (qualified) slug
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1356,6 +1390,8 @@ class TcwHandler(BaseHTTPRequestHandler):
             if name not in WORK_ARTIFACTS:
                 self._send(HTTPStatus.BAD_REQUEST, b"unknown artifact")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1394,6 +1430,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1429,6 +1467,8 @@ class TcwHandler(BaseHTTPRequestHandler):
                                f"{name} is written by `{owner}`, not edited; "
                                f"run that command instead.")
                 return
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1484,6 +1524,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         if m:
             slug = _decode_path_param(m.group(1))
             stage_id = _decode_path_param(m.group(2))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1501,6 +1543,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         m = re.match(r"^/api/work/([^/]+)$", path)
         if m:
             slug = _decode_path_param(m.group(1))
+            if self._refused_read_only(slug):
+                return
             resolved = self._resolve_work(slug)
             if resolved is None:
                 self._send(HTTPStatus.NOT_FOUND, b"no such work item")
@@ -1570,6 +1614,8 @@ class TcwHandler(BaseHTTPRequestHandler):
         slug_q, _, stage_q = middle.partition("/plan-stages/")
         slug = _decode_path_param(slug_q)
         stage_id = _decode_path_param(stage_q)
+        if self._refused_read_only(slug):
+            return
         resolved = self._resolve_work(slug)
         if resolved is None:
             self._send(HTTPStatus.NOT_FOUND, b"no such work item")