trello-axi 0.2.1__tar.gz

trello_axi-0.2.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.3
+Name: trello-axi
+Version: 0.2.1
+Summary: Agent-native, token-efficient CLI for Trello
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# trello-axi
+
+Agent-native, token-efficient CLI for Trello. It calls the official Trello REST API directly and implements the [AXI](https://axi.md/) design principles: compact truthful output, bounded reads, exact resolution, idempotent mutations, structured failures, batching, and non-interactive operation.
+
+## Install
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install trello-axi
+```
+
+For development:
+
+```bash
+uv sync --locked --all-groups
+uv run trello-axi --version
+```
+
+## Authentication
+
+Prefer environment variables in managed environments:
+
+```bash
+export TRELLO_API_KEY='...'
+export TRELLO_TOKEN='...'
+trello-axi auth status
+```
+
+Or store them locally (the file is created with mode `0600`):
+
+```bash
+trello-axi auth set --api-key '...' --token '...'
+```
+
+Install the bundled skill and optional Claude Code/Codex SessionStart hooks:
+
+```bash
+trello-axi setup skill
+trello-axi setup hooks
+```
+
+The hook installer preserves unmanaged hooks and updates only entries marked for `trello-axi`.
+
+Default path: `${XDG_CONFIG_HOME:-~/.config}/trello-axi/config.json`. Environment variables take precedence. Never commit the token or pass credentials through agent prompts.
+
+## Agent-oriented workflows
+
+No arguments returns live board data rather than help:
+
+```bash
+trello-axi
+trello-axi boards
+trello-axi board Dream
+trello-axi lists --board Dream
+trello-axi cards --board Dream --list Backlog --limit 50
+trello-axi search videoaula --board Dream
+trello-axi card view CARD_ID            # descriptions are bounded to 2,000 chars
+trello-axi card view CARD_ID --full     # explicitly request the complete description
+```
+
+Mutations:
+
+```bash
+trello-axi card create --board Dream --list Backlog --title 'Task' --description-file task.md
+trello-axi card ensure --board Dream --list Backlog --title 'Task' --description-file task.md
+trello-axi card update CARD_ID --title 'New title' --due 2026-06-01
+trello-axi card move CARD_ID --board Dream --list Doing
+trello-axi card comment CARD_ID --text 'Implementation started'
+trello-axi card add-label CARD_ID --label-id LABEL_ID
+trello-axi card add-checklist CARD_ID --name Acceptance --item 'Tests pass' --item 'Docs updated'
+trello-axi card archive CARD_ID
+```
+
+`ensure` is idempotent by exact case-insensitive title: it creates a missing card, moves/updates one match, leaves the desired state unchanged, and refuses ambiguous matches.
+
+Batch creation accepts JSON or YAML:
+
+```yaml
+cards:
+  - title: First task
+    description: Detailed scope
+  - title: Second task
+    due: '2026-06-30'
+```
+
+```bash
+trello-axi card create-batch --board Dream --list Backlog --file cards.yaml --ensure
+```
+
+## Output contract
+
+TOON-style output is the default and includes contextual next-command suggestions. JSON is available globally and uses a stable `{<resource>: ..., "help": [...]}` envelope:
+
+```bash
+trello-axi --format json cards --board Dream --limit 10
+```
+
+Unknown flags fail. Reads default to 50 records and are capped at 1000. Failures are written to stderr with stable exit codes:
+
+| Code | Meaning |
+|---:|---|
+| 0 | Success / desired state already satisfied |
+| 1 | Unexpected local failure |
+| 2 | Invalid input or configuration |
+| 3 | Authentication/permission failure |
+| 4 | Resource not found |
+| 5 | Ambiguous name; use an ID |
+| 6 | Trello API/network failure |
+
+## Scope
+
+The MVP supports boards and lists, card CRUD, search, moves, archive, comments, labels, checklists, idempotent ensure, and batch creation. It intentionally excludes Power-Ups, webhooks, OAuth multi-user applications, and destructive permanent deletion.
+
+## Development
+
+```bash
+uv sync --locked --all-groups
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check .
+uv run pytest
+uv build
+```
+
+## License
+
+MIT

trello_axi-0.2.1/README.md

@@ -0,0 +1,128 @@
+# trello-axi
+
+Agent-native, token-efficient CLI for Trello. It calls the official Trello REST API directly and implements the [AXI](https://axi.md/) design principles: compact truthful output, bounded reads, exact resolution, idempotent mutations, structured failures, batching, and non-interactive operation.
+
+## Install
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install trello-axi
+```
+
+For development:
+
+```bash
+uv sync --locked --all-groups
+uv run trello-axi --version
+```
+
+## Authentication
+
+Prefer environment variables in managed environments:
+
+```bash
+export TRELLO_API_KEY='...'
+export TRELLO_TOKEN='...'
+trello-axi auth status
+```
+
+Or store them locally (the file is created with mode `0600`):
+
+```bash
+trello-axi auth set --api-key '...' --token '...'
+```
+
+Install the bundled skill and optional Claude Code/Codex SessionStart hooks:
+
+```bash
+trello-axi setup skill
+trello-axi setup hooks
+```
+
+The hook installer preserves unmanaged hooks and updates only entries marked for `trello-axi`.
+
+Default path: `${XDG_CONFIG_HOME:-~/.config}/trello-axi/config.json`. Environment variables take precedence. Never commit the token or pass credentials through agent prompts.
+
+## Agent-oriented workflows
+
+No arguments returns live board data rather than help:
+
+```bash
+trello-axi
+trello-axi boards
+trello-axi board Dream
+trello-axi lists --board Dream
+trello-axi cards --board Dream --list Backlog --limit 50
+trello-axi search videoaula --board Dream
+trello-axi card view CARD_ID            # descriptions are bounded to 2,000 chars
+trello-axi card view CARD_ID --full     # explicitly request the complete description
+```
+
+Mutations:
+
+```bash
+trello-axi card create --board Dream --list Backlog --title 'Task' --description-file task.md
+trello-axi card ensure --board Dream --list Backlog --title 'Task' --description-file task.md
+trello-axi card update CARD_ID --title 'New title' --due 2026-06-01
+trello-axi card move CARD_ID --board Dream --list Doing
+trello-axi card comment CARD_ID --text 'Implementation started'
+trello-axi card add-label CARD_ID --label-id LABEL_ID
+trello-axi card add-checklist CARD_ID --name Acceptance --item 'Tests pass' --item 'Docs updated'
+trello-axi card archive CARD_ID
+```
+
+`ensure` is idempotent by exact case-insensitive title: it creates a missing card, moves/updates one match, leaves the desired state unchanged, and refuses ambiguous matches.
+
+Batch creation accepts JSON or YAML:
+
+```yaml
+cards:
+  - title: First task
+    description: Detailed scope
+  - title: Second task
+    due: '2026-06-30'
+```
+
+```bash
+trello-axi card create-batch --board Dream --list Backlog --file cards.yaml --ensure
+```
+
+## Output contract
+
+TOON-style output is the default and includes contextual next-command suggestions. JSON is available globally and uses a stable `{<resource>: ..., "help": [...]}` envelope:
+
+```bash
+trello-axi --format json cards --board Dream --limit 10
+```
+
+Unknown flags fail. Reads default to 50 records and are capped at 1000. Failures are written to stderr with stable exit codes:
+
+| Code | Meaning |
+|---:|---|
+| 0 | Success / desired state already satisfied |
+| 1 | Unexpected local failure |
+| 2 | Invalid input or configuration |
+| 3 | Authentication/permission failure |
+| 4 | Resource not found |
+| 5 | Ambiguous name; use an ID |
+| 6 | Trello API/network failure |
+
+## Scope
+
+The MVP supports boards and lists, card CRUD, search, moves, archive, comments, labels, checklists, idempotent ensure, and batch creation. It intentionally excludes Power-Ups, webhooks, OAuth multi-user applications, and destructive permanent deletion.
+
+## Development
+
+```bash
+uv sync --locked --all-groups
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check .
+uv run pytest
+uv build
+```
+
+## License
+
+MIT

trello_axi-0.2.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["uv_build>=0.8,<1"]
+build-backend = "uv_build"
+
+[project]
+name = "trello-axi"
+version = "0.2.1"
+description = "Agent-native, token-efficient CLI for Trello"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "pyyaml>=6.0.3",
+]
+
+[project.scripts]
+trello-axi = "trello_axi.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-httpx>=0.36.2",
+    "ruff>=0.12",
+    "ty>=0.0.1",
+]
+
+[tool.pytest.ini_options]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = ["src", "tests"]

trello_axi-0.2.1/src/trello_axi/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

trello_axi-0.2.1/src/trello_axi/cli.py

@@ -0,0 +1,371 @@
+"""Argument parsing and orchestration for trello-axi."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .client import TrelloClient
+from .config import load_credentials, save_credentials
+from .errors import TrelloAxiError
+from .models import board as normalize_board
+from .models import card as normalize_card
+from .models import trello_list as normalize_list
+from .output import emit, emit_error
+from .setup import install_hooks, install_skill
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="trello-axi", description="Agent-native Trello CLI")
+    parser.add_argument(
+        "--format", choices=("toon", "json"), default="toon", help="output format (default: toon)"
+    )
+    parser.add_argument("--version", action="version", version="trello-axi 0.2.1")
+    commands = parser.add_subparsers(dest="command")
+
+    auth = commands.add_parser("auth", help="manage and verify credentials")
+    auth_commands = auth.add_subparsers(dest="auth_command", required=True)
+    auth_set = auth_commands.add_parser("set", help="store credentials in a mode-0600 file")
+    auth_set.add_argument("--api-key", required=True)
+    auth_set.add_argument("--token", required=True)
+    auth_commands.add_parser("status", help="verify credentials against Trello")
+
+    setup = commands.add_parser("setup", help="install agent integration")
+    setup_commands = setup.add_subparsers(dest="setup_command", required=True)
+    setup_commands.add_parser("skill", help="install the bundled agent skill")
+    hooks = setup_commands.add_parser("hooks", help="install Claude/Codex SessionStart hooks")
+    hooks.add_argument(
+        "--command", dest="hook_command", help="absolute trello-axi executable used by hooks"
+    )
+
+    boards = commands.add_parser("boards", help="list visible boards")
+    boards.add_argument("--all", action="store_true", help="include closed boards")
+
+    board_cmd = commands.add_parser("board", help="show a board summary")
+    board_cmd.add_argument("board")
+
+    lists = commands.add_parser("lists", help="list board lists")
+    lists.add_argument("--board", required=True)
+    lists.add_argument("--all", action="store_true")
+
+    cards = commands.add_parser("cards", help="list cards")
+    cards.add_argument("--board", required=True)
+    cards.add_argument("--list")
+    cards.add_argument("--limit", type=_positive_int, default=50)
+    cards.add_argument("--full", action="store_true")
+
+    search = commands.add_parser("search", help="search cards")
+    search.add_argument("query")
+    search.add_argument("--board")
+    search.add_argument("--limit", type=_positive_int, default=50)
+    search.add_argument("--full", action="store_true")
+
+    card = commands.add_parser("card", help="inspect or mutate cards")
+    card_commands = card.add_subparsers(dest="card_command", required=True)
+    view = card_commands.add_parser("view")
+    view.add_argument("card")
+    view.add_argument("--board")
+    view.add_argument("--full", action="store_true", help="do not truncate the description")
+    create = card_commands.add_parser("create")
+    _create_args(create)
+    ensure = card_commands.add_parser("ensure", help="create, move, or update by unique title")
+    _create_args(ensure)
+    update = card_commands.add_parser("update")
+    update.add_argument("card")
+    update.add_argument("--title")
+    update.add_argument("--description")
+    update.add_argument("--description-file", type=Path)
+    update.add_argument("--due")
+    update.add_argument("--due-complete", choices=("true", "false"))
+    move = card_commands.add_parser("move")
+    move.add_argument("card")
+    move.add_argument("--board", required=True)
+    move.add_argument("--list", required=True)
+    archive = card_commands.add_parser("archive")
+    archive.add_argument("card")
+    comment = card_commands.add_parser("comment")
+    comment.add_argument("card")
+    comment.add_argument("--text", required=True)
+    label = card_commands.add_parser("add-label")
+    label.add_argument("card")
+    label.add_argument("--label-id", required=True)
+    checklist = card_commands.add_parser("add-checklist")
+    checklist.add_argument("card")
+    checklist.add_argument("--name", required=True)
+    checklist.add_argument("--item", action="append", default=[])
+    batch = card_commands.add_parser("create-batch", help="create cards from JSON/YAML")
+    batch.add_argument("--board", required=True)
+    batch.add_argument("--list", required=True)
+    batch.add_argument("--file", required=True, type=Path)
+    batch.add_argument(
+        "--ensure",
+        action="store_true",
+        help="idempotently ensure titles instead of always creating",
+    )
+    return parser
+
+
+def _create_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--board", required=True)
+    parser.add_argument("--list", required=True)
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--description", default="")
+    parser.add_argument("--description-file", type=Path)
+    parser.add_argument("--due")
+    parser.add_argument("--label-id", action="append", default=[])
+
+
+def _positive_int(value: str) -> int:
+    number = int(value)
+    if number < 1 or number > 1000:
+        raise argparse.ArgumentTypeError("must be between 1 and 1000")
+    return number
+
+
+def _description(args: argparse.Namespace) -> str:
+    if getattr(args, "description_file", None):
+        if getattr(args, "description", ""):
+            raise ValueError("use only one of --description and --description-file")
+        return args.description_file.read_text()
+    return getattr(args, "description", "") or ""
+
+
+def _load_batch(path: Path) -> list[dict[str, Any]]:
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except (OSError, yaml.YAMLError) as exc:
+        raise ValueError(f"cannot load batch file {path}: {exc}") from exc
+    if isinstance(raw, dict):
+        raw = raw.get("cards")
+    if not isinstance(raw, list) or not all(isinstance(item, dict) for item in raw):
+        raise ValueError("batch file must be a list, or an object containing a `cards` list")
+    for index, item in enumerate(raw, 1):
+        if not str(item.get("title", "")).strip():
+            raise ValueError(f"batch card {index} is missing a title")
+        label_ids = item.get("label_ids", [])
+        if not isinstance(label_ids, list) or not all(
+            isinstance(label_id, str) and label_id.strip() for label_id in label_ids
+        ):
+            raise ValueError(f"batch card {index} label_ids must be a list of strings")
+        due = item.get("due")
+        if due is not None and not isinstance(due, str):
+            raise ValueError(f"batch card {index} due must be a string")
+    return raw
+
+
+def run(args: argparse.Namespace) -> tuple[Any, str]:
+    if args.command == "auth" and args.auth_command == "set":
+        path = save_credentials(args.api_key, args.token)
+        return {"configured": True, "path": str(path), "permissions": "0600"}, "auth"
+    if args.command == "setup":
+        if args.setup_command == "skill":
+            path = install_skill()
+            return {"installed": True, "skill": str(path)}, "setup"
+        paths = install_hooks(command=args.hook_command)
+        return {"installed": True, "hooks": [str(path) for path in paths]}, "setup"
+    credentials = load_credentials()
+    with TrelloClient(credentials) as client:
+        if args.command == "auth":
+            member = client.member()
+            return {
+                "authenticated": True,
+                "username": member.get("username"),
+                "name": member.get("fullName"),
+            }, "auth"
+        if args.command in {None, "boards"}:
+            return [
+                normalize_board(item)
+                for item in client.boards(include_closed=getattr(args, "all", False))
+            ], "boards"
+        if args.command == "board":
+            selected = client.resolve_board(args.board)
+            lists = client.lists(args.board)
+            cards = client.all_cards(args.board)
+            counts = {item["id"]: 0 for item in lists}
+            for item in cards:
+                counts[item["idList"]] = counts.get(item["idList"], 0) + 1
+            return {
+                **normalize_board(selected),
+                "list_count": len(lists),
+                "open_card_count": len(cards),
+                "lists": [
+                    {"id": item["id"], "name": item["name"], "cards": counts[item["id"]]}
+                    for item in lists
+                ],
+            }, "board"
+        if args.command == "lists":
+            return [
+                normalize_list(item) for item in client.lists(args.board, include_closed=args.all)
+            ], "lists"
+        if args.command == "cards":
+            return [
+                normalize_card(item, full=args.full)
+                for item in client.cards(args.board, list_value=args.list, limit=args.limit)
+            ], "cards"
+        if args.command == "search":
+            return [
+                normalize_card(item, full=args.full)
+                for item in client.search(args.query, board=args.board, limit=args.limit)
+            ], "cards"
+        if args.command == "card":
+            return _run_card(client, args)
+    raise ValueError("unknown command")
+
+
+def _run_card(client: TrelloClient, args: argparse.Namespace) -> tuple[Any, str]:
+    command = args.card_command
+    if command == "view":
+        limit = None if args.full else 2000
+        return normalize_card(
+            client.card(args.card, board=args.board), full=True, description_limit=limit
+        ), "card"
+    if command in {"create", "ensure"}:
+        description = _description(args)
+        if command == "create":
+            result = client.create_card(
+                board=args.board,
+                list_value=args.list,
+                title=args.title,
+                description=description,
+                due=args.due,
+                label_ids=args.label_id,
+            )
+            action = "created"
+        else:
+            result, action = client.ensure_card(
+                board=args.board,
+                list_value=args.list,
+                title=args.title,
+                description=description,
+                due=args.due,
+                label_ids=args.label_id,
+            )
+        return {"action": action, **normalize_card(result, full=True)}, "card"
+    if command == "update":
+        description = _description(args) if args.description or args.description_file else None
+        if all(value is None for value in (args.title, description, args.due, args.due_complete)):
+            raise ValueError("card update requires at least one mutation flag")
+        result = client.update_card(
+            args.card,
+            name=args.title,
+            desc=description,
+            due=args.due,
+            dueComplete=args.due_complete,
+        )
+        return {"action": "updated", **normalize_card(result, full=True)}, "card"
+    if command == "move":
+        result, action = client.move_card(args.card, board=args.board, list_value=args.list)
+        return {"action": action, **normalize_card(result)}, "card"
+    if command == "archive":
+        result, action = client.archive_card(args.card)
+        return {"action": action, **normalize_card(result)}, "card"
+    if command == "comment":
+        result = client.comment(args.card, args.text)
+        return {"action": "commented", "id": result.get("id"), "card_id": args.card}, "comment"
+    if command == "add-label":
+        result = client.add_label(args.card, args.label_id)
+        return {"action": "label_added", "id": result.get("id")}, "label"
+    if command == "add-checklist":
+        result = client.add_checklist(args.card, args.name, args.item)
+        return {
+            "action": "checklist_added",
+            "id": result.get("id"),
+            "name": result.get("name"),
+            "items": len(args.item),
+        }, "checklist"
+    if command == "create-batch":
+        results = []
+        target = client.resolve_list(args.board, args.list)
+        index = client.index_cards(client.all_cards(args.board)) if args.ensure else {}
+        for item in _load_batch(args.file):
+            title = str(item["title"])
+            description = str(item.get("description", ""))
+            due = item.get("due")
+            label_ids = item.get("label_ids", ())
+            if args.ensure:
+                result, action = client.ensure_card(
+                    board=args.board,
+                    list_value=args.list,
+                    title=title,
+                    description=description,
+                    due=due,
+                    label_ids=label_ids,
+                    target_list=target,
+                    card_index=index,
+                )
+                index[title.casefold()] = [result]
+            else:
+                result = client.create_card_in_list(
+                    str(target["id"]),
+                    title=title,
+                    description=description,
+                    due=due,
+                    label_ids=label_ids,
+                )
+                action = "created"
+            results.append({"action": action, **normalize_card(result)})
+        return results, "cards"
+    raise ValueError(f"unsupported card command: {command}")
+
+
+def _next_steps(args: argparse.Namespace, data: Any) -> tuple[str, ...]:
+    if args.command in {None, "boards"}:
+        return ("trello-axi board <board-id>", "trello-axi lists --board <board-id>")
+    if args.command == "board":
+        return (
+            f"trello-axi cards --board {args.board} --list <list-id>",
+            f"trello-axi search <query> --board {args.board}",
+        )
+    if args.command == "lists":
+        return (f"trello-axi cards --board {args.board} --list <list-id>",)
+    if args.command in {"cards", "search"}:
+        return (
+            "trello-axi card view <card-id>",
+            "trello-axi card move <card-id> --board <board-id> --list <list-id>",
+        )
+    if args.command == "card" and isinstance(data, dict) and data.get("id"):
+        return (
+            f"trello-axi card view {data['id']}",
+            f"trello-axi card comment {data['id']} --text <text>",
+        )
+    if args.command == "setup":
+        return ("trello-axi auth status", "trello-axi boards")
+    if args.command == "auth":
+        return ("trello-axi boards", "trello-axi setup skill")
+    return ()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        data, name = run(args)
+        emit(
+            data,
+            fmt=args.format,
+            name=name,
+            help_commands=_next_steps(args, data),
+        )
+        return 0
+    except TrelloAxiError as exc:
+        emit_error(
+            str(exc),
+            code=exc.__class__.__name__,
+            fmt=args.format,
+            help_commands=("trello-axi auth status", "trello-axi --help"),
+        )
+        return exc.exit_code
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        emit_error(
+            str(exc), code="InputError", fmt=args.format, help_commands=("trello-axi --help",)
+        )
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

trello_axi-0.2.1/src/trello_axi/client.py

@@ -0,0 +1,262 @@
+"""Thin Trello REST adapter with exact-name resolution and safe mutations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import httpx
+
+from .config import Credentials
+from .errors import AmbiguousMatchError, ApiError, AuthenticationError, NotFoundError
+
+CARD_FIELDS = "id,name,idList,desc,due,dueComplete,closed,url,labels,idMembers,idChecklists"
+
+
+class TrelloClient:
+    def __init__(
+        self, credentials: Credentials, *, transport: httpx.BaseTransport | None = None
+    ) -> None:
+        self._client = httpx.Client(
+            base_url="https://api.trello.com/1",
+            params={"key": credentials.api_key, "token": credentials.token},
+            timeout=30,
+            transport=transport,
+        )
+
+    def __enter__(self) -> TrelloClient:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self._client.close()
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"Trello request failed: {exc}") from exc
+        if response.status_code in {401, 403}:
+            raise AuthenticationError("Trello rejected the credentials or required permission")
+        if response.status_code == 404:
+            raise NotFoundError("Trello resource was not found or is not visible to this token")
+        if response.is_error:
+            try:
+                detail = response.json().get("message", response.text)
+            except (ValueError, AttributeError):
+                detail = response.text
+            raise ApiError(
+                f"Trello API returned HTTP {response.status_code}: {detail}",
+                status_code=response.status_code,
+            )
+        if not response.content:
+            return {}
+        return response.json()
+
+    def member(self) -> dict[str, Any]:
+        return self.request("GET", "/members/me", params={"fields": "id,username,fullName"})
+
+    def boards(self, *, include_closed: bool = False) -> list[dict[str, Any]]:
+        return self.request(
+            "GET",
+            "/members/me/boards",
+            params={"filter": "all" if include_closed else "open", "fields": "id,name,closed,url"},
+        )
+
+    def resolve_board(self, value: str) -> dict[str, Any]:
+        return self._resolve(value, self.boards(include_closed=True), "board")
+
+    def lists(self, board: str, *, include_closed: bool = False) -> list[dict[str, Any]]:
+        board_id = self.resolve_board(board)["id"]
+        return self.request(
+            "GET",
+            f"/boards/{board_id}/lists",
+            params={"filter": "all" if include_closed else "open", "fields": "id,name,closed,pos"},
+        )
+
+    def resolve_list(self, board: str, value: str) -> dict[str, Any]:
+        return self._resolve(value, self.lists(board, include_closed=True), "list")
+
+    def cards(
+        self, board: str, *, list_value: str | None = None, limit: int = 50
+    ) -> list[dict[str, Any]]:
+        path = self._cards_path(board, list_value)
+        return self.request(
+            "GET",
+            path,
+            params={"filter": "open", "limit": limit, "fields": CARD_FIELDS},
+        )
+
+    def all_cards(self, board: str) -> list[dict[str, Any]]:
+        """Read every open card with deterministic Trello ID pagination."""
+        path = self._cards_path(board, None)
+        results: list[dict[str, Any]] = []
+        before: str | None = None
+        while True:
+            params = {"filter": "open", "limit": 1000, "fields": CARD_FIELDS}
+            if before:
+                params["before"] = before
+            page = self.request("GET", path, params=params)
+            results.extend(page)
+            if len(page) < 1000:
+                return results
+            next_before = str(page[-1]["id"])
+            if next_before == before:
+                raise ApiError("Trello card pagination did not advance")
+            before = next_before
+
+    def _cards_path(self, board: str, list_value: str | None) -> str:
+        if list_value:
+            list_id = self.resolve_list(board, list_value)["id"]
+            return f"/lists/{list_id}/cards"
+        board_id = self.resolve_board(board)["id"]
+        return f"/boards/{board_id}/cards"
+
+    def card(self, value: str, *, board: str | None = None) -> dict[str, Any]:
+        if board:
+            return self._resolve(value, self.all_cards(board), "card")
+        return self.request("GET", f"/cards/{value}", params={"fields": CARD_FIELDS})
+
+    def search(
+        self, query: str, *, board: str | None = None, limit: int = 50
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {
+            "query": query,
+            "modelTypes": "cards",
+            "card_fields": CARD_FIELDS,
+            "cards_limit": limit,
+        }
+        if board:
+            params["idBoards"] = self.resolve_board(board)["id"]
+        result = self.request("GET", "/search", params=params)
+        return result.get("cards", [])
+
+    def create_card(
+        self,
+        *,
+        board: str,
+        list_value: str,
+        title: str,
+        description: str = "",
+        due: str | None = None,
+        label_ids: Sequence[str] = (),
+    ) -> dict[str, Any]:
+        list_id = self.resolve_list(board, list_value)["id"]
+        return self.create_card_in_list(
+            list_id, title=title, description=description, due=due, label_ids=label_ids
+        )
+
+    def create_card_in_list(
+        self,
+        list_id: str,
+        *,
+        title: str,
+        description: str = "",
+        due: str | None = None,
+        label_ids: Sequence[str] = (),
+    ) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "idList": list_id,
+            "name": title,
+            "desc": description,
+            "pos": "bottom",
+        }
+        if due is not None:
+            data["due"] = due
+        if label_ids:
+            data["idLabels"] = ",".join(label_ids)
+        return self.request("POST", "/cards", data=data)
+
+    def ensure_card(
+        self,
+        *,
+        board: str,
+        list_value: str,
+        title: str,
+        description: str = "",
+        due: str | None = None,
+        label_ids: Sequence[str] = (),
+        target_list: Mapping[str, Any] | None = None,
+        card_index: Mapping[str, Sequence[dict[str, Any]]] | None = None,
+    ) -> tuple[dict[str, Any], str]:
+        target = target_list or self.resolve_list(board, list_value)
+        index = card_index if card_index is not None else self.index_cards(self.all_cards(board))
+        matches = list(index.get(title.casefold(), ()))
+        if len(matches) > 1:
+            raise AmbiguousMatchError(f"multiple cards named {title!r}; use an ID")
+        if not matches:
+            return self.create_card_in_list(
+                str(target["id"]),
+                title=title,
+                description=description,
+                due=due,
+                label_ids=label_ids,
+            ), "created"
+        current = matches[0]
+        changes: dict[str, Any] = {}
+        if current.get("idList") != target["id"]:
+            changes["idList"] = target["id"]
+        if description and current.get("desc") != description:
+            changes["desc"] = description
+        if due is not None and current.get("due") != due:
+            changes["due"] = due
+        if label_ids:
+            current_labels = {str(label.get("id")) for label in current.get("labels", [])}
+            if current_labels != set(label_ids):
+                changes["idLabels"] = ",".join(label_ids)
+        if changes:
+            current = self.request("PUT", f"/cards/{current['id']}", data=changes)
+            return current, "updated"
+        return current, "unchanged"
+
+    @staticmethod
+    def index_cards(cards: Sequence[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+        index: dict[str, list[dict[str, Any]]] = {}
+        for item in cards:
+            index.setdefault(str(item.get("name", "")).casefold(), []).append(item)
+        return index
+
+    def update_card(self, card_id: str, **changes: Any) -> dict[str, Any]:
+        data = {key: value for key, value in changes.items() if value is not None}
+        if not data:
+            return self.card(card_id)
+        return self.request("PUT", f"/cards/{card_id}", data=data)
+
+    def move_card(self, card_id: str, *, board: str, list_value: str) -> tuple[dict[str, Any], str]:
+        target = self.resolve_list(board, list_value)
+        current = self.card(card_id)
+        if current.get("idList") == target["id"]:
+            return current, "unchanged"
+        return self.update_card(card_id, idList=target["id"]), "moved"
+
+    def archive_card(self, card_id: str) -> tuple[dict[str, Any], str]:
+        current = self.card(card_id)
+        if current.get("closed"):
+            return current, "unchanged"
+        return self.update_card(card_id, closed="true"), "archived"
+
+    def comment(self, card_id: str, text: str) -> dict[str, Any]:
+        return self.request("POST", f"/cards/{card_id}/actions/comments", data={"text": text})
+
+    def add_label(self, card_id: str, label_id: str) -> dict[str, Any]:
+        return self.request("POST", f"/cards/{card_id}/idLabels", data={"value": label_id})
+
+    def add_checklist(self, card_id: str, name: str, items: Sequence[str]) -> dict[str, Any]:
+        checklist = self.request("POST", f"/cards/{card_id}/checklists", data={"name": name})
+        for item in items:
+            self.request("POST", f"/checklists/{checklist['id']}/checkItems", data={"name": item})
+        return checklist
+
+    @staticmethod
+    def _resolve(value: str, objects: Sequence[Mapping[str, Any]], kind: str) -> dict[str, Any]:
+        by_id = [item for item in objects if item.get("id") == value]
+        if by_id:
+            return dict(by_id[0])
+        exact = [
+            item for item in objects if str(item.get("name", "")).casefold() == value.casefold()
+        ]
+        if not exact:
+            raise NotFoundError(f"{kind} {value!r} was not found; use `{kind}s` to list valid IDs")
+        if len(exact) > 1:
+            ids = ", ".join(str(item.get("id")) for item in exact)
+            raise AmbiguousMatchError(f"{kind} {value!r} is ambiguous; matching IDs: {ids}")
+        return dict(exact[0])

trello_axi-0.2.1/src/trello_axi/config.py

@@ -0,0 +1,71 @@
+"""Credential loading without leaking secrets."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    api_key: str
+    token: str
+
+
+def default_config_path() -> Path:
+    return (
+        Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+        / "trello-axi"
+        / "config.json"
+    )
+
+
+def load_credentials(config_path: Path | None = None) -> Credentials:
+    """Load environment credentials first, then the local config file."""
+    api_key = os.environ.get("TRELLO_API_KEY", "").strip()
+    token = os.environ.get("TRELLO_TOKEN", "").strip()
+    path = config_path or default_config_path()
+    if (not api_key or not token) and path.exists():
+        try:
+            raw = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"cannot read credential file {path}: {exc}") from exc
+        if not isinstance(raw, Mapping):
+            raise ValueError(f"credential file {path} must contain a JSON object")
+        api_key = api_key or str(raw.get("api_key", "")).strip()
+        token = token or str(raw.get("token", "")).strip()
+    if not api_key or not token:
+        raise ValueError(
+            "Trello credentials are missing. Set TRELLO_API_KEY and TRELLO_TOKEN, "
+            "or run `trello-axi auth set --api-key <key> --token <token>`."
+        )
+    return Credentials(api_key=api_key, token=token)
+
+
+def save_credentials(api_key: str, token: str, config_path: Path | None = None) -> Path:
+    if not api_key.strip() or not token.strip():
+        raise ValueError("both --api-key and --token are required")
+    path = config_path or default_config_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.parent.chmod(0o700)
+    payload = json.dumps({"api_key": api_key.strip(), "token": token.strip()}) + "\n"
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w") as stream:
+            descriptor = -1
+            stream.write(payload)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(path)
+    except BaseException:
+        if descriptor >= 0:
+            os.close(descriptor)
+        temporary.unlink(missing_ok=True)
+        raise
+    return path

trello_axi-0.2.1/src/trello_axi/errors.py

@@ -0,0 +1,29 @@
+"""Domain errors mapped to stable CLI exit codes."""
+
+from __future__ import annotations
+
+
+class TrelloAxiError(Exception):
+    """Base actionable error."""
+
+    exit_code = 1
+
+
+class AuthenticationError(TrelloAxiError):
+    exit_code = 3
+
+
+class NotFoundError(TrelloAxiError):
+    exit_code = 4
+
+
+class AmbiguousMatchError(TrelloAxiError):
+    exit_code = 5
+
+
+class ApiError(TrelloAxiError):
+    exit_code = 6
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code

trello_axi-0.2.1/src/trello_axi/models.py

@@ -0,0 +1,52 @@
+"""Pure normalization functions for token-efficient API output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def board(raw: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": raw.get("id"),
+        "name": raw.get("name"),
+        "closed": raw.get("closed", False),
+        "url": raw.get("url"),
+    }
+
+
+def trello_list(raw: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": raw.get("id"),
+        "name": raw.get("name"),
+        "closed": raw.get("closed", False),
+        "pos": raw.get("pos"),
+    }
+
+
+def card(
+    raw: dict[str, Any], *, full: bool = False, description_limit: int | None = None
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "id": raw.get("id"),
+        "name": raw.get("name"),
+        "list_id": raw.get("idList"),
+        "due": raw.get("due"),
+    }
+    labels = raw.get("labels") or []
+    result["labels"] = ";".join(item.get("name") or item.get("color", "") for item in labels)
+    if full:
+        description = str(raw.get("desc", ""))
+        truncated = description_limit is not None and len(description) > description_limit
+        if truncated:
+            description = description[:description_limit] + "…"
+        result.update(
+            description=description,
+            description_chars=len(str(raw.get("desc", ""))),
+            description_truncated=truncated,
+            closed=raw.get("closed", False),
+            url=raw.get("url"),
+            due_complete=raw.get("dueComplete", False),
+            member_ids=raw.get("idMembers", []),
+            checklist_ids=raw.get("idChecklists", []),
+        )
+    return result

trello_axi-0.2.1/src/trello_axi/output.py

@@ -0,0 +1,76 @@
+"""Compact deterministic output for agents."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def _scalar(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    text = str(value).replace("\n", "\\n")
+    if any(char in text for char in ',"'):
+        return '"' + text.replace('"', '""') + '"'
+    return text
+
+
+def toon(data: Any, *, name: str = "result") -> str:
+    """Render a small TOON-style subset: scalar maps and tabular arrays."""
+    if isinstance(data, list):
+        if not data:
+            return f"{name}[0]:"
+        rows = [item for item in data if isinstance(item, Mapping)]
+        if len(rows) == len(data):
+            fields = list(
+                dict.fromkeys(
+                    key for row in rows for key in row if not isinstance(row[key], (dict, list))
+                )
+            )
+            lines = [f"{name}[{len(rows)}]{{{','.join(fields)}}}:"]
+            lines.extend(
+                "  " + ",".join(_scalar(row.get(field)) for field in fields) for row in rows
+            )
+            return "\n".join(lines)
+    if isinstance(data, Mapping):
+        lines = [f"{name}:"]
+        for key, value in data.items():
+            if isinstance(value, list):
+                lines.append(toon(value, name=str(key)))
+            elif isinstance(value, Mapping):
+                lines.append(
+                    f"  {key}: {json.dumps(value, ensure_ascii=False, separators=(',', ':'))}"
+                )
+            else:
+                lines.append(f"  {key}: {_scalar(value)}")
+        return "\n".join(lines)
+    return f"{name}: {_scalar(data)}"
+
+
+def emit(
+    data: Any,
+    *,
+    fmt: str = "toon",
+    name: str = "result",
+    help_commands: Sequence[str] = (),
+) -> None:
+    if fmt == "json":
+        print(json.dumps({name: data, "help": list(help_commands)}, ensure_ascii=False, indent=2))
+    else:
+        print(toon(data, name=name))
+        if help_commands:
+            print(toon([{"command": command} for command in help_commands], name="help"))
+
+
+def emit_error(
+    message: str, *, code: str, fmt: str = "toon", help_commands: Sequence[str] = ()
+) -> None:
+    payload = {"error": code, "message": message, "help": list(help_commands)}
+    if fmt == "json":
+        print(json.dumps(payload, ensure_ascii=False), file=sys.stderr)
+    else:
+        print(toon(payload, name="failure"), file=sys.stderr)

trello_axi-0.2.1/src/trello_axi/resources/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: trello-axi
+description: Use Trello through an agent-native CLI for compact board context, card CRUD, search, comments, labels, checklists, and idempotent batch workflows.
+---
+
+# trello-axi
+
+Use IDs after initial discovery. Keep reads bounded and request JSON only when another program must parse output.
+
+## Discover
+
+```bash
+trello-axi auth status
+trello-axi boards
+trello-axi board "<board>"
+trello-axi cards --board "<board>" --list "<list>" --limit 50
+```
+
+## Mutate safely
+
+Prefer idempotent `ensure` when retrying is possible:
+
+```bash
+trello-axi card ensure --board "<board>" --list "<list>" --title "<title>" --description-file <path>
+```
+
+Use card IDs for subsequent operations:
+
+```bash
+trello-axi card move <card-id> --board "<board>" --list "<list>"
+trello-axi card comment <card-id> --text "<comment>"
+trello-axi card archive <card-id>
+```
+
+Execute explicit archive and batch requests noninteractively; do not introduce confirmation prompts inside the command workflow. Never print, log, or request API credentials in chat. Do not use permanent deletion; this CLI intentionally archives cards instead.

trello_axi-0.2.1/src/trello_axi/resources/skill.py

@@ -0,0 +1,39 @@
+"""Bundled trello-axi agent skill."""
+# ruff: noqa: E501
+
+SKILL_TEXT = """---
+name: trello-axi
+description: Use Trello through an agent-native CLI for compact board context, card CRUD, search, comments, labels, checklists, and idempotent batch workflows.
+---
+
+# trello-axi
+
+Use IDs after initial discovery. Keep reads bounded and request JSON only when another program must parse output.
+
+## Discover
+
+```bash
+trello-axi auth status
+trello-axi boards
+trello-axi board "<board>"
+trello-axi cards --board "<board>" --list "<list>" --limit 50
+```
+
+## Mutate safely
+
+Prefer idempotent `ensure` when retrying is possible:
+
+```bash
+trello-axi card ensure --board "<board>" --list "<list>" --title "<title>" --description-file <path>
+```
+
+Use card IDs for subsequent operations:
+
+```bash
+trello-axi card move <card-id> --board "<board>" --list "<list>"
+trello-axi card comment <card-id> --text "<comment>"
+trello-axi card archive <card-id>
+```
+
+Execute explicit archive and batch requests noninteractively; do not introduce confirmation prompts inside the command workflow. Never print, log, or request API credentials in chat. Do not use permanent deletion; this CLI intentionally archives cards instead.
+"""

trello_axi-0.2.1/src/trello_axi/setup.py

@@ -0,0 +1,76 @@
+"""Idempotent agent skill and SessionStart hook installers."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .resources.skill import SKILL_TEXT
+
+MARKER = "trello-axi"
+
+
+def install_skill(destination: Path | None = None) -> Path:
+    target = destination or Path.home() / ".agents" / "skills" / MARKER / "SKILL.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if not target.exists() or target.read_text() != SKILL_TEXT:
+        target.write_text(SKILL_TEXT)
+    return target
+
+
+def install_hooks(*, command: str | None = None) -> list[Path]:
+    """Install managed Claude Code and Codex SessionStart hooks."""
+    executable = command or shutil.which("trello-axi")
+    if not executable:
+        raise ValueError("trello-axi executable was not found on PATH")
+    hook = {"type": "command", "command": executable, "timeout": 10}
+    installed = []
+    for path in (Path.home() / ".claude" / "settings.json", Path.home() / ".codex" / "hooks.json"):
+        settings = _load_object(path)
+        hooks = settings.setdefault("hooks", {})
+        if not isinstance(hooks, dict):
+            raise ValueError(f"{path} contains a non-object hooks setting")
+        groups = hooks.setdefault("SessionStart", [])
+        if not isinstance(groups, list):
+            raise ValueError(f"{path} contains a non-list SessionStart setting")
+        managed = None
+        for group in groups:
+            if not isinstance(group, dict) or not isinstance(group.get("hooks"), list):
+                continue
+            if any(
+                MARKER in str(item.get("command", ""))
+                for item in group["hooks"]
+                if isinstance(item, dict)
+            ):
+                managed = group
+                break
+        desired = {"matcher": "", "hooks": [hook]}
+        if managed is None:
+            groups.append(desired)
+        else:
+            managed.clear()
+            managed.update(desired)
+        _atomic_json(path, settings)
+        installed.append(path)
+    return installed
+
+
+def _load_object(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        raw = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"cannot read agent settings {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ValueError(f"agent settings {path} must contain a JSON object")
+    return raw
+
+
+def _atomic_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.trello-axi.tmp")
+    temporary.write_text(json.dumps(value, indent=2) + "\n")
+    temporary.replace(path)