tcw-cli 2.0.1__tar.gz → 2.0.2__tar.gz

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.0.1
+Version: 2.0.2
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/pyproject.toml

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

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

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tcw/store/checkouts.py

@@ -18,6 +18,45 @@ from pathlib import Path
 from tcw.store.base import RepositoryDeclaration, StoreDeclarationError
 
 
+def normalized_url(url: str) -> str:
+    """A canonical form of `url`, for asking whether two declarations name the
+    **same repository**.
+
+    Identity, not display, and the distinction is load-bearing. `_cache_key`
+    below does similar-looking text handling, but only for the *readable* half
+    of a directory name: the half that decides which directory a store lands in
+    is a digest of the raw url. So it deliberately keeps two spellings of one
+    repository apart, which is the opposite of what this answers. The two must
+    not be folded into one helper — routing that digest through here would
+    rename every provisioned directory on every machine at once, silently, and
+    orphan every store already in the cache.
+
+    Handles the spellings one workspace actually mixes, because the two sides of
+    a connection are written by different people at different times: a trailing
+    slash, a `.git` suffix, and `git@host:owner/repo` against
+    `https://host/owner/repo`. A local filesystem path round-trips unchanged,
+    which the tests rely on — they use real repositories in a temporary
+    directory as remotes.
+
+    The host is lowercased because hostnames are case-insensitive. The path is
+    not, because whether a forge treats `Owner/Repo` and `owner/repo` as one
+    thing varies, and merging them here would be this function claiming to know.
+    A port is kept as though it were a path segment: two spellings carrying the
+    same port still match each other, which is all identity needs, and dropping
+    it could merge two genuinely different hosts.
+    """
+    cleaned = url.strip().rstrip("/")
+    if cleaned.endswith(".git"):
+        cleaned = cleaned[:-4]
+    cleaned = re.sub(r"^[A-Za-z][A-Za-z0-9+.-]*://", "", cleaned)
+    cleaned = cleaned.rpartition("@")[2]           # drop any `git@` user part
+    host, slash, rest = cleaned.partition("/")
+    if ":" in host:                                # scp-style `host:owner/repo`
+        host, _, prefix = host.partition(":")
+        rest = f"{prefix}/{rest}" if slash else prefix
+    return f"{host.lower()}/{rest}"
+
+
 def _cache_root() -> Path:
     """Where working copies land when a declaration names no `checkout`.
 

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tcw/store/fs.py

@@ -1552,7 +1552,8 @@ class FsTreeStore:
 
     def _write_staged(self, pairs: list[tuple[Path, str]], *,
                       owned_dir: Path | None = None,
-                      also_stage: tuple[Path, ...] = ()) -> None:
+                      also_stage: tuple[Path, ...] = (),
+                      stage_root: Path | None = None) -> None:
         """Write every `(path, content)` and stage the lot, undoing what *this
         call* created if either half fails, then re-raising.
 
@@ -1575,6 +1576,12 @@ class FsTreeStore:
 
         Best-effort and silent: the undo must not mask the original error, and
         must not add a second line to a refusal whose one-line shape is pinned.
+
+        `stage_root` names the repository to stage in, for the one write that is
+        not a store file: the node's own `tcw-config.yaml`. The store root and
+        the node root vary independently — in the orchestrator layout they are
+        different repositories — and `git add` refuses a path outside the
+        repository it is given. Everything else defaults to the store's.
         """
         # `exists() or is_symlink()`: `exists()` follows the link, so a
         # pre-existing *dangling* symlink read as absent, was replaced by a real
@@ -1583,7 +1590,12 @@ class FsTreeStore:
         new = [p for p, _ in pairs if not (p.exists() or p.is_symlink())]
         try:
             _atomic_write_all(pairs)
-            self._stage(*(p for p, _ in pairs), *also_stage)
+            paths = (*(p for p, _ in pairs), *also_stage)
+            if stage_root is None:
+                self._stage(*paths)
+            else:
+                self._require_repository()
+                git_stage(stage_root, *paths)
         except BaseException:
             if owned_dir is not None:
                 shutil.rmtree(owned_dir, ignore_errors=True)
@@ -2936,11 +2948,41 @@ def _is_store_layout(root: Path, component: str) -> bool:
     return all((root / name).is_dir() for name in STORE_LAYOUT)
 
 
+def _registry_checkout_root(
+    node_root: Path, declaration: "RepositoryDeclaration"
+) -> Path | None:
+    """Where the declared store sits inside a project this machine already has.
+
+    The join the ladder's rung 1.5 needs: ask the project registry which project
+    is a checkout of the declared repository, then descend to the store's path
+    within it. None when the registry cannot answer, which sends the ladder on
+    to the provisioned copy.
+
+    **Every failure here is "no answer", never an error.** This rung is a
+    fallback reached only after a configured path has already failed, and a
+    graph problem must not turn a working provisioned store into a refusal. So
+    the registry is opened without `require_valid()` — the shape `run_provision`
+    already uses for the same reason — and anything raised is swallowed.
+    """
+    try:
+        found = FsProjectRegistry.open(node_root).checkout_of(declaration.url)
+    except Exception:
+        return None
+    if found is None:
+        return None
+    return (found / declaration.path) if declaration.path else found
+
+
 def resolve_store(store_cls, node_root: Path, _walk=None):
     """This node's store for `store_cls`'s component, in one ordered ladder.
 
     1. the local store (`<component>.path`, else `docs/<component>`) when it is
        usable;
+    1.5. else inside a project the registry has already located here, when one
+       is a checkout of the declared repository — local before remote, the same
+       rule `ConnectedProject` states for a project's own location. Numbered as
+       a half because it was added after the others and renumbering them would
+       silently rewrite what every message and comment elsewhere calls "rule 2";
     2. else the declared home repository's provisioned location, if usable;
     3. else `StoreNotProvisioned`, when a home repository is declared;
     4. else exactly what the component did before a declaration existed — the
@@ -3018,17 +3060,46 @@ def resolve_store(store_cls, node_root: Path, _walk=None):
             raw_root, node_root, config_path,
             external=configured is not None, must_exist=must_exist,
             _walk=_walk)
-    except StoreLocationUnusable:
+    except StoreLocationUnusable as unusable:
         # Only this. A store that is *there* and fails to open — a federation
         # error, a malformed `extends` — is a real error, and swallowing it here
         # reported "not provisioned; run `tcw provision`", which then succeeded
         # and left the store exactly as unopenable. `_extended_component_stores`
         # raises for many more reasons than it used to, so the hole widened.
-        pass
+        #
+        # The reason is carried rather than discarded, but **only when the
+        # configured path is actually there**. A path that does not exist,
+        # beside a declaration, is the ordinary case the declaration exists for
+        # — reporting it would make every provisioned node noisy. A path that
+        # exists and holds no store is a second configuration problem, and it
+        # used to vanish behind rule 3's message entirely.
+        #
+        # Presence is tested here rather than read out of the message: `_open_at`
+        # raises the same "is not a directory" for an absent path and for one
+        # that is a file, so the message cannot tell them apart.
+        local_failure = str(unusable) if raw_root.exists() else None
+        prefix = f"{config_path}: "
+        if local_failure and local_failure.startswith(prefix):
+            local_failure = local_failure[len(prefix):]
+    local = _registry_checkout_root(node_root, declaration)
+    if local is not None:
+        try:                                                    # rule 1.5
+            # No `declaration=`, and that omission is the whole of "must not
+            # publish". This store is on the user's own disk and they push it
+            # themselves — the same reasoning rule 1 relies on. `publishes`
+            # consults nothing else.
+            return store_cls._open_at(
+                local, node_root, config_path,
+                external=True, must_exist=True, _walk=_walk)
+        except StoreLocationUnusable:
+            # The project is here but holds no store at the declared path.
+            # A location that did not work out, so the ladder carries on —
+            # the same rule rules 1 and 2 follow.
+            pass
     try:                                                        # rule 2
-        # The declaration travels with the store *only* here. Rule 1 above
-        # resolved without it, so a store built there carries None and does not
-        # publish — see `FsWorkStore.publishes`.
+        # The declaration travels with the store *only* here. Rules 1 and 1.5
+        # above resolved without it, so a store built there carries None and
+        # does not publish — see `FsWorkStore.publishes`.
         return store_cls._open_at(
             provisioned_store_root(node_root, declaration), node_root, config_path,
             external=True, must_exist=True, declaration=declaration,
@@ -3038,7 +3109,8 @@ def resolve_store(store_cls, node_root: Path, _walk=None):
     raise StoreNotProvisioned(                                  # rule 3
         f"{config_path}: the {component} store is declared in "
         f"{declaration.url} but has not been provisioned here; "
-        f"run `tcw provision` to obtain it")
+        f"run `tcw provision` to obtain it"
+        + (f" — and the configured {local_failure}" if local_failure else ""))
 
 
 def declared_repository(
@@ -3383,8 +3455,13 @@ class FsWorkStore(FsTreeStore, WorkStore):
         root = raw_root.resolve()
         missing = [name for name in ("inbox", *WORK_STATUSES) if not (root / name).is_dir()]
         if missing:
+            # Names the directory, as the two branches above already do. Without
+            # it the user is told `work.path` is not a work store and never told
+            # which path that is — which matters most exactly when the value is
+            # relative and resolved somewhere they did not expect.
             raise StoreLocationUnusable(
-                f"{config_path}: work.path is not a work store; missing: {', '.join(missing)}")
+                f"{config_path}: work.path is not a work store: {root}; "
+                f"missing: {', '.join(missing)}")
         repository = git_root(root) if external else node_root
         if repository is None and external:
             # `StoreDeclarationError`, and both halves of that choice matter.
@@ -5158,7 +5235,18 @@ class FsWorkStore(FsTreeStore, WorkStore):
     def _write_tags(self, tags: set[str]) -> list[str]:
         """Read-modify-write `work.tags` (preserving other config keys), stage
         the file. `dump_yaml` rewrites the sentinel wholesale, dropping its stub
-        comments — accepted per plan."""
+        comments — accepted per plan.
+
+        **Staged in the node's repository, not the store's.** This is the only
+        write here that touches a file outside the store, and with an external
+        `work.path` the two are different repositories — the intended
+        orchestrator layout, not an edge case. Staging it against the store's
+        repository made `tcw work tags add` fail outright with *is outside
+        repository at …*, so the whole verb was unusable there.
+
+        A node outside git stages nothing rather than failing: the file is
+        written and that is the whole of what a non-git node can do.
+        """
         self._require_repository()
         config = self._config()
         work = config.get("work")
@@ -5167,9 +5255,14 @@ class FsWorkStore(FsTreeStore, WorkStore):
         result = sorted(tags)
         work["tags"] = result
         config["work"] = work
-        self._write_staged([(self._config_path(),
-                             yaml.safe_dump(config, sort_keys=False,
-                                            allow_unicode=True))])
+        config_path = self._config_path()
+        node_repository = git_root(config_path.parent)
+        payload = [(config_path, yaml.safe_dump(config, sort_keys=False,
+                                                allow_unicode=True))]
+        if node_repository is None:
+            _atomic_write_all(payload)
+        else:
+            self._write_staged(payload, stage_root=node_repository)
         return result
 
     def register_tags(self, tags: list[str]) -> list[str]:

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tcw/store/project.py

@@ -16,7 +16,7 @@ from tcw.store.base import (
     RepositoryDeclaration, StoreDeclarationError, UnreachableProject,
     WORK_STATUSES, parse_connected_entry,
 )
-from tcw.store.checkouts import provisioned_root
+from tcw.store.checkouts import normalized_url, provisioned_root
 
 SENTINEL = "tcw-config.yaml"
 PROJECT_ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
@@ -231,6 +231,45 @@ class FsProjectRegistry(ProjectRegistry):
         self._load_graph()
         return [cfg.project for cfg in self._by_id.values()]
 
+    def checkout_of(self, url: str) -> Path | None:
+        """Where a project this graph holds is a checkout of `url`, or None.
+
+        **Filesystem-adapter private, deliberately not on `ProjectRegistry`.**
+        The question itself is storage-neutral — a tracker-backed registry could
+        answer "which of your projects comes from this source" perfectly well —
+        but answering it here means comparing `RepositoryDeclaration.url` and
+        returning a `Project.locator`, and both are documented as things nothing
+        above the adapter may read. The one caller is `resolve_store` in
+        `fs.py`, which is the same adapter reading its own values.
+
+        Asks the *resolved* project rather than the declaration that named it.
+        That is the entire point: a declaration says where a project comes from,
+        and only the graph knows where it landed here, `TCW_PROJECT_<ID>`
+        included. A lookup that returned the declared locator would answer with
+        the path the config wrote, which on a machine needing this is exactly
+        the path that does not exist.
+
+        A project is reached through the edges pointing at it, since a node's
+        own repository is declared by whoever knows about that edge rather than
+        by the node itself. A declared project the graph does not hold answers
+        None: it names a repository but no location here, and sending the store
+        ladder to a path that is not there is worse than sending it nowhere.
+        """
+        self._load_graph()
+        wanted = normalized_url(url)
+        if not wanted:
+            return None
+        for cfg in list(self._cache.values()):
+            for entry in (*cfg.parent.values(), *cfg.children.values()):
+                if entry.repository is None:
+                    continue
+                if normalized_url(entry.repository.url) != wanted:
+                    continue
+                target = self._by_id.get(entry.id)
+                if target is not None:
+                    return Path(target.project.locator).resolve()
+        return None
+
     def check(self) -> list[str]:
         return list(self._problems)
 

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tcw/validate.py

@@ -21,7 +21,10 @@ from typing import Literal
 import yaml
 
 from tcw.refs import resolve_tcw_ref
-from tcw.store.fs import FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, load_yaml
+from tcw.store.base import StoreLocationUnusable
+from tcw.store.fs import (
+    STORE_CLASSES, FsCapabilitiesStore, FsTaxonomyStore, FsWorkStore, load_yaml,
+)
 
 _COMPONENTS = ("taxonomy", "capabilities", "work")
 _LINK_RE = re.compile(r"\]\((tcw://[^)\s]+)\)")
@@ -126,6 +129,56 @@ def _components_to_check(node_root: Path, path) -> list[str]:
     return []
 
 
+def _configured_path_problem(node_root: Path, comp: str) -> str | None:
+    """A configured `<comp>.path` that is present and holds no store, or None.
+
+    **Asked independently of resolution, and that is the whole point.** The
+    resolution ladder treats an unusable configured path as a location that did
+    not work out and moves on to the declaration, which is right for reading and
+    wrong for a command whose entire job is enumerating configuration problems.
+    Two faults were reported as one, and `_run_check` collapses any opening
+    failure into a single string, so even a compound message still counts once.
+
+    Running this only when resolution fails would miss the user it helps most:
+    the one whose declared store provisions fine, so nothing ever tells them the
+    path they wrote is wrong and they quietly read a second copy of the board.
+
+    **Silent when the path is absent.** With a declaration present that is the
+    ordinary case the declaration exists for, and reporting it would make every
+    provisioned node noisy. Presence is tested here rather than inferred from
+    the message, because `_open_at` raises the same text for a path that is
+    missing and one that is a file.
+
+    Asks the component's own `_open_at` rather than re-listing what a store
+    looks like. A third spelling of the store layout is exactly the drift the
+    shared ladder exists to prevent.
+    """
+    config_path = node_root / "tcw-config.yaml"
+    try:
+        config = load_yaml(config_path, unique=True)
+    except Exception:
+        return None                      # reported by the YAML pass above
+    section = config.get(comp) if isinstance(config, dict) else None
+    configured = section.get("path") if isinstance(section, dict) else None
+    if not isinstance(configured, str) or not configured.strip():
+        return None
+    store_cls = STORE_CLASSES[comp]
+    raw_root = store_cls._local_root(node_root, configured)
+    if not raw_root.exists():
+        return None
+    try:
+        store_cls._open_at(raw_root, node_root, config_path,
+                           external=True, must_exist=True)
+    except StoreLocationUnusable as unusable:
+        return str(unusable)
+    except Exception:
+        # Anything else is either not this check's business or is already
+        # reported by the component check beside it. Never swallow it into a
+        # second, differently worded copy of the same fault.
+        return None
+    return None
+
+
 def _run_check(node_root: Path, comp: str, identifier: str | None = None) -> list[str]:
     """One component's `check()`, or the reason its store could not be opened.
 
@@ -237,6 +290,11 @@ def validate(node_root: Path, path: Path | None = None, *,
     else:
         components = [target.axis] if target is not None else _components_to_check(node_root, path)
         for comp in components:
+            # Before the component's own check, so a node reads "your path is
+            # broken" ahead of whatever the store it fell back to has to say.
+            configured = _configured_path_problem(node_root, comp)
+            if configured is not None:
+                problems.append(f"{comp} path: {configured}")
             problems += _run_check(node_root, comp, target.ref if target else None)
 
     return problems

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tcw_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcw-cli
-Version: 2.0.1
+Version: 2.0.2
 Summary: Taxonomy · Capabilities · Work — a storage-abstracted framework for describing and evolving a software project.
 License:                                  Apache License
                                    Version 2.0, January 2004

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tests/test_external_work_store.py

@@ -1186,3 +1186,32 @@ def test_get_detail_of_a_genuinely_unknown_slug_is_none(tmp_path):
     code = _repo(tmp_path / "code")
     init(["work"], code, "corelib")
     assert FsWorkStore.open(code).get_detail("2026-01-01-nope") is None
+
+
+def test_registering_a_tag_stages_the_config_in_its_own_repository(tmp_path):
+    """`work.tags` lives in the node's `tcw-config.yaml`, which an external store
+    puts in a *different* repository from the store.
+
+    Staging it against the store's repository fails outright — `is outside
+    repository at …` — so registering a tag was impossible in the orchestrator
+    layout this project documents as the intended one. The store root and the
+    node root vary independently; a write has to go to whichever repository owns
+    the file it touches.
+    """
+    code, work_root = _external_node(tmp_path, "../orchestrator/stores/corelib")
+    store = FsWorkStore.open(code)
+    assert store.store_git_root != store.node_root, "the premise of this test"
+
+    assert store.register_tags(["chore"]) == ["chore"]
+
+    assert "chore" in yaml.safe_load(
+        (code / "tcw-config.yaml").read_text())["work"]["tags"]
+    staged = subprocess.run(
+        ["git", "-C", str(code), "diff", "--cached", "--name-only"],
+        capture_output=True, text=True, check=True).stdout.split()
+    assert "tcw-config.yaml" in staged, \
+        "the config must be staged in the repository that holds it"
+    store_staged = subprocess.run(
+        ["git", "-C", str(store.store_git_root), "diff", "--cached", "--name-only"],
+        capture_output=True, text=True, check=True).stdout
+    assert "tcw-config.yaml" not in store_staged

{tcw_cli-2.0.1 → tcw_cli-2.0.2}/tests/test_project_registry.py

@@ -835,3 +835,106 @@ def test_the_override_is_probed_once_per_project(tmp_path, monkeypatch):
     registry.require_valid()
     assert calls.count("child-project") == 1
     assert len(registry.overrides()) == 1
+
+
+# ── locating a project by the repository it comes from ───────────────────────
+#
+# The question the store-resolution ladder asks when its configured path does
+# not resolve: *is a checkout of this repository already on this disk?* The
+# registry is the only thing that knows, because it is the only thing that has
+# consulted `TCW_PROJECT_<ID>`.
+
+
+def _workspace(tmp_path: Path, url: str, *, parent_at: str = "orchestration") -> tuple[Path, Path]:
+    """A child declaring its parent, and naming the repository the parent is a
+    checkout of. Returns `(child_root, parent_root)`.
+
+    Every axis the lookup branches on is written here rather than defaulted:
+    the declared locator, the repository url, and where the parent actually is.
+    """
+    parent = tmp_path / parent_at
+    child = tmp_path / "core"
+    config(parent, f"id: orchestration\nconnected-projects:\n  children:\n    core: {child}\n")
+    config(
+        child,
+        "id: core\n"
+        "connected-projects:\n"
+        "  parent:\n"
+        "    orchestration:\n"
+        f"      path: {parent}\n"
+        "      repository:\n"
+        f"        url: {url}\n"
+        "        ref: main\n",
+    )
+    return child, parent
+
+
+def test_checkout_of_finds_a_project_declared_from_that_repository(tmp_path):
+    url = "https://github.invalid/acme/orchestration.git"
+    child, parent = _workspace(tmp_path, url)
+
+    registry = FsProjectRegistry.open(child)
+
+    assert registry.checkout_of(url) == parent.resolve()
+
+
+@pytest.mark.parametrize("asked", [
+    "https://github.invalid/acme/orchestration",
+    "https://github.invalid/acme/orchestration/",
+    "git@github.invalid:acme/orchestration.git",
+])
+def test_checkout_of_matches_across_url_spellings(tmp_path, asked):
+    """The two sides of a connection are written at different times by
+    different people, so one spelling is not a safe assumption."""
+    child, parent = _workspace(tmp_path, "https://github.invalid/acme/orchestration.git")
+
+    assert FsProjectRegistry.open(child).checkout_of(asked) == parent.resolve()
+
+
+def test_checkout_of_returns_none_for_an_unrelated_repository(tmp_path):
+    child, _parent = _workspace(tmp_path, "https://github.invalid/acme/orchestration.git")
+
+    registry = FsProjectRegistry.open(child)
+
+    assert registry.checkout_of("https://github.invalid/acme/something-else.git") is None
+
+
+def test_checkout_of_follows_an_override(tmp_path, monkeypatch):
+    """The whole point of the item this exists for.
+
+    The declared locator is right for the nested layout and wrong here; the
+    environment says where the parent actually is. A lookup that read the
+    declaration instead of the resolved project would answer with a directory
+    this machine does not have.
+    """
+    url = "https://github.invalid/acme/orchestration.git"
+    child, declared = _workspace(tmp_path, url)
+    elsewhere = tmp_path / "flat" / "orchestration"
+    config(elsewhere, f"id: orchestration\nconnected-projects:\n  children:\n    core: {child}\n")
+    monkeypatch.setenv("TCW_PROJECT_ORCHESTRATION", str(elsewhere))
+
+    found = FsProjectRegistry.open(child).checkout_of(url)
+
+    assert found == elsewhere.resolve()
+    assert found != declared.resolve(), "the declared locator must not win over the override"
+
+
+def test_checkout_of_ignores_a_project_the_graph_does_not_hold(tmp_path):
+    """A declaration whose target is not on this machine names a repository but
+    no location. Answering with a path that is not there would send the store
+    ladder somewhere worse than nowhere."""
+    url = "https://github.invalid/acme/orchestration.git"
+    child = tmp_path / "core"
+    config(
+        child,
+        "id: core\n"
+        "connected-projects:\n"
+        "  parent:\n"
+        "    orchestration:\n"
+        f"      path: {tmp_path / 'not-here'}\n"
+        "      repository:\n"
+        f"        url: {url}\n"
+        "        ref: main\n",
+    )
+
+    assert FsProjectRegistry.open(child).checkout_of(url) is None