tcw-cli 0.20.1__py3-none-any.whl

tcw/__init__.py

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

tcw/capabilities/cli.py

@@ -0,0 +1,295 @@
+"""`tcw capabilities` — the user stories. Path-addressed folder capabilities."""
+
+import argparse
+import sys
+
+from tcw.store.base import Capability, RefError
+from tcw.store.base import AmbiguousRef
+from tcw.store.fs import FsCapabilitiesStore, FsTaxonomyStore, find_node, git_root
+
+NAME = "capabilities"
+SUBCOMMANDS = {"init", "list", "show", "path", "add", "search", "check", "set", "reset", "extends", "drift"}
+DEFAULT_SUBCOMMAND = "show"  # `tcw capabilities <path>` == `tcw capabilities show <path>`
+
+
+def _init(args: argparse.Namespace) -> int:
+    from tcw.cli import run_init      # function-local: top-level cli imports this module
+    return run_init([NAME], args.id)
+
+
+def _store() -> FsCapabilitiesStore | None:
+    node = find_node(NAME)
+    if node is None:
+        print("tcw capabilities: no tcw capabilities node here — run `tcw init` in the project folder.",
+              file=sys.stderr)
+        return None
+    return FsCapabilitiesStore.open(node)
+
+
+def _taxonomy_for(node):
+    """The node's taxonomy store, if it has one (for cross-component Subject check)."""
+    return FsTaxonomyStore.open(node) if (node / "docs" / "taxonomy").is_dir() else None
+
+
+def _stdin_body() -> str:
+    if sys.stdin.isatty():
+        return ""
+    try:
+        return sys.stdin.read()
+    except (OSError, ValueError):
+        return ""
+
+
+def _fmt(v) -> str:
+    return ", ".join(v) if isinstance(v, list) else str(v)
+
+
+def _print_cap(cap: Capability) -> None:
+    tag = f"  [{cap.origin}]" if cap.origin != "local" else ""
+    print(f"## {cap.name}  ({cap.qualified}){tag}")
+    if cap.id:
+        print(f"**id:** {cap.id}")
+    for k, v in cap.fields.items():
+        print(f"**{k}:** {_fmt(v)}")
+    body = cap.body.strip()
+    if body:
+        print()
+        print(body)
+
+
+def _list(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    for c in st.list_all(status=args.status, namespace=args.namespace,
+                         local_only=args.local_only):
+        print(f"[{c.status}]\t{c.qualified}\t{c.name}")
+    return 0
+
+
+def _show(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        cap = st.get(args.id)
+    except (RefError, AmbiguousRef) as e:
+        print(f"tcw capabilities show: {e}", file=sys.stderr)
+        return 1
+    if cap is None:
+        print(f"tcw capabilities show: no such capability: {args.id}", file=sys.stderr)
+        return 1
+    _print_cap(cap)
+    return 0
+
+
+def _path(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    print(st.root)
+    return 0
+
+
+def _add(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        cap = st.add(args.path, name=args.name, status=args.status, body=_stdin_body())
+    except (ValueError, RefError) as e:
+        print(f"tcw capabilities add: {e}", file=sys.stderr)
+        return 1
+    print(f"Added capability {cap.path} ({cap.id})")
+    return 0
+
+
+def _set(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    fields: dict = {}
+    if args.status:
+        fields["Status"] = args.status
+    for kv in (args.field or []):
+        if "=" not in kv:
+            print(f"tcw capabilities set: --field must be K=V: {kv}", file=sys.stderr)
+            return 1
+        k, v = kv.split("=", 1)
+        fields[k.strip()] = v.strip()
+    if not fields:
+        print("tcw capabilities set: need --status or at least one --field", file=sys.stderr)
+        return 1
+    try:
+        cap = st.set(args.id, fields)
+    except (ValueError, RefError) as e:
+        print(f"tcw capabilities set: {e}", file=sys.stderr)
+        return 1
+    print(f"Set {cap.path}")
+    return 0
+
+
+def _reset(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        st.reset(args.id)
+    except (ValueError, RefError) as e:
+        print(f"tcw capabilities reset: {e}", file=sys.stderr)
+        return 1
+    print(f"reset {args.id}")
+    return 0
+
+
+def _search(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    for c in st.search(args.query):
+        print(f"{c.qualified}\t{c.name}")
+    return 0
+
+
+def _extends(args: argparse.Namespace) -> int:
+    st = _store()
+    if st is None:
+        return 1
+    try:
+        if args.rm:
+            st.extends_remove(args.project_id)
+            print(f"Removed extends project {args.project_id}")
+        else:
+            st.extends_add(args.project_id)
+            print(f"Added extends project {args.project_id}")
+    except (ValueError, RefError) as e:
+        print(f"tcw capabilities extends: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _drift(args: argparse.Namespace) -> int:
+    """Report capabilities that drifted from ground truth: inherited-but-unreviewed
+    (status is the master default, never locally ruled on) and local-Missing whose
+    Planning doc points to a completed work item (declared, shipped, never flipped).
+    Read-only; exits non-zero when any drift is found."""
+    node = find_node(NAME)
+    if node is None:
+        print("tcw capabilities: no tcw capabilities node here — run `tcw init` in the project folder.",
+              file=sys.stderr)
+        return 1
+    st = FsCapabilitiesStore.open(node)
+
+    unreviewed = st.unreviewed_inherited()
+    shipped_missing = _shipped_but_missing(node, st)
+
+    for c in unreviewed:
+        print(f"unreviewed\t{c.qualified}\t(inherited; status is the master default)")
+    for path, slug in shipped_missing:
+        print(f"shipped-missing\t{path}\t(Planning doc {slug} is completed, still Missing)")
+
+    n = len(unreviewed) + len(shipped_missing)
+    if n:
+        print(f"{n} capability(ies) drifted.", file=sys.stderr)
+        return 1
+    print("no capability drift")
+    return 0
+
+
+def _shipped_but_missing(node, st) -> list[tuple[str, str]]:
+    """Local Missing capabilities whose `Planning doc` names a completed work item.
+    Read-only follow of an existing capability→work forward pointer; degrades to
+    empty when no work node is present (no hard cross-axis dependency)."""
+    if not (node / "docs" / "work").is_dir():
+        return []
+    from tcw.store.fs import FsWorkStore
+    work = FsWorkStore.open(node)
+    out: list[tuple[str, str]] = []
+    for c in st.list_all(local_only=True):
+        if c.status != "Missing":
+            continue
+        slug = c.fields.get("Planning doc")
+        if not slug:
+            continue
+        try:
+            item = work.get(str(slug))
+        except Exception:
+            item = None
+        # `completed` alone, deliberately NOT `RESOLVED_STATUSES`: this asks
+        # "did it ship?", not "is it closed?". A discarded item's capability is
+        # *supposed* to stay Missing (or be marked Omitted) — reporting it as
+        # shipped-but-unreconciled would be a false positive, which is exactly
+        # what happened before `discarded` existed.
+        if item is not None and item.status == "completed":
+            out.append((c.path, str(slug)))
+    return out
+
+
+def _check(args: argparse.Namespace) -> int:
+    node = find_node(NAME)
+    if node is None:
+        print("tcw capabilities: no tcw capabilities node here — run `tcw init` in the project folder.",
+              file=sys.stderr)
+        return 1
+    problems = FsCapabilitiesStore.open(node).check(taxonomy=_taxonomy_for(node))
+    for p in problems:
+        print(p, file=sys.stderr)
+    if problems:
+        print(f"{len(problems)} problem(s).", file=sys.stderr)
+        return 1
+    print("capabilities OK")
+    return 0
+
+
+def add_subparser(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(NAME, help="the user stories — what a user can do")
+    g = p.add_subparsers(dest="cmd", required=True)
+
+    pi = g.add_parser("init", help="scaffold docs/capabilities/ (mirror of `tcw init capabilities`)")
+    pi.add_argument("--id", help="canonical project ID (required for new/legacy nodes)")
+    pi.set_defaults(func=_init)
+
+    pl = g.add_parser("list", help="list capabilities, flagged by status + origin")
+    pl.add_argument("--status")
+    pl.add_argument("--namespace")
+    pl.add_argument("--local-only", action="store_true",
+                    help="exclude inherited (federated) capabilities")
+    pl.set_defaults(func=_list)
+
+    ps = g.add_parser("show", help="read a capability by path")
+    ps.add_argument("id", metavar="path")
+    ps.set_defaults(func=_show)
+
+    g.add_parser("path", help="print the capabilities store folder path").set_defaults(func=_path)
+
+    pa = g.add_parser("add", help="scaffold a capability folder")
+    pa.add_argument("path", metavar="namespace/path")
+    pa.add_argument("name", nargs="?")
+    pa.add_argument("-s", "--status", default="Missing")
+    pa.set_defaults(func=_add)
+
+    pset = g.add_parser("set", help="update a capability's status/fields in place")
+    pset.add_argument("id", metavar="path")
+    pset.add_argument("--status", help="shorthand for --field Status=<S>")
+    pset.add_argument("--field", action="append", metavar="K=V",
+                      help="set a metadata field (repeatable; Subject accepts a,b,c)")
+    pset.set_defaults(func=_set)
+
+    prst = g.add_parser("reset", help="drop a local override, re-inheriting upstream")
+    prst.add_argument("id", metavar="path")
+    prst.set_defaults(func=_reset)
+
+    pse = g.add_parser("search", help="search names + bodies")
+    pse.add_argument("query")
+    pse.set_defaults(func=_search)
+
+    pe = g.add_parser("extends", help="federate another project's capabilities")
+    pe.add_argument("project_id")
+    pe.add_argument("--rm", action="store_true", help="remove the project instead")
+    pe.set_defaults(func=_extends)
+
+    pc = g.add_parser("check", help="validate paths, subject/feature refs, federation, metadata")
+    pc.set_defaults(func=_check)
+
+    pd = g.add_parser("drift", help="report unreviewed inherited + shipped-but-Missing capabilities")
+    pd.set_defaults(func=_drift)

tcw/cli.py

@@ -0,0 +1,187 @@
+"""Top-level `tcw` CLI: dispatches `init | taxonomy | capabilities | work`.
+
+Built component groups register their own subparsers; the rest stub to "not yet
+implemented" until their phase lands (capabilities = Phase 3, work = Phase 5).
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from tcw import __version__
+from tcw.capabilities import cli as capabilities_cli
+from tcw.serve import DEFAULT_PORT, serve
+from tcw.store.fs import COMPONENTS, SENTINEL, find_node_root, git_root, init
+from tcw.store.project import FsProjectRegistry
+import yaml
+from tcw.taxonomy import cli as taxonomy_cli
+from tcw.work import cli as work_cli
+
+# Component CLI modules (each exposes NAME / SUBCOMMANDS / DEFAULT_SUBCOMMAND /
+# add_subparser). All three components are now built.
+_BUILT = [taxonomy_cli, capabilities_cli, work_cli]
+_STUBBED = [c for c in COMPONENTS if c not in {m.NAME for m in _BUILT}]
+
+
+def run_init(components: list[str], project_id: str | None = None,
+             work_path: str | None = None) -> int:
+    """Scaffold `docs/<component>/` trees under the current directory, mark it a
+    node, and report. Shared by `tcw init` and each `tcw <component> init`."""
+    root = Path.cwd()
+    if git_root(root) is None:                 # returns the repo root for any dir inside it
+        print("tcw init: not inside a git repository. Run `git init` first.", file=sys.stderr)
+        return 1
+    unknown = [c for c in components if c not in COMPONENTS]
+    if unknown:
+        print(f"tcw init: unknown component(s): {', '.join(unknown)}. "
+              f"Choose from: {', '.join(COMPONENTS)}.", file=sys.stderr)
+        return 2
+    sentinel = root / SENTINEL
+    if project_id is None:
+        try:
+            configured = yaml.safe_load(sentinel.read_text(encoding="utf-8")) if sentinel.exists() else {}
+        except yaml.YAMLError as error:
+            print(f"tcw init: invalid {SENTINEL}: {error}", file=sys.stderr)
+            return 1
+        if not isinstance(configured, dict) or not configured.get("id"):
+            print(
+                "tcw init: new or legacy TCW nodes require `--id <project-id>`; "
+                "IDs are not inferred",
+                file=sys.stderr,
+            )
+            return 1
+    try:
+        created = init(components, root, project_id,
+                       Path(work_path).expanduser() if work_path is not None else None)
+    except (ValueError, OSError) as error:
+        print(f"tcw init: {error}", file=sys.stderr)
+        return 1
+    print(f"Scaffolded {len(created)} dir(s):")
+    for p in created:
+        try:
+            shown = p.relative_to(root)
+        except ValueError:
+            shown = p
+        print(f"  {shown}")
+    print(f"Node marker: {SENTINEL}")          # deterministic across runs
+    if "work" in components:
+        print(".gitignore: resolved work (completed/, discarded/) stays on disk, "
+              "out of the tracked tree")
+    return 0
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    return run_init(args.components or list(COMPONENTS), args.id, args.work_path)
+
+
+def _not_yet(name: str):
+    def run(args: argparse.Namespace) -> int:
+        print(f"tcw {name}: not yet implemented.", file=sys.stderr)
+        return 1
+    return run
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    node_root = find_node_root()
+    if node_root is None:
+        print("tcw validate: no tcw node here — run `tcw init` in the project folder.",
+              file=sys.stderr)
+        return 1
+    registry = FsProjectRegistry.open(node_root)
+    registry_problems = registry.check()
+    if registry_problems:
+        for problem in registry_problems:
+            print(problem, file=sys.stderr)
+        print(f"{len(registry_problems)} project graph problem(s).", file=sys.stderr)
+        return 1
+    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]
+    problems: list[str] = []
+    for project in projects:
+        project_problems = validate(Path(project.locator), args.path)
+        if len(projects) > 1:
+            project_problems = [f"[{project.id}] {problem}" for problem in project_problems]
+        problems.extend(project_problems)
+    for p in problems:
+        print(p, file=sys.stderr)
+    if problems:
+        print(f"{len(problems)} problem(s).", file=sys.stderr)
+        return 1
+    print("validate OK")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    # Descendant node boards are aggregated by default (like
+    # `tcw work list --include-descendants`).
+    node_root = find_node_root()
+    if node_root is None:
+        print("tcw serve: no tcw node here — run `tcw init --id <project-id>`.",
+              file=sys.stderr)
+        return 1
+    FsProjectRegistry.open(node_root).require_valid()
+    return serve(port=args.port, open_browser=not args.no_open,
+                 include_descendants=True)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tcw", description="Taxonomy · Capabilities · Work.")
+    parser.add_argument("--version", action="version", version=f"tcw {__version__}")
+    sub = parser.add_subparsers(dest="group", required=True)
+
+    p_init = sub.add_parser("init", help="scaffold component doc trees in this git repo")
+    p_init.add_argument("components", nargs="*",
+                        help=f"any of: {', '.join(COMPONENTS)} (default: all)")
+    p_init.add_argument("--id", help="canonical project ID (required for new/legacy nodes)")
+    p_init.add_argument("--work-path", help="filesystem location for the work store")
+    p_init.set_defaults(func=_cmd_init)
+
+    p_validate = sub.add_parser(
+        "validate", help="check YAML soundness, tcw:// links, and component integrity")
+    p_validate.add_argument("path", nargs="?",
+                            help="narrow the active project scan to one file or directory (disables recursion)")
+    p_validate.add_argument(
+        "--no-recurse", action="store_true",
+        help="validate only the active project, excluding registered descendants",
+    )
+    p_validate.set_defaults(func=_cmd_validate)
+
+    p_serve = sub.add_parser("serve", help="serve a local read-only web viewer")
+    p_serve.add_argument("--port", type=int, default=DEFAULT_PORT,
+                         help=f"loopback port to bind (default: {DEFAULT_PORT})")
+    p_serve.add_argument("--no-open", action="store_true",
+                         help="do not open a browser automatically")
+    p_serve.set_defaults(func=_cmd_serve)
+
+    for mod in _BUILT:
+        mod.add_subparser(sub)
+    for name in _STUBBED:
+        p = sub.add_parser(name, help=f"{name} commands (not yet implemented)")
+        p.set_defaults(func=_not_yet(name))
+
+    return parser
+
+
+def _normalize(argv: list[str]) -> list[str]:
+    """Sugar: `tcw <component> <path>` → `tcw <component> show <path>`."""
+    if len(argv) >= 2 and not argv[1].startswith("-"):
+        for mod in _BUILT:
+            default = getattr(mod, "DEFAULT_SUBCOMMAND", None)
+            if default and argv[0] == mod.NAME and argv[1] not in mod.SUBCOMMANDS:
+                return [argv[0], default, *argv[1:]]
+    return argv
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args = build_parser().parse_args(_normalize(argv))
+    try:
+        return args.func(args)
+    except ValueError as error:
+        print(f"tcw: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tcw/refs.py

@@ -0,0 +1,132 @@
+"""The `tcw://` reference protocol — a portable way to point at a TCW object.
+
+Grammar: ``tcw://[<namespace>/]<axis>/<ref>``
+  - ``<axis>``      is ``T`` (Taxonomy), ``C`` (Capabilities), or ``W`` (Work).
+  - ``<namespace>`` (optional) locates the object in another project: an
+    ``extends`` alias for T/C, a descendant node path for W. Absent = local.
+  - ``<ref>``       is the identifier within that axis.
+
+`parse_tcw_uri` is a pure, total function (never raises) — the abstract grammar.
+`resolve_tcw_ref` is thin CLI/serve adapter glue: it imports the FS stores and
+dispatches through their existing ``get()`` / ``resolve_qualified_work_ref`` (no
+new store-interface method — litmus-clean), and never propagates a store
+exception to a caller scanning many links.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import unquote
+
+from tcw.store.fs import (
+    FsCapabilitiesStore,
+    FsTaxonomyStore,
+    qualified_work_ref_problem,
+    resolve_qualified_work_ref,
+)
+
+_SCHEME = "tcw://"
+_AXES = {"T", "C", "W"}
+
+
+@dataclass(frozen=True)
+class TcwRef:
+    namespace: str  # "" = local
+    axis: str       # normalized upper: "T" | "C" | "W"
+    ref: str
+
+
+@dataclass(frozen=True)
+class ResolveResult:
+    ok: bool
+    axis: str | None
+    key: str | None
+    reason: str
+    project: str = ""      # owning project id for a foreign work ref; "" = local
+
+
+def _segment_ok(seg: str) -> bool:
+    """A decoded path segment is safe iff it is not a traversal token and holds
+    no control/NUL/backslash chars (mirrors the guard style of `_safe_store_id`)."""
+    if seg in (".", ".."):
+        return False
+    return not any(ord(c) < 0x20 or c == "\x7f" or c == "\\" for c in seg)
+
+
+def parse_tcw_uri(uri: str) -> TcwRef | None:
+    """Parse a ``tcw://`` uri into its (namespace, axis, ref). Total: returns
+    None on any malformed input, never raises.
+
+    Split the remainder on ``/`` FIRST, then percent-decode each segment (so a
+    ``%2F`` inside a segment can't inject a spurious separator/axis — matches
+    the React client's ``parsePath``). The axis is the first segment whose ``.upper()``
+    is one of T/C/W; the first-bare-axis-wins collision (``tcw://T/C/ref``) is a
+    documented limitation. Empty segments (multiple slashes) are dropped.
+    """
+    if not isinstance(uri, str) or not uri.startswith(_SCHEME):
+        return None
+    raw_segs = [s for s in uri[len(_SCHEME):].split("/") if s]  # drop empties
+    segs = [unquote(s) for s in raw_segs]
+    if not all(_segment_ok(s) for s in segs):
+        return None
+    axis_idx = next((i for i, s in enumerate(segs) if s.upper() in _AXES), -1)
+    if axis_idx == -1:
+        return None
+    ref = "/".join(segs[axis_idx + 1:])
+    if not ref:
+        return None
+    return TcwRef("/".join(segs[:axis_idx]), segs[axis_idx].upper(), ref)
+
+
+def resolve_tcw_ref(node_root: Path | None, uri: str) -> ResolveResult:
+    """Resolve a ``tcw://`` uri against the node at ``node_root``, returning the
+    SPA object key (namespace-qualified where present). Never propagates a store
+    exception — a store failure becomes ``ok=False`` with a reason.
+
+    ``ok`` answers one question only: **does this reference resolve in the
+    registered graph?** That is what `tcw validate` asks. Whether a *viewer* can
+    open it is a different question with a different answer per server, so it is
+    not decided here — a foreign work ref reports its owning project in
+    ``project`` and the viewer gates on that (see `tcw serve`'s ``/api/resolve``).
+    Conflating the two is what made a valid cross-node link report ``ok`` and then
+    dead-end in the SPA: the two spellings of a namespaced work ref took different
+    paths, and the one people actually write never reached the gate at all.
+
+    Both spellings now produce the same qualified key. ``parse_tcw_uri`` treats the
+    first T/C/W segment as the axis, so ``tcw://<id>/W/<slug>`` arrives with a
+    parsed namespace while ``tcw://W/<id>/<slug>`` arrives as a bare ref whose
+    qualifier is resolved by ``resolve_qualified_work_ref``; keying off where the
+    ref actually landed, rather than off the spelling, covers both.
+    """
+    parsed = parse_tcw_uri(uri)
+    if parsed is None:
+        return ResolveResult(False, None, None, "malformed tcw:// uri")
+    if node_root is None:
+        return ResolveResult(False, parsed.axis, None, "no tcw node")
+    ns_ref = f"{parsed.namespace}/{parsed.ref}" if parsed.namespace else parsed.ref
+    try:
+        if parsed.axis == "T":
+            term = FsTaxonomyStore.open(node_root).get(ns_ref)
+            if term is None:
+                return ResolveResult(False, "T", None, f"no taxonomy term: {ns_ref}")
+            return ResolveResult(True, "T", term.qualified, "")
+        if parsed.axis == "C":
+            cap = FsCapabilitiesStore.open(node_root).get(ns_ref)
+            if cap is None:
+                return ResolveResult(False, "C", None, f"no capability: {ns_ref}")
+            return ResolveResult(True, "C", cap.qualified, "")
+        # axis == "W"
+        resolved = resolve_qualified_work_ref(node_root, ns_ref)
+        if resolved is None:
+            return ResolveResult(
+                False, "W", None, qualified_work_ref_problem(node_root, ns_ref))
+        store, bare = resolved
+        if store.node_root == node_root.resolve():        # landed locally
+            return ResolveResult(True, "W", bare, "")
+        # Foreign: the qualifier is a project id (a status-path locator is always
+        # local), and the SPA keys foreign items the way the board prints them.
+        project = ns_ref.partition("/")[0]
+        return ResolveResult(True, "W", f"{project}/{bare}", "", project)
+    except Exception as e:  # store errors (AmbiguousRef, MultipleMatch, IO) -> ok=False
+        return ResolveResult(False, parsed.axis, None, str(e))