taktcli 0.1.0__tar.gz

taktcli-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: taktcli
+Version: 0.1.0
+Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
+Author: Takt
+License: MIT
+Project-URL: Homepage, https://takt.sh
+Project-URL: Repository, https://github.com/muzhig/takt
+Keywords: takt,graphql,cli,agents
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: watch
+Requires-Dist: websockets>=12.0; extra == "watch"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# taktcli
+
+Authorized GraphQL CLI for [Takt](https://takt.sh) — the full GraphQL surface
+from the shell, for agents and humans. Package and console-script are both
+named `taktcli` (bare `takt` is taken on PyPI).
+
+The core is **stdlib-only** (`urllib` + `argparse` + `json`): `argv → GraphQL-over-HTTP`.
+It sidesteps the MCP client-serialization bug class entirely — argv strings can't
+be double-JSON-encoded. See PRD 002 in the Takt wiki (`takt/dev/prd-002-taktcli`).
+
+## Install
+
+```bash
+pip install taktcli            # stdlib-only core
+pip install 'taktcli[watch]'   # + websockets, enables `taktcli watch`
+```
+
+From a checkout (monorepo subdir):
+
+```bash
+pip install -e cli/
+```
+
+## Auth (PRD §6)
+
+Resolution order, simplest-wins:
+
+- **Token:** `TAKT_TOKEN` env → `~/.takt/credentials.json` → error `Run: taktcli login` (exit 3)
+- **URL:** `TAKT_URL` env → `url` in the credentials file → default `https://api.takt.sh/graphql`
+
+`~/.takt/credentials.json` is plain JSON (no YAML dependency):
+
+```json
+{ "token": "<jwt>", "url": "https://api.takt.sh/graphql" }
+```
+
+### Login
+
+`taktcli login` runs the OAuth 2.0 device-authorization grant: it prints a
+verification URL + user code, polls until you approve in the browser, then
+writes `{token, url}` to `~/.takt/credentials.json` (mode `0600`).
+
+```bash
+taktcli login                                       # default endpoint
+taktcli login --url http://localhost:8454/graphql   # override the endpoint
+taktcli logout                                      # remove the stored credential
+taktcli whoami                                      # nickname + claims + active source
+```
+
+`--url` (highest) → `TAKT_URL` env → default decides where `login` authenticates.
+`whoami` reports which credential source is active (`TAKT_TOKEN` env vs the file).
+
+## Exit codes (PRD §4.3)
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | GraphQL error (server reached; `errors[]` non-empty) |
+| `2` | transport error (DNS/TCP/TLS/HTTP non-2xx/timeout) |
+| `3` | config or usage error (no token, bad URL, unknown verb, missing flag) |
+
+`extensions.code` (e.g. `LEASE_EXPIRED`, `ALREADY_CLAIMED`) is preserved in
+error output so loops can branch on it.
+
+## Shared I/O flags (PRD §4)
+
+- `--var KEY=VALUE` (repeatable; value parsed as JSON when valid, else string)
+- `--vars JSON` / `--vars-file PATH` (`-` = stdin) — bulk variables
+- `--field-file NAME=PATH` (`NAME=-` = stdin) — inject a file's contents as a
+  variable; the canonical path for large markdown
+- `--raw` — full envelope `{data, errors, extensions}`; default is pretty JSON of `.data`
+- `--compact` — single-line JSON
+
+Variable precedence (lowest → highest): `--vars-file` < `--vars` < `--var` < `--field-file`.
+
+## Status
+
+Implemented: **A** (foundation — package skeleton, transport, auth/URL
+resolution, shared I/O plumbing, CI/release), **B** (`gql` + `schema`
+passthrough), **C** (hot-path aliases + `task …`), **D** (`wiki …` +
+`workspace …`), **G** (`login`/`logout`/`whoami`), and **H** (`label …`,
+`notif …`, `project …`). Curated verbs each map to a GraphQL op via
+`transport.execute`; the `wiki`/`workspace` verbs take a global `--wiki SLUG`
+(default `$TAKT_WIKI`) and stream big markdown through
+`--content-file`/`--old-file`/`--new-file` (`-` = stdin).
+
+`label create` is CLI-only (the MCP server never wrapped `createLabel`, but the
+GraphQL mutation exists). `label update`/`delete` are keyed by **name** and
+resolve the id client-side via the `labels` query, mirroring the MCP tools.
+`project rename` is name-only — slug changes are blocked on backend
+[[takt-304]]. Per the [[takt-83]] guardrail there is **no** claims/permission
+verb anywhere in the surface.
+
+The remaining verb groups are stubs — running one exits 3 with a pointer to its
+implementing subtask (E media/file, F watch, J delete-result).
+
+## Release
+
+Push a `cli-v*` tag (e.g. `cli-v0.1.0`) — `.github/workflows/cli.yaml` builds
+`cli/` and OIDC trusted-publishes to PyPI. The tag must match the version in
+`cli/pyproject.toml` (CI asserts this).

taktcli-0.1.0/README.md

@@ -0,0 +1,101 @@
+# taktcli
+
+Authorized GraphQL CLI for [Takt](https://takt.sh) — the full GraphQL surface
+from the shell, for agents and humans. Package and console-script are both
+named `taktcli` (bare `takt` is taken on PyPI).
+
+The core is **stdlib-only** (`urllib` + `argparse` + `json`): `argv → GraphQL-over-HTTP`.
+It sidesteps the MCP client-serialization bug class entirely — argv strings can't
+be double-JSON-encoded. See PRD 002 in the Takt wiki (`takt/dev/prd-002-taktcli`).
+
+## Install
+
+```bash
+pip install taktcli            # stdlib-only core
+pip install 'taktcli[watch]'   # + websockets, enables `taktcli watch`
+```
+
+From a checkout (monorepo subdir):
+
+```bash
+pip install -e cli/
+```
+
+## Auth (PRD §6)
+
+Resolution order, simplest-wins:
+
+- **Token:** `TAKT_TOKEN` env → `~/.takt/credentials.json` → error `Run: taktcli login` (exit 3)
+- **URL:** `TAKT_URL` env → `url` in the credentials file → default `https://api.takt.sh/graphql`
+
+`~/.takt/credentials.json` is plain JSON (no YAML dependency):
+
+```json
+{ "token": "<jwt>", "url": "https://api.takt.sh/graphql" }
+```
+
+### Login
+
+`taktcli login` runs the OAuth 2.0 device-authorization grant: it prints a
+verification URL + user code, polls until you approve in the browser, then
+writes `{token, url}` to `~/.takt/credentials.json` (mode `0600`).
+
+```bash
+taktcli login                                       # default endpoint
+taktcli login --url http://localhost:8454/graphql   # override the endpoint
+taktcli logout                                      # remove the stored credential
+taktcli whoami                                      # nickname + claims + active source
+```
+
+`--url` (highest) → `TAKT_URL` env → default decides where `login` authenticates.
+`whoami` reports which credential source is active (`TAKT_TOKEN` env vs the file).
+
+## Exit codes (PRD §4.3)
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | GraphQL error (server reached; `errors[]` non-empty) |
+| `2` | transport error (DNS/TCP/TLS/HTTP non-2xx/timeout) |
+| `3` | config or usage error (no token, bad URL, unknown verb, missing flag) |
+
+`extensions.code` (e.g. `LEASE_EXPIRED`, `ALREADY_CLAIMED`) is preserved in
+error output so loops can branch on it.
+
+## Shared I/O flags (PRD §4)
+
+- `--var KEY=VALUE` (repeatable; value parsed as JSON when valid, else string)
+- `--vars JSON` / `--vars-file PATH` (`-` = stdin) — bulk variables
+- `--field-file NAME=PATH` (`NAME=-` = stdin) — inject a file's contents as a
+  variable; the canonical path for large markdown
+- `--raw` — full envelope `{data, errors, extensions}`; default is pretty JSON of `.data`
+- `--compact` — single-line JSON
+
+Variable precedence (lowest → highest): `--vars-file` < `--vars` < `--var` < `--field-file`.
+
+## Status
+
+Implemented: **A** (foundation — package skeleton, transport, auth/URL
+resolution, shared I/O plumbing, CI/release), **B** (`gql` + `schema`
+passthrough), **C** (hot-path aliases + `task …`), **D** (`wiki …` +
+`workspace …`), **G** (`login`/`logout`/`whoami`), and **H** (`label …`,
+`notif …`, `project …`). Curated verbs each map to a GraphQL op via
+`transport.execute`; the `wiki`/`workspace` verbs take a global `--wiki SLUG`
+(default `$TAKT_WIKI`) and stream big markdown through
+`--content-file`/`--old-file`/`--new-file` (`-` = stdin).
+
+`label create` is CLI-only (the MCP server never wrapped `createLabel`, but the
+GraphQL mutation exists). `label update`/`delete` are keyed by **name** and
+resolve the id client-side via the `labels` query, mirroring the MCP tools.
+`project rename` is name-only — slug changes are blocked on backend
+[[takt-304]]. Per the [[takt-83]] guardrail there is **no** claims/permission
+verb anywhere in the surface.
+
+The remaining verb groups are stubs — running one exits 3 with a pointer to its
+implementing subtask (E media/file, F watch, J delete-result).
+
+## Release
+
+Push a `cli-v*` tag (e.g. `cli-v0.1.0`) — `.github/workflows/cli.yaml` builds
+`cli/` and OIDC trusted-publishes to PyPI. The tag must match the version in
+`cli/pyproject.toml` (CI asserts this).

taktcli-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "taktcli"
+version = "0.1.0"
+description = "Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Takt" }]
+keywords = ["takt", "graphql", "cli", "agents"]
+dependencies = []
+
+[project.optional-dependencies]
+watch = ["websockets>=12.0"]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+taktcli = "taktcli.__main__:main"
+
+[project.urls]
+Homepage = "https://takt.sh"
+Repository = "https://github.com/muzhig/takt"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+include = ["taktcli*"]
+
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"

taktcli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taktcli-0.1.0/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-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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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