taktcli 0.2.0__tar.gz → 0.3.0__tar.gz

{taktcli-0.2.0 → taktcli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taktcli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
 Author: Takt
 License: MIT
@@ -139,7 +139,7 @@ Every MCP tool maps to a verb:
 | `get_task_comments` | `task comments <id>` |
 | `attach_result` | `task result <id>` |
 | `get_task_results` | `task results <id>` |
-| `delete_result` | `task result delete <id>` |
+| `delete_result` | `task result-delete <id>` |
 | `wiki_read` | `wiki read <path>` |
 | `wiki_search` / `wiki_semantic_search` | `wiki search <q>` (`--semantic`) |
 | `wiki_grep` | `wiki grep <pattern>` |

{taktcli-0.2.0 → taktcli-0.3.0}/README.md

@@ -123,7 +123,7 @@ Every MCP tool maps to a verb:
 | `get_task_comments` | `task comments <id>` |
 | `attach_result` | `task result <id>` |
 | `get_task_results` | `task results <id>` |
-| `delete_result` | `task result delete <id>` |
+| `delete_result` | `task result-delete <id>` |
 | `wiki_read` | `wiki read <path>` |
 | `wiki_search` / `wiki_semantic_search` | `wiki search <q>` (`--semantic`) |
 | `wiki_grep` | `wiki grep <pattern>` |

{taktcli-0.2.0 → taktcli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taktcli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core"
 readme = "README.md"
 requires-python = ">=3.12"

taktcli-0.3.0/taktcli/__init__.py

@@ -0,0 +1,27 @@
+"""taktcli — authorized GraphQL CLI for Takt.
+
+Stdlib-only core: argv -> GraphQL-over-HTTP. See PRD 002 in the takt wiki.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+FALLBACK_VERSION = "0.0.0.dev0"
+
+
+def _resolve_version() -> str:
+    """Resolve the version from the installed distribution's metadata.
+
+    `cli/pyproject.toml` is the single source of truth: its version is baked
+    into the package metadata at build time, so `--version` always reports the
+    version actually installed and can never drift from the released package.
+
+    Running from a source checkout that was never pip-installed leaves no
+    metadata to read; that case reports FALLBACK_VERSION rather than failing.
+    """
+    try:
+        return version("taktcli")
+    except PackageNotFoundError:
+        return FALLBACK_VERSION
+
+
+__version__ = _resolve_version()

{taktcli-0.2.0 → taktcli-0.3.0}/taktcli/commands/_run.py

@@ -14,12 +14,24 @@ from ..io import format_output, read_path
 from ..transport import execute
 
 
-def run_op(args, document: str, variables: dict) -> int:
-    """Execute a GraphQL document and print the formatted result."""
+def run_op(args, document: str, variables: dict, *, hint=None) -> int:
+    """Execute a GraphQL document and print the formatted result.
+
+    ``hint`` is an optional ``data -> str`` callback for advisory guardrails: it
+    is called with the unwrapped ``.data`` payload once stdout has been written
+    and flushed, and a non-empty return is emitted on stderr (falsy = stay
+    quiet). Running it after the flush is what preserves the §4.2 contract that
+    stdout stays parseable JSON — a hint never interleaves with the payload,
+    and never changes the exit code.
+    """
     url, token = resolve_auth()
     envelope = execute(document, variables, url=url, token=token)
     print(format_output(envelope, raw=getattr(args, "raw", False), compact=getattr(args, "compact", False)))
     sys.stdout.flush()
+    if hint is not None:
+        message = hint((envelope or {}).get("data") or {})
+        if message:
+            print(message, file=sys.stderr)
     return 0
 
 

{taktcli-0.2.0 → taktcli-0.3.0}/taktcli/commands/task.py

@@ -11,6 +11,7 @@ from ..io import parse_scalar
 from ._exec import (
     add_output_args,
     build_operation,
+    fetch,
     resolve_lease,
     run_operation,
     text_from_flags,
@@ -111,8 +112,43 @@ def search_run(args) -> int:
     return run_operation(args, document, variables)
 
 
+def reject_empty(value: str, flag: str) -> str:
+    """Reject a blank flag value instead of letting it silently drop.
+
+    ``createTask`` coerces a falsy ``parentId`` to ``None`` server-side, so an
+    empty string would quietly create a *parentless* task at exit 0 — the
+    empty-string-drops-args class taktcli exists to avoid. Both parent flags go
+    through here so neither can fail silently.
+    """
+    if not value.strip():
+        raise ConfigError(f"{flag}: empty value — omit the flag to create a task with no parent")
+    return value
+
+
+def resolve_parent_id(identifier: str) -> str:
+    """Resolve a task identifier to its internal UUID for ``CreateTaskInput.parentId``.
+
+    ``CreateTaskInput`` only accepts the parent's UUID, so ``--parent`` costs one
+    extra round-trip. An identifier that matches no task raises ``ConfigError``
+    (exit 3) rather than letting a ``null`` lookup silently create a parentless
+    task.
+    """
+    document, variables = build_operation(
+        "ResolveParent", "task",
+        [("id", "String!", "identifier", identifier)],
+        "{ id }",
+    )
+    envelope = fetch(document, variables)
+    parent = ((envelope.get("data") or {}).get("task") or {}).get("id")
+    if not parent:
+        raise ConfigError(f"--parent: no task found with identifier '{identifier}'")
+    return parent
+
+
 def create_run(args) -> int:
     description = text_from_flags(args.desc, args.desc_file, "--desc", "--desc-file")
+    if args.parent is not None and args.parent_id is not None:
+        raise ConfigError("pass either --parent or --parent-id, not both")
     payload = {"title": args.title}
     if description is not None:
         payload["description"] = description
@@ -122,8 +158,10 @@ def create_run(args) -> int:
         payload["labels"] = args.label
     if args.priority is not None:
         payload["priority"] = args.priority
-    if args.parent_id:
-        payload["parentId"] = args.parent_id
+    if args.parent is not None:
+        payload["parentId"] = resolve_parent_id(reject_empty(args.parent, "--parent"))
+    elif args.parent_id is not None:
+        payload["parentId"] = reject_empty(args.parent_id, "--parent-id")
     if args.assignee:
         payload["assignee"] = args.assignee
     if args.status:
@@ -343,7 +381,8 @@ def register(subparsers) -> None:
     p.add_argument("--depends-on", dest="depends_on", action="append", help="blocking dependency identifier (repeatable)")
     p.add_argument("--label", action="append", help="label name (repeatable)")
     p.add_argument("--priority", type=int)
-    p.add_argument("--parent-id", dest="parent_id", help="parent task UUID")
+    p.add_argument("--parent", help="parent task identifier (e.g. takt-10)")
+    p.add_argument("--parent-id", dest="parent_id", help="parent task UUID (back-compat; prefer --parent)")
     p.add_argument("--assignee")
     p.add_argument("--status", choices=TASK_STATUSES)
     add_output_args(p)

{taktcli-0.2.0 → taktcli-0.3.0}/taktcli/commands/wiki.py

@@ -11,6 +11,8 @@ Large markdown flows through ``--content-file`` / ``--old-file`` / ``--new-file`
 """
 
 import os
+import re
+import warnings
 
 from ..errors import ConfigError
 from ..io import add_output_args
@@ -18,6 +20,37 @@ from ._run import resolve_text, run_op
 
 STATUS_CHOICES = ("DRAFT", "PUBLISHED", "ARCHIVED")
 
+ORDER_FIELD_CHOICES = ("RELEVANCE", "UPDATED_AT", "CREATED_AT", "PATH", "TITLE")
+"""``WikiPageOrderField`` minus ``MATCH_COUNT``, which needs a grep predicate.
+
+``wiki search`` maps to ``wikiPages`` without one, so ``MATCH_COUNT`` could only ever come
+back as a server ``VALIDATION_ERROR`` — offering it in ``--help`` would advertise an
+ordering this verb cannot produce. ``RELEVANCE`` stays: the positional query supplies the
+ts_rank signal, and the one case that loses it (an empty query) is the server's call, not
+a shape the CLI can rule out up front.
+"""
+
+DIRECTION_CHOICES = ("ASC", "DESC")
+
+SEMANTIC_ORDER_CONFLICT = (
+    "--order-by/--direction/--offset are not supported with --semantic: semantic rows are a "
+    "top-K selection over a similarity threshold, ranked by cosine score. Raise --limit and "
+    "slice locally, or drop --semantic to order and page the full-text surface."
+)
+
+TASK_IDENTIFIER_RE = re.compile(r"[a-z][a-z0-9-]*-\d+")
+"""Mirrors ``TASK_IDENTIFIER_PATTERN`` (backend ``mention_service``), which the
+CLI cannot import — its core is stdlib-only and ships to PyPI on its own. A
+task_prefix is validated ``^[a-z][a-z0-9-]*$`` at the project layer, so every
+mintable identifier matches; matched with ``fullmatch`` so a stray newline
+cannot slip through a ``$``."""
+
+REGEX_METACHARS = frozenset("|()[]{}*+?^$")
+
+MENTION_RE = re.compile(r"\[\[[^\[\]]+\]\]")
+
+GREP_METACHAR_HINT = "pattern contains regex metacharacters — literal match returned nothing; retry with --regex?"
+
 
 def _add_wiki_arg(parser) -> None:
     parser.add_argument(
@@ -34,6 +67,95 @@ def _wiki_slug(args) -> str:
     return args.wiki
 
 
+def _has_unescaped_metachar(pattern: str) -> bool:
+    """True when PATTERN carries regex syntax that a literal grep cannot honour.
+
+    Backslash-escaped characters are skipped: ``\\(`` is written by an author
+    who already knows the literal/regex distinction. ``.`` is deliberately not
+    in ``REGEX_METACHARS`` — it is too common in ordinary prose and in the
+    filenames agents grep for (``wiki_service.py``) to signal regex intent, and
+    a hint that cries wolf on every dotted token is worse than no hint.
+    """
+    chars = iter(pattern)
+    for char in chars:
+        if char == "\\":
+            next(chars, None)
+            continue
+        if char in REGEX_METACHARS:
+            return True
+    return False
+
+
+def _is_valid_regex(pattern: str) -> bool:
+    """Whether PATTERN would survive the ``re.compile`` the server runs.
+
+    ``re.compile`` is the only way to ask — there is no ``re.is_valid`` — so the
+    expected-to-raise probe is the API, not defensive wrapping. The answer is
+    exact rather than heuristic: ``wiki_service.grep_pages`` compiles with this
+    same stdlib engine, and compiles it *unguarded*, so advising ``--regex`` on
+    a pattern that cannot compile would trade a clean exit-0 empty result for an
+    unhandled ``re.error``.
+
+    ``re.error`` is not the whole failure contract: a repeat count above
+    ``MAXREPEAT`` (``a{4294967296}``) raises ``OverflowError`` and deep nesting
+    raises ``RecursionError``. Both must answer "no" rather than escape — a
+    probe that crashes the client on the *literal* path would be a worse bug
+    than the one this gate exists to prevent, and the backend would raise the
+    same thing in regex mode anyway.
+
+    Warnings are silenced because this compile is a *probe*, not a use: ``re``
+    writes ``FutureWarning: Possible nested set`` to stderr for patterns like
+    ``[[a]]``, which would pollute the very stream the hint contract keeps
+    clean. Only the caller's own hint may reach stderr here.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        try:
+            re.compile(pattern)
+        except (re.error, OverflowError, RecursionError):
+            return False
+    return True
+
+
+def _looks_like_mention(pattern: str) -> bool:
+    """Whether PATTERN contains Takt mention syntax — ``[[takt-42]]``, ``[[wiki/path]]``.
+
+    Grepping for a mention is high-traffic (CLAUDE.md tells every agent to write
+    them), and a missing one is exactly the zero-hit path that arms the hint —
+    yet ``--regex`` is never the fix. ``[[takt/context/taktcli]]`` even compiles,
+    as a character class that quietly matches garbage, so the validity gate alone
+    would not catch it.
+
+    ``search``, not ``fullmatch``: ``[[a]]|[[b]]`` is two mentions and ``--regex``
+    turns it into char-class junk just the same, so any pattern *containing* a
+    mention is one whose author is thinking in mentions rather than regex. The
+    cost is that a genuine regex spliced onto a mention goes unhinted — cheap,
+    since silence is the safe default and the hint was only ever a nudge.
+    """
+    return MENTION_RE.search(pattern) is not None
+
+
+def _should_hint_regex(pattern: str) -> bool:
+    """Whether a zero-hit literal PATTERN earns an "add ``--regex``" nudge.
+
+    Three gates, each closing off a way the nudge could mislead: the pattern must
+    carry regex syntax at all, must not be mention syntax that ``--regex`` cannot
+    help, and must actually compile.
+    """
+    return _has_unescaped_metachar(pattern) and not _looks_like_mention(pattern) and _is_valid_regex(pattern)
+
+
+def _grep_metachar_hint(data) -> str:
+    """Advise ``--regex`` only when a metachar pattern actually found nothing.
+
+    Gating on an empty result set is what keeps this quiet: a literal pattern
+    that matched is not a mistake, however many metacharacters it contains.
+    """
+    if data.get("wikiGrep"):
+        return ""
+    return GREP_METACHAR_HINT
+
+
 def register(subparsers) -> None:
     """Register the ``wiki`` noun group and all its verbs."""
     group = subparsers.add_parser(
@@ -50,7 +172,14 @@ def register(subparsers) -> None:
     p = verbs.add_parser("search", help="search pages (text or semantic)")
     p.add_argument("query")
     p.add_argument("--semantic", action="store_true", help="semantic (embedding) search instead of full-text")
-    p.add_argument("--limit", type=int, default=10)
+    p.add_argument("--limit", type=int, default=10, help="how many pages to return")
+    p.add_argument("--offset", type=int, default=0, help="skip this many pages first (not with --semantic)")
+    p.add_argument(
+        "--order-by",
+        choices=ORDER_FIELD_CHOICES,
+        help="order by this field (default: relevance when searching, else updatedAt)",
+    )
+    p.add_argument("--direction", choices=DIRECTION_CHOICES, help="sort direction (default: the field's natural one)")
     _add_wiki_arg(p)
     add_output_args(p)
     p.set_defaults(func=search)
@@ -160,8 +289,24 @@ def read(args) -> int:
 
 
 def search(args) -> int:
+    """Full-text (``wikiPages``) or semantic (``wikiSemanticSearch``) page search.
+
+    ``--limit`` is the count on both paths; it spells ``first`` on ``wikiPages``, which
+    pairs it with ``--offset`` to skip, and ``limit`` on the semantic op. The cursor
+    (``after``) is deliberately not surfaced as a flag — a shell caller has nowhere to keep
+    a cursor between invocations, which is the gap ``--offset`` exists to close. Reach for
+    ``gql`` if you need a cursor walk.
+
+    The ordering flags are gated client-side on the semantic path because the op there has
+    no argument to reject them with: passing ``--order-by`` to a request that cannot carry
+    it would silently return cosine-ranked rows as though the flag had applied. ``--offset``
+    is measured against its default rather than truthiness — 0 is the same request as
+    absent, so only a caller who actually asked to skip is refused.
+    """
     wiki = _wiki_slug(args)
     if args.semantic:
+        if args.order_by or args.direction or args.offset != 0:
+            raise ConfigError(SEMANTIC_ORDER_CONFLICT)
         document = (
             "query($wiki:String!,$query:String!,$limit:Int!){"
             "wikiSemanticSearch(wiki:$wiki,query:$query,limit:$limit){"
@@ -169,11 +314,21 @@ def search(args) -> int:
         )
         return run_op(args, document, {"wiki": wiki, "query": args.query, "limit": args.limit})
     document = (
-        "query($wiki:String!,$search:String,$first:Int!){"
-        "wikiPages(wiki:$wiki,search:$search,first:$first){"
-        "totalCount nodes{path title summary status}}}"
+        "query($wiki:String!,$search:String,$first:Int!,$offset:Int!,"
+        "$orderBy:WikiPageOrderField,$direction:SortDirection){"
+        "wikiPages(wiki:$wiki,search:$search,first:$first,offset:$offset,"
+        "orderBy:$orderBy,direction:$direction){"
+        "totalCount order{field direction} nodes{path title summary status}}}"
     )
-    return run_op(args, document, {"wiki": wiki, "search": args.query, "first": args.limit})
+    variables = {
+        "wiki": wiki,
+        "search": args.query,
+        "first": args.limit,
+        "offset": args.offset,
+        "orderBy": args.order_by,
+        "direction": args.direction,
+    }
+    return run_op(args, document, variables)
 
 
 def grep(args) -> int:
@@ -189,7 +344,10 @@ def grep(args) -> int:
         "context": args.context,
         "limit": args.limit,
     }
-    return run_op(args, document, variables)
+    hint = None
+    if not args.regex and _should_hint_regex(args.pattern):
+        hint = _grep_metachar_hint
+    return run_op(args, document, variables, hint=hint)
 
 
 def create(args) -> int:
@@ -279,6 +437,8 @@ def bulk_status(args) -> int:
 
 
 def related(args) -> int:
+    if not TASK_IDENTIFIER_RE.fullmatch(args.task_id):
+        raise ConfigError("wiki related takes a task identifier (e.g. takt-42), not a page path")
     document = (
         "query($identifier:String!,$wiki:String!,$limit:Int!){"
         "findRelatedWikiPages(identifier:$identifier,wiki:$wiki,limit:$limit){"

{taktcli-0.2.0 → taktcli-0.3.0}/taktcli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taktcli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
 Author: Takt
 License: MIT
@@ -139,7 +139,7 @@ Every MCP tool maps to a verb:
 | `get_task_comments` | `task comments <id>` |
 | `attach_result` | `task result <id>` |
 | `get_task_results` | `task results <id>` |
-| `delete_result` | `task result delete <id>` |
+| `delete_result` | `task result-delete <id>` |
 | `wiki_read` | `wiki read <path>` |
 | `wiki_search` / `wiki_semantic_search` | `wiki search <q>` (`--semantic`) |
 | `wiki_grep` | `wiki grep <pattern>` |

{taktcli-0.2.0 → taktcli-0.3.0}/taktcli.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ tests/test_project.py
 tests/test_schema.py
 tests/test_task.py
 tests/test_transport.py
+tests/test_version.py
 tests/test_watch.py
 tests/test_wiki.py
 tests/test_workspace.py

{taktcli-0.2.0 → taktcli-0.3.0}/tests/test_task.py

@@ -30,6 +30,23 @@ def patch(monkeypatch, *, envelope=None, capture=None, raises=None):
     return capture
 
 
+def patch_calls(monkeypatch, envelopes):
+    """Stub auth + execute with a per-call envelope queue, recording every call.
+
+    ``create --parent`` spends two round-trips (resolve identifier -> createTask),
+    so these tests need each call's document/variables, not just the last one.
+    """
+    monkeypatch.setattr("taktcli.commands._exec.resolve_auth", lambda: (URL, TOKEN))
+    calls = []
+
+    def fake_execute(query, variables=None, *, url, token, **kwargs):
+        calls.append({"query": query, "variables": variables})
+        return envelopes[len(calls) - 1]
+
+    monkeypatch.setattr("taktcli.commands._exec.execute", fake_execute)
+    return calls
+
+
 def test_get_builds_task_query(monkeypatch, capsys):
     cap = patch(monkeypatch, envelope={"data": {"task": {"identifier": "takt-1"}}}, capture={})
     assert main(["task", "get", "takt-1"]) == 0
@@ -101,6 +118,63 @@ def test_create_desc_and_desc_file_conflict_exits_3(monkeypatch, capsys, tmp_pat
     assert "not both" in capsys.readouterr().err
 
 
+def test_create_parent_resolves_identifier_to_uuid(monkeypatch):
+    calls = patch_calls(monkeypatch, [
+        {"data": {"task": {"id": "3f1c-uuid-10"}}},
+        {"data": {"createTask": {"identifier": "takt-11"}}},
+    ])
+    assert main([
+        "task", "create", "--project", "takt", "--title", "x",
+        "--parent", "takt-10", "--status", "PENDING",
+    ]) == 0
+    assert len(calls) == 2
+    assert "task(identifier: $id) { id }" in calls[0]["query"]
+    assert calls[0]["variables"] == {"id": "takt-10"}
+    assert calls[1]["variables"]["input"] == {
+        "title": "x",
+        "parentId": "3f1c-uuid-10",
+        "status": "PENDING",
+    }
+
+
+def test_create_parent_id_passes_uuid_through_without_lookup(monkeypatch):
+    calls = patch_calls(monkeypatch, [{"data": {"createTask": {"identifier": "takt-11"}}}])
+    assert main(["task", "create", "--title", "x", "--parent-id", "3f1c-uuid-10"]) == 0
+    assert len(calls) == 1
+    assert "createTask" in calls[0]["query"]
+    assert calls[0]["variables"]["input"] == {"title": "x", "parentId": "3f1c-uuid-10"}
+
+
+def test_create_parent_and_parent_id_conflict_exits_3(monkeypatch, capsys):
+    calls = patch_calls(monkeypatch, [])
+    assert main([
+        "task", "create", "--title", "x",
+        "--parent", "takt-10", "--parent-id", "3f1c-uuid-10",
+    ]) == 3
+    assert "not both" in capsys.readouterr().err
+    assert calls == []
+
+
+@pytest.mark.parametrize("flag", ["--parent", "--parent-id"])
+def test_create_empty_parent_flag_exits_3_without_creating(monkeypatch, capsys, flag):
+    """An empty parent value must not silently create a parentless task.
+
+    ``createTask`` coerces a falsy ``parentId`` to ``None``, so an unguarded
+    empty string reaches the server and parents nothing at exit 0.
+    """
+    calls = patch_calls(monkeypatch, [])
+    assert main(["task", "create", "--title", "x", flag, ""]) == 3
+    assert f"{flag}: empty value" in capsys.readouterr().err
+    assert calls == []
+
+
+def test_create_parent_unknown_identifier_exits_3_before_creating(monkeypatch, capsys):
+    calls = patch_calls(monkeypatch, [{"data": {"task": None}}])
+    assert main(["task", "create", "--title", "x", "--parent", "takt-999"]) == 3
+    assert "no task found with identifier 'takt-999'" in capsys.readouterr().err
+    assert len(calls) == 1
+
+
 def test_update_sets_fields(monkeypatch):
     cap = patch(monkeypatch, capture={})
     main(["task", "update", "takt-1", "--title", "New", "--label-add", "dx"])

taktcli-0.3.0/tests/test_version.py

@@ -0,0 +1,44 @@
+"""__version__ is single-sourced from distribution metadata, with a dev fallback."""
+
+import importlib.metadata
+
+import pytest
+
+import taktcli
+from taktcli import _resolve_version
+from taktcli.__main__ import main
+
+
+def test_resolve_version_reads_the_taktcli_distribution(monkeypatch):
+    queried = []
+
+    def fake_version(name):
+        queried.append(name)
+        return "9.9.9"
+
+    monkeypatch.setattr(taktcli, "version", fake_version)
+    assert _resolve_version() == "9.9.9"
+    assert queried == ["taktcli"]
+
+
+def test_resolve_version_falls_back_when_not_installed(monkeypatch):
+    def not_installed(name):
+        raise importlib.metadata.PackageNotFoundError(name)
+
+    monkeypatch.setattr(taktcli, "version", not_installed)
+    assert _resolve_version() == "0.0.0.dev0"
+
+
+def test_version_matches_installed_distribution():
+    try:
+        installed = importlib.metadata.version("taktcli")
+    except importlib.metadata.PackageNotFoundError:
+        pytest.skip("taktcli is not pip-installed in this environment")
+    assert taktcli.__version__ == installed
+
+
+def test_version_flag_reports_resolved_version(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.strip() == f"taktcli {taktcli.__version__}"