taktcli 0.1.0__py3-none-any.whl

taktcli/__init__.py

@@ -0,0 +1,6 @@
+"""taktcli — authorized GraphQL CLI for Takt.
+
+Stdlib-only core: argv -> GraphQL-over-HTTP. See PRD 002 in the takt wiki.
+"""
+
+__version__ = "0.1.0"

taktcli/__main__.py

@@ -0,0 +1,53 @@
+"""taktcli entry point — argparse dispatch (PRD 002 §3, §4.3).
+
+Resolves the command tree, runs the selected handler, and maps typed errors to
+the exit-code contract. Usage/parse errors exit 3 (config/usage), not argparse's
+default 2 (which the contract reserves for transport failures).
+"""
+
+import argparse
+import sys
+
+from . import __version__, commands
+from .errors import TaktCliError
+
+
+class TaktArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser whose parse/usage errors exit 3, per the CLI contract."""
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(3, f"{self.prog}: error: {message}\n")
+
+
+def build_parser() -> TaktArgumentParser:
+    """Build the top-level parser with all noun groups and verbs registered."""
+    parser = TaktArgumentParser(
+        prog="taktcli",
+        description="Authorized GraphQL CLI for Takt — full GraphQL surface from the shell.",
+        epilog="Run 'taktcli <noun> --help' for a group's verbs. Most verbs land in subtasks B-J.",
+    )
+    parser.add_argument("--version", action="version", version=f"taktcli {__version__}")
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>", required=True)
+    commands.register(subparsers)
+    return parser
+
+
+def main(argv=None) -> int:
+    """Parse argv, dispatch to the handler, and return the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "func", None)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return 3
+    try:
+        result = handler(args)
+    except TaktCliError as exc:
+        print(exc.render(), file=sys.stderr)
+        return exc.exit_code
+    return int(result or 0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

taktcli/auth.py

@@ -0,0 +1,104 @@
+"""Auth + URL resolution (PRD 002 §6).
+
+Resolution order (simplest-wins):
+
+Token:  ``TAKT_TOKEN`` env  ->  ``~/.takt/credentials.json``  ->  error (exit 3)
+URL:    ``TAKT_URL`` env    ->  ``url`` in credentials file    ->  default
+
+Full ``taktcli login`` (device-auth) is subtask G2; this module only reads
+the JSON credential store and resolves the active token/URL.
+"""
+
+import json
+import os
+from pathlib import Path
+
+from .errors import ConfigError
+
+DEFAULT_URL = "https://api.takt.sh/graphql"
+
+LOGIN_HINT = "No Takt credentials found. Run: taktcli login"
+
+
+def credentials_path() -> Path:
+    """Location of the JSON credential store (``~/.takt/credentials.json``)."""
+    return Path.home() / ".takt" / "credentials.json"
+
+
+def load_credentials(path: Path | None = None) -> dict:
+    """Read the JSON credential store. Missing file -> ``{}``.
+
+    A present-but-corrupt file is a configuration error (exit 3), not a
+    silent empty read — surface it so the user can fix the file.
+    """
+    path = path or credentials_path()
+    if not path.exists():
+        return {}
+    raw = path.read_text()
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Corrupt credentials file at {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"Credentials file at {path} must be a JSON object")
+    return data
+
+
+def resolve_token(credentials: dict | None = None) -> str:
+    """Resolve the bearer token: env -> file -> error (exit 3)."""
+    env_token = os.environ.get("TAKT_TOKEN")
+    if env_token:
+        return env_token
+    creds = load_credentials() if credentials is None else credentials
+    token = creds.get("token")
+    if token:
+        return token
+    raise ConfigError(LOGIN_HINT)
+
+
+def resolve_url(credentials: dict | None = None) -> str:
+    """Resolve the GraphQL endpoint: env -> file -> default."""
+    env_url = os.environ.get("TAKT_URL")
+    if env_url:
+        return env_url
+    creds = load_credentials() if credentials is None else credentials
+    return creds.get("url") or DEFAULT_URL
+
+
+def resolve_auth() -> tuple[str, str]:
+    """Resolve ``(url, token)`` in one pass, reading the file at most once."""
+    creds = load_credentials()
+    return resolve_url(creds), resolve_token(creds)
+
+
+def token_source() -> str | None:
+    """Describe where the active token comes from, or ``None`` if there is none.
+
+    Mirrors :func:`resolve_token`'s precedence: env wins over the file.
+    """
+    if os.environ.get("TAKT_TOKEN"):
+        return "TAKT_TOKEN env"
+    if load_credentials().get("token"):
+        return f"credentials file ({credentials_path()})"
+    return None
+
+
+def save_credentials(token: str, url: str, path: Path | None = None) -> Path:
+    """Persist ``{token, url}`` to the JSON store, creating ``~/.takt`` as 0700.
+
+    The file is written 0600 — it holds a bearer token.
+    """
+    path = path or credentials_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.write_text(json.dumps({"token": token, "url": url}, indent=2) + "\n")
+    path.chmod(0o600)
+    return path
+
+
+def clear_credentials(path: Path | None = None) -> bool:
+    """Remove the credential store. Returns ``True`` if a file was deleted."""
+    path = path or credentials_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False

taktcli/commands/__init__.py

@@ -0,0 +1,68 @@
+"""Command surface for taktcli (PRD 002 §3).
+
+This module declares the noun/verb tree. Implemented surfaces register their own
+parsers via per-module ``register`` functions; the remaining groups are stubs
+(running one exits 3 with a pointer to the implementing subtask) until they land.
+"""
+
+from ..errors import ConfigError
+from ..io import add_shared_io_args
+from . import auth, file, gql, hotpath, label, notif, project, schema, task, watch, wiki, workspace
+
+NOUN_GROUPS = {}
+
+
+def _stub(path: str, subtask: str):
+    def handler(args):
+        raise ConfigError(
+            f"`taktcli {path}` is not implemented yet (subtask {subtask})."
+        )
+
+    return handler
+
+
+def _add_leaf(subparsers, name: str, spec, path_prefix: str) -> None:
+    help_text = spec["help"] if isinstance(spec, dict) else spec
+    subtask = spec.get("subtask", "?") if isinstance(spec, dict) else "?"
+    leaf = subparsers.add_parser(name, help=help_text, description=help_text)
+    path = f"{path_prefix}{name}".strip()
+    if isinstance(spec, dict) and spec.get("io"):
+        add_shared_io_args(leaf)
+    else:
+        leaf.add_argument("args", nargs="*", help="(stub — see implementing subtask)")
+    leaf.set_defaults(func=_stub(path, subtask))
+
+
+def _add_group(subparsers, name: str, spec: dict, path_prefix: str, parent_subtask: str = "?") -> None:
+    group = subparsers.add_parser(name, help=spec["help"], description=spec["help"])
+    sub = group.add_subparsers(dest=f"{name}_verb", metavar="<verb>", required=True)
+    group_subtask = spec.get("subtask", parent_subtask)
+    for verb, verb_spec in spec["verbs"].items():
+        path = f"{path_prefix}{name} "
+        if isinstance(verb_spec, dict) and "verbs" in verb_spec:
+            _add_group(sub, verb, verb_spec, path, group_subtask)
+        else:
+            leaf_spec = (
+                {"help": verb_spec, "subtask": group_subtask}
+                if isinstance(verb_spec, str)
+                else {**verb_spec, "subtask": verb_spec.get("subtask", group_subtask)}
+            )
+            _add_leaf(sub, verb, leaf_spec, path)
+
+
+def register(subparsers) -> None:
+    """Register every implemented verb plus the remaining stub groups."""
+    gql.register(subparsers)
+    schema.register(subparsers)
+    auth.register(subparsers)
+    hotpath.register(subparsers)
+    task.register(subparsers)
+    file.register(subparsers)
+    wiki.register(subparsers)
+    workspace.register(subparsers)
+    label.register(subparsers)
+    notif.register(subparsers)
+    project.register(subparsers)
+    watch.register(subparsers)
+    for name, spec in NOUN_GROUPS.items():
+        _add_group(subparsers, name, spec, "")

taktcli/commands/_exec.py

@@ -0,0 +1,85 @@
+"""Shared execution + I/O helpers for the task verbs and hot-path aliases.
+
+Every verb in subtask C builds a GraphQL document plus a variables dict and runs
+it through :func:`run_operation` (or :func:`fetch` when it needs the raw envelope
+back). Auth, transport, output formatting, and the exit-code contract are all
+funnelled through here so the verbs stay declarative (PRD 002 §3.3, §3.4, §4).
+"""
+
+import argparse
+import os
+import sys
+
+from ..auth import resolve_auth
+from ..errors import ConfigError
+from ..io import format_output, read_path
+from ..transport import execute
+
+
+def add_output_args(parser: argparse.ArgumentParser) -> None:
+    """Attach the ``--raw``/``--compact`` output flags to a verb parser."""
+    group = parser.add_argument_group("output")
+    group.add_argument(
+        "--raw",
+        action="store_true",
+        help="print the full GraphQL envelope {data, errors, extensions}",
+    )
+    group.add_argument(
+        "--compact",
+        action="store_true",
+        help="single-line JSON output (pipe-friendly)",
+    )
+
+
+def fetch(document: str, variables: dict) -> dict:
+    """Resolve auth, run the operation, and return the full GraphQL envelope."""
+    url, token = resolve_auth()
+    return execute(document, variables, url=url, token=token)
+
+
+def run_operation(args, document: str, variables: dict) -> int:
+    """Execute ``document`` and print the formatted envelope; return exit 0."""
+    envelope = fetch(document, variables)
+    print(format_output(envelope, raw=getattr(args, "raw", False), compact=getattr(args, "compact", False)))
+    sys.stdout.flush()
+    return 0
+
+
+def resolve_lease(args) -> str | None:
+    """Resolve a lease id: ``--lease`` flag, else ``$TAKT_LEASE``, else None."""
+    lease = getattr(args, "lease", None)
+    if lease:
+        return lease
+    return os.environ.get("TAKT_LEASE") or None
+
+
+def text_from_flags(inline, path, inline_flag: str, file_flag: str):
+    """Resolve a text value from an inline flag or a ``*-file`` path.
+
+    ``path`` of ``-`` reads stdin. Passing both is a usage error (exit 3).
+    Returns ``None`` when neither is provided so callers can decide if the
+    field is required.
+    """
+    if inline is not None and path is not None:
+        raise ConfigError(f"pass either {inline_flag} or {file_flag}, not both")
+    if path is not None:
+        return read_path(path)
+    return inline
+
+
+def build_operation(name: str, field: str, arg_specs: list, selection: str, *, op_type: str = "query"):
+    """Assemble a single-field GraphQL operation from provided arguments.
+
+    ``arg_specs`` is a list of ``(var_name, gql_type, arg_name, value)`` tuples,
+    one per *provided* argument — only these are declared and passed, so the
+    document never references an unused (and therefore illegal) variable. The
+    ``selection`` string includes its own surrounding braces.
+    """
+    decls = ", ".join(f"${var}: {gql_type}" for var, gql_type, _, _ in arg_specs)
+    decl_str = f"({decls})" if decls else ""
+    field_args = ", ".join(f"{arg}: ${var}" for var, _, arg, _ in arg_specs)
+    field_args_str = f"({field_args})" if field_args else ""
+    selection_str = f" {selection}" if selection else ""
+    document = f"{op_type} {name}{decl_str} {{ {field}{field_args_str}{selection_str} }}"
+    variables = {var: value for var, _, _, value in arg_specs}
+    return document, variables

taktcli/commands/_run.py

@@ -0,0 +1,51 @@
+"""Shared helpers for curated noun/verb commands (PRD 002 §3.4-§3.8).
+
+Curated verbs map a fixed GraphQL document plus a small set of typed flags to
+``transport.execute`` and print the result through the §4.2 output contract.
+This module holds the two pieces every curated verb repeats: running the op and
+resolving an inline-or-file (``-`` = stdin) text argument.
+"""
+
+import sys
+
+from ..auth import resolve_auth
+from ..errors import ConfigError
+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."""
+    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()
+    return 0
+
+
+def fetch_data(document: str, variables: dict) -> dict:
+    """Execute a GraphQL document and return its unwrapped ``.data`` payload.
+
+    For curated verbs that need a server lookup before their real op (e.g.
+    resolving a label name to its id) without printing the intermediate result.
+    """
+    url, token = resolve_auth()
+    envelope = execute(document, variables, url=url, token=token)
+    return (envelope or {}).get("data") or {}
+
+
+def resolve_text(inline, file_path, name: str, *, required: bool = False):
+    """Resolve a ``--<name>`` / ``--<name>-file`` (`-` = stdin) pair.
+
+    Passing both is a usage error; passing neither yields ``None`` unless
+    ``required``, in which case it is a usage error too.
+    """
+    if inline is not None and file_path is not None:
+        raise ConfigError(f"pass either --{name} or --{name}-file, not both")
+    if file_path is not None:
+        return read_path(file_path)
+    if inline is not None:
+        return inline
+    if required:
+        raise ConfigError(f"--{name} or --{name}-file is required")
+    return None

taktcli/commands/auth.py

@@ -0,0 +1,206 @@
+"""``taktcli login``/``logout``/``whoami`` — auth verbs (PRD 002 §3.9, §6).
+
+``login`` drives the OAuth 2.0 device-authorization grant against the backend
+(``requestDeviceCode`` -> poll ``pollDeviceToken`` until ``ISSUED``) and persists
+``{token, url}`` to ``~/.takt/credentials.json``. ``logout`` removes that file.
+``whoami`` runs the ``me`` query and reports which credential source is active.
+
+The device-code request and poll are unauthenticated (no token exists yet), so
+they post with an empty token; :mod:`..transport` omits the bearer header.
+"""
+
+import os
+import sys
+import time
+import urllib.request
+
+from ..auth import (
+    DEFAULT_URL,
+    clear_credentials,
+    credentials_path,
+    resolve_auth,
+    save_credentials,
+    token_source,
+)
+from ..errors import ConfigError
+from ..transport import execute
+
+REQUEST_DEVICE_CODE = """
+mutation RequestDeviceCode($clientName: String) {
+  requestDeviceCode(clientName: $clientName) {
+    deviceCode
+    userCode
+    verificationUri
+    verificationUriComplete
+    interval
+    expiresIn
+  }
+}
+""".strip()
+
+POLL_DEVICE_TOKEN = """
+mutation PollDeviceToken($deviceCode: String!) {
+  pollDeviceToken(deviceCode: $deviceCode) {
+    status
+    token
+    expiresAt
+  }
+}
+""".strip()
+
+ME_QUERY = """
+query Whoami {
+  me {
+    nickname
+    displayName
+    claims
+  }
+}
+""".strip()
+
+SLOW_DOWN_INCREMENT = 5
+DEFAULT_CLIENT_NAME = "taktcli"
+
+
+def register(subparsers) -> None:
+    """Register the ``login``/``logout``/``whoami`` verbs on the top level."""
+    login_help = "device-auth login; stores ~/.takt/credentials.json"
+    login = subparsers.add_parser("login", help=login_help, description=login_help)
+    login.add_argument(
+        "--url",
+        metavar="URL",
+        help="GraphQL endpoint to authenticate against (overrides TAKT_URL and the default)",
+    )
+    login.add_argument(
+        "--client-name",
+        metavar="NAME",
+        default=DEFAULT_CLIENT_NAME,
+        help="client name recorded with the device authorization request",
+    )
+    login.set_defaults(func=run_login)
+
+    logout_help = "remove the stored credential"
+    logout = subparsers.add_parser("logout", help=logout_help, description=logout_help)
+    logout.set_defaults(func=run_logout)
+
+    whoami_help = "print the authenticated identity (nickname + claims + source)"
+    whoami = subparsers.add_parser("whoami", help=whoami_help, description=whoami_help)
+    whoami.set_defaults(func=run_whoami)
+
+
+def _login_url(args) -> str:
+    """Resolve the endpoint for login: ``--url`` -> ``TAKT_URL`` -> default."""
+    return getattr(args, "url", None) or os.environ.get("TAKT_URL") or DEFAULT_URL
+
+
+def device_login(url, *, client_name=None, opener=None, sleep=None, out=None) -> str:
+    """Run the device-authorization grant and return the issued token.
+
+    Prints the verification URL + user code to ``out``, then polls until the
+    code is approved (``ISSUED``). Honours the server ``interval`` and bumps it
+    on ``SLOW_DOWN``. Terminal failure statuses raise ``ConfigError`` (exit 3).
+
+    ``opener``/``sleep``/``out`` resolve to the live ``urlopen``/``time.sleep``/
+    ``stderr`` when ``None`` — so monkeypatching those modules drives the flow.
+    """
+    opener = opener or urllib.request.urlopen
+    sleep = sleep or time.sleep
+    out = out if out is not None else sys.stderr
+    envelope = execute(
+        REQUEST_DEVICE_CODE,
+        {"clientName": client_name},
+        url=url,
+        token=None,
+        opener=opener,
+    )
+    grant = (envelope.get("data") or {}).get("requestDeviceCode")
+    if not grant:
+        raise ConfigError(f"Device-code request returned no grant from {url}")
+
+    device_code = grant["deviceCode"]
+    user_code = grant["userCode"]
+    interval = grant.get("interval") or 5
+    complete = grant.get("verificationUriComplete") or grant.get("verificationUri")
+
+    print("To authorize taktcli, visit:", file=out)
+    print(f"  {grant['verificationUri']}", file=out)
+    print(f"and enter the code: {user_code}", file=out)
+    if complete:
+        print(f"\nOr open this URL directly:\n  {complete}", file=out)
+    print("\nWaiting for approval...", file=out)
+    out.flush()
+
+    while True:
+        sleep(interval)
+        envelope = execute(
+            POLL_DEVICE_TOKEN,
+            {"deviceCode": device_code},
+            url=url,
+            token=None,
+            opener=opener,
+        )
+        result = (envelope.get("data") or {}).get("pollDeviceToken") or {}
+        status = result.get("status")
+        if status == "AUTHORIZATION_PENDING":
+            continue
+        if status == "SLOW_DOWN":
+            interval += SLOW_DOWN_INCREMENT
+            continue
+        if status == "ACCESS_DENIED":
+            raise ConfigError("Device authorization was denied.")
+        if status == "EXPIRED_TOKEN":
+            raise ConfigError("Device code expired before approval. Run: taktcli login")
+        if status == "ISSUED":
+            token = result.get("token")
+            if not token:
+                raise ConfigError("Server reported ISSUED but returned no token.")
+            return token
+        raise ConfigError(f"Unexpected device-token status: {status!r}")
+
+
+def run_login(args, *, opener=None, sleep=None, out=None) -> int:
+    """``taktcli login`` — device-auth, then persist ``{token, url}``."""
+    out = out if out is not None else sys.stderr
+    url = _login_url(args)
+    token = device_login(
+        url,
+        client_name=getattr(args, "client_name", DEFAULT_CLIENT_NAME),
+        opener=opener,
+        sleep=sleep,
+        out=out,
+    )
+    path = save_credentials(token, url)
+    print(f"Logged in. Credentials saved to {path}", file=out)
+    out.flush()
+    return 0
+
+
+def run_logout(args, *, out=None) -> int:
+    """``taktcli logout`` — remove the stored credential."""
+    out = out if out is not None else sys.stdout
+    path = credentials_path()
+    if clear_credentials(path):
+        print(f"Logged out. Removed {path}", file=out)
+    else:
+        print("Not logged in (no stored credential).", file=out)
+    out.flush()
+    return 0
+
+
+def run_whoami(args, *, opener=None, out=None) -> int:
+    """``taktcli whoami`` — print identity + active credential source."""
+    out = out if out is not None else sys.stdout
+    opener = opener or urllib.request.urlopen
+    url, token = resolve_auth()
+    envelope = execute(ME_QUERY, {}, url=url, token=token, opener=opener)
+    me = (envelope.get("data") or {}).get("me") or {}
+    source = token_source() or "unknown"
+    claims = me.get("claims") or []
+    print(f"nickname: {me.get('nickname')}", file=out)
+    if me.get("displayName"):
+        print(f"display name: {me['displayName']}", file=out)
+    print(f"claims: {', '.join(claims) if claims else '(none)'}", file=out)
+    print(f"source: {source}", file=out)
+    print(f"endpoint: {url}", file=out)
+    out.flush()
+    return 0