diff options
| -rw-r--r-- | docs/superpowers/plans/2026-06-30-firefly-cli.md | 1387 |
1 files changed, 1387 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-06-30-firefly-cli.md b/docs/superpowers/plans/2026-06-30-firefly-cli.md new file mode 100644 index 0000000..2d5596c --- /dev/null +++ b/docs/superpowers/plans/2026-06-30-firefly-cli.md @@ -0,0 +1,1387 @@ +# firefly-cli Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A Python-package CLI (`firefly`) that lets an LLM agent and the user record and query a Firefly III instance over its REST API. + +**Architecture:** A `firefly_cli` package with shared primitives (config, HTTP client, name resolver, output) and a self-registering command registry. Each command group is one module in `firefly_cli/commands/`; dropping a module in adds commands with no other edits. JSON output by default, `--human` for tables. + +**Tech Stack:** Python 3.11+ standard library only (`urllib.request`, `json`, `tomllib`, `argparse`, `unittest`). No third-party runtime deps. License GPLv2-only. + +--- + +## Reference facts (verified against the cloned firefly-iii codebase, read-only) + +- API base path: `/api/v1`. About endpoint: `GET /api/v1/about` returns `{"data":{"version":...,"api_version":...}}`. +- Auth: `Authorization: Bearer <PAT>`. Accept header `application/vnd.api+json`. +- Account types (enum string values): `Asset account`, `Expense account`, + `Revenue account`, `Liability credit account`, `Loan`, `Mortgage`, `Debt`, + `Cash account`, etc. The API `accounts` list accepts a `type` query filter + with short names: `asset`, `expense`, `revenue`, `liability`, etc. +- Account resource fields include: `id`, `name`, `type`, `current_balance`, + `currency_code`. (AccountTransformer, verified.) +- Transaction store body shape: + `{"transactions":[{ "type", "date", "amount", "description", + "source_id", "destination_id", "category_name", "tags": [...] }]}`. + Source/destination accept `_id` or `_name`; we send `_id` (resolved). Fields + verified in StoreRequest rules. +- Transaction reads use TransactionGroupTransformer (a group wraps one or more + splits). List/collection responses are Fractal-serialized: + `{"data":[...], "meta":{"pagination":{...}}, "links":{...}}`. + +**Executor note:** the exact list envelope and the precise `current_balance` +field name are confirmed live by the integration tests in Task 11. Until then, +unit tests use the documented shapes above. If a live shape differs, update the +unwrap logic and its unit test together. + +--- + +## File Structure + +- `firefly_cli/__init__.py` — version, package marker. +- `firefly_cli/config.py` — load (env over TOML file), template-write. +- `firefly_cli/client.py` — `Client` with `request()`, auth headers, error surfacing. +- `firefly_cli/errors.py` — exception types shared across modules. +- `firefly_cli/output.py` — `emit()` JSON/human, `unwrap()` envelope helper. +- `firefly_cli/resolver.py` — `Resolver` name→id with ambiguity errors. +- `firefly_cli/registry.py` — command registry (decorator + list). +- `firefly_cli/cli.py` — builds argparse from registry, `main()`, builds `Context`. +- `firefly_cli/context.py` — `Context` dataclass bundling config/client/resolver + flags. +- `firefly_cli/commands/__init__.py` — imports each command module so they register. +- `firefly_cli/commands/auth.py`, `account.py`, `transaction.py`, `category.py`, `tag.py`. +- `firefly_cli/__main__.py` — `python -m firefly_cli`. +- `tests/unit/test_*.py` — mocked, always run. +- `tests/integration/test_live.py` — gated by `FIREFLY_TEST_URL`/`FIREFLY_TEST_TOKEN`. +- `pyproject.toml`, `LICENSE`, `README.md`, `CLAUDE.md`. + +--- + +## Task 1: Project scaffold, license, CLAUDE.md + +**Files:** +- Create: `pyproject.toml`, `LICENSE`, `README.md`, `CLAUDE.md`, + `firefly_cli/__init__.py`, `firefly_cli/__main__.py`, `.gitignore` + +- [ ] **Step 1: Fetch GPLv2 license text** + +Run: +```bash +curl -fsSL https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt -o LICENSE +head -2 LICENSE +``` +Expected: prints the GPLv2 preamble lines. If offline, executor must obtain the +official text before committing. + +- [ ] **Step 2: Write `pyproject.toml`** + +```toml +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "firefly-cli" +version = "0.1.0" +description = "CLI tool for agent interaction with Firefly III" +requires-python = ">=3.11" +license = { text = "GPL-2.0-only" } +authors = [{ name = "Danilo M.", email = "danix@danix.xyz" }] +dependencies = [] + +[project.scripts] +firefly = "firefly_cli.cli:main" + +[tool.setuptools.packages.find] +include = ["firefly_cli*"] +``` + +- [ ] **Step 3: Write `firefly_cli/__init__.py`** + +```python +# firefly-cli — CLI for Firefly III +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> +# Licensed under the GNU General Public License v2.0 only. + +__version__ = "0.1.0" +``` + +- [ ] **Step 4: Write `firefly_cli/__main__.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli.cli import main + +if __name__ == "__main__": + raise SystemExit(main()) +``` + +- [ ] **Step 5: Write `.gitignore`** + +``` +__pycache__/ +*.pyc +*.egg-info/ +build/ +dist/ +.venv/ +``` + +- [ ] **Step 6: Write `README.md`** (sections: what it is, install + `pip install -e .`, config via `firefly auth set` or env vars, command list + placeholder pointing at `firefly --help`, License = GPLv2-only). + +- [ ] **Step 7: Write `CLAUDE.md`** — see Appendix A at the end of this plan for + full content. Copy it verbatim. + +- [ ] **Step 8: Commit** + +```bash +git add pyproject.toml LICENSE README.md CLAUDE.md firefly_cli/__init__.py firefly_cli/__main__.py .gitignore +git commit -S -m "chore: project scaffold, GPLv2 license, CLAUDE.md" +``` + +--- + +## Task 2: Errors module + +**Files:** +- Create: `firefly_cli/errors.py` +- Test: `tests/unit/test_errors.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from firefly_cli.errors import FireflyError, ConfigError, ApiError, ResolutionError + +class TestErrors(unittest.TestCase): + def test_subclassing(self): + for cls in (ConfigError, ApiError, ResolutionError): + self.assertTrue(issubclass(cls, FireflyError)) + + def test_api_error_carries_status_and_body(self): + e = ApiError(422, {"message": "bad"}) + self.assertEqual(e.status, 422) + self.assertEqual(e.body, {"message": "bad"}) + self.assertIn("422", str(e)) + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_errors -v` +Expected: FAIL, `ModuleNotFoundError: firefly_cli.errors`. + +- [ ] **Step 3: Write `firefly_cli/errors.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only + +class FireflyError(Exception): + """Base for all firefly-cli errors.""" + +class ConfigError(FireflyError): + """Missing or invalid configuration.""" + +class ResolutionError(FireflyError): + """A name could not be resolved to a single id.""" + +class ApiError(FireflyError): + """Firefly returned a non-2xx response.""" + def __init__(self, status, body): + self.status = status + self.body = body + msg = body.get("message") if isinstance(body, dict) else body + super().__init__(f"API error {status}: {msg}") +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_errors -v` +Expected: PASS (add empty `tests/__init__.py`, `tests/unit/__init__.py` if needed). + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/errors.py tests/ +git commit -S -m "feat: error types" +``` + +--- + +## Task 3: Config (env over TOML file, template write) + +**Files:** +- Create: `firefly_cli/config.py` +- Test: `tests/unit/test_config.py` + +- [ ] **Step 1: Write the failing test** + +```python +import os, tempfile, unittest +from pathlib import Path +from firefly_cli import config +from firefly_cli.errors import ConfigError + +class TestConfig(unittest.TestCase): + def setUp(self): + self.dir = tempfile.TemporaryDirectory() + self.path = Path(self.dir.name) / "config.toml" + def tearDown(self): + self.dir.cleanup() + for k in ("FIREFLY_URL", "FIREFLY_TOKEN"): + os.environ.pop(k, None) + + def test_write_then_read_roundtrip(self): + config.write("https://f.example/", "tok123", path=self.path) + cfg = config.load(path=self.path, env={}) + self.assertEqual(cfg["url"], "https://f.example") # trailing slash trimmed + self.assertEqual(cfg["token"], "tok123") + + def test_env_overrides_file(self): + config.write("https://file/", "filetok", path=self.path) + cfg = config.load(path=self.path, + env={"FIREFLY_URL": "https://env", "FIREFLY_TOKEN": "envtok"}) + self.assertEqual(cfg["url"], "https://env") + self.assertEqual(cfg["token"], "envtok") + + def test_missing_everything_raises_configerror(self): + with self.assertRaises(ConfigError): + config.load(path=self.path, env={}) + + def test_env_only_no_file(self): + cfg = config.load(path=self.path, + env={"FIREFLY_URL": "https://env/", "FIREFLY_TOKEN": "t"}) + self.assertEqual(cfg["url"], "https://env") +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_config -v` +Expected: FAIL, no module/attr. + +- [ ] **Step 3: Write `firefly_cli/config.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import os +import tomllib +from pathlib import Path +from firefly_cli.errors import ConfigError + +DEFAULT_PATH = Path(os.path.expanduser("~/.config/firefly-cli/config.toml")) + +def load(path=DEFAULT_PATH, env=None): + env = os.environ if env is None else env + url = env.get("FIREFLY_URL") + token = env.get("FIREFLY_TOKEN") + if not (url and token) and Path(path).exists(): + with open(path, "rb") as fh: + data = tomllib.load(fh) + url = url or data.get("url") + token = token or data.get("token") + if not url or not token: + raise ConfigError( + "No Firefly III config found. Run `firefly auth set` " + "or set FIREFLY_URL and FIREFLY_TOKEN." + ) + return {"url": url.rstrip("/"), "token": token} + +def write(url, token, path=DEFAULT_PATH): + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + # tomllib cannot write; template the 2-key file (deps stay at zero). + content = ( + f'url = "{url.rstrip("/")}"\n' + f'token = "{token}"\n' + ) + path.write_text(content) + path.chmod(0o600) + return path +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_config -v` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/config.py tests/unit/test_config.py +git commit -S -m "feat: config load/write with env override" +``` + +--- + +## Task 4: HTTP client + +**Files:** +- Create: `firefly_cli/client.py` +- Test: `tests/unit/test_client.py` + +- [ ] **Step 1: Write the failing test** + +```python +import json, unittest +from unittest.mock import patch, MagicMock +from io import BytesIO +import urllib.error +from firefly_cli.client import Client +from firefly_cli.errors import ApiError + +def fake_response(payload, status=200): + r = MagicMock() + r.read.return_value = json.dumps(payload).encode() + r.status = status + r.__enter__.return_value = r + r.__exit__.return_value = False + return r + +class TestClient(unittest.TestCase): + def setUp(self): + self.c = Client("https://f.example", "tok") + + @patch("firefly_cli.client.urllib.request.urlopen") + def test_get_builds_url_and_headers(self, urlopen): + urlopen.return_value = fake_response({"data": []}) + out = self.c.request("GET", "/api/v1/accounts", params={"type": "asset"}) + req = urlopen.call_args[0][0] + self.assertEqual(req.full_url, "https://f.example/api/v1/accounts?type=asset") + self.assertEqual(req.get_header("Authorization"), "Bearer tok") + self.assertEqual(req.get_header("Accept"), "application/vnd.api+json") + self.assertEqual(out, {"data": []}) + + @patch("firefly_cli.client.urllib.request.urlopen") + def test_post_sends_json_body(self, urlopen): + urlopen.return_value = fake_response({"data": {"id": "9"}}) + self.c.request("POST", "/api/v1/transactions", body={"x": 1}) + req = urlopen.call_args[0][0] + self.assertEqual(req.get_method(), "POST") + self.assertEqual(json.loads(req.data), {"x": 1}) + self.assertEqual(req.get_header("Content-type"), "application/json") + + @patch("firefly_cli.client.urllib.request.urlopen") + def test_http_error_becomes_apierror(self, urlopen): + body = json.dumps({"message": "boom"}).encode() + urlopen.side_effect = urllib.error.HTTPError( + "u", 422, "Unprocessable", {}, BytesIO(body)) + with self.assertRaises(ApiError) as ctx: + self.c.request("GET", "/api/v1/accounts") + self.assertEqual(ctx.exception.status, 422) + self.assertEqual(ctx.exception.body["message"], "boom") +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_client -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/client.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import json +import urllib.request +import urllib.parse +import urllib.error +from firefly_cli.errors import ApiError + +class Client: + def __init__(self, url, token, timeout=30): + self.url = url.rstrip("/") + self.token = token + self.timeout = timeout + + def request(self, method, path, params=None, body=None): + full = self.url + path + if params: + full += "?" + urllib.parse.urlencode(params) + data = json.dumps(body).encode() if body is not None else None + req = urllib.request.Request(full, data=data, method=method) + req.add_header("Authorization", f"Bearer {self.token}") + req.add_header("Accept", "application/vnd.api+json") + if data is not None: + req.add_header("Content-Type", "application/json") + try: + with urllib.request.urlopen(req, timeout=self.timeout) as resp: + raw = resp.read().decode() + return json.loads(raw) if raw else {} + except urllib.error.HTTPError as e: + raw = e.read().decode() + try: + parsed = json.loads(raw) + except ValueError: + parsed = {"message": raw or e.reason} + raise ApiError(e.code, parsed) from None +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_client -v` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/client.py tests/unit/test_client.py +git commit -S -m "feat: HTTP client with auth and error surfacing" +``` + +--- + +## Task 5: Output (emit + unwrap) + +**Files:** +- Create: `firefly_cli/output.py` +- Test: `tests/unit/test_output.py` + +- [ ] **Step 1: Write the failing test** + +```python +import io, json, unittest +from contextlib import redirect_stdout +from firefly_cli.output import unwrap, emit + +class TestOutput(unittest.TestCase): + def test_unwrap_list_returns_clean_objects(self): + resp = {"data": [ + {"id": "1", "type": "accounts", "attributes": {"name": "Checking"}}, + {"id": "2", "type": "accounts", "attributes": {"name": "Savings"}}, + ]} + self.assertEqual(unwrap(resp), + [{"id": "1", "name": "Checking"}, {"id": "2", "name": "Savings"}]) + + def test_unwrap_single_object(self): + resp = {"data": {"id": "5", "type": "accounts", + "attributes": {"name": "Wallet"}}} + self.assertEqual(unwrap(resp), {"id": "5", "name": "Wallet"}) + + def test_emit_json_default(self): + buf = io.StringIO() + with redirect_stdout(buf): + emit([{"id": "1", "name": "x"}], human=False) + self.assertEqual(json.loads(buf.getvalue()), [{"id": "1", "name": "x"}]) + + def test_emit_human_table_contains_values(self): + buf = io.StringIO() + with redirect_stdout(buf): + emit([{"id": "1", "name": "Checking"}], human=True) + out = buf.getvalue() + self.assertIn("Checking", out) + self.assertIn("id", out) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_output -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/output.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import json +import sys + +def unwrap(resp): + """Flatten Firefly's JSON:API envelope to plain id+attributes objects.""" + def flat(item): + out = {"id": item.get("id")} + out.update(item.get("attributes", {})) + return out + data = resp.get("data", resp) + if isinstance(data, list): + return [flat(i) for i in data] + if isinstance(data, dict) and "attributes" in data: + return flat(data) + return data + +def emit(data, human=False, stream=None): + stream = stream or sys.stdout + if not human: + json.dump(data, stream, indent=2, default=str) + stream.write("\n") + return + rows = data if isinstance(data, list) else [data] + if not rows: + stream.write("(no results)\n") + return + cols = list(rows[0].keys()) + widths = {c: max(len(c), *(len(str(r.get(c, ""))) for r in rows)) for c in cols} + stream.write(" ".join(c.ljust(widths[c]) for c in cols) + "\n") + for r in rows: + stream.write(" ".join(str(r.get(c, "")).ljust(widths[c]) for c in cols) + "\n") + +def emit_error(message, stream=None): + stream = stream or sys.stderr + json.dump({"error": message}, stream) + stream.write("\n") +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_output -v` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/output.py tests/unit/test_output.py +git commit -S -m "feat: output emit and envelope unwrap" +``` + +--- + +## Task 6: Registry + Context + +**Files:** +- Create: `firefly_cli/registry.py`, `firefly_cli/context.py` +- Test: `tests/unit/test_registry.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from firefly_cli import registry + +class TestRegistry(unittest.TestCase): + def setUp(self): + registry._COMMANDS.clear() + + def test_command_decorator_registers(self): + @registry.command("tx add", help="add a tx") + def handler(args, ctx): + return 0 + cmds = registry.all_commands() + self.assertEqual(len(cmds), 1) + self.assertEqual(cmds[0].name, "tx add") + self.assertIs(cmds[0].handler, handler) + + def test_add_arguments_callback_stored(self): + def args_cb(p): + p.add_argument("name") + @registry.command("account get", args=args_cb) + def handler(args, ctx): + return 0 + self.assertIs(registry.all_commands()[0].args, args_cb) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_registry -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/registry.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from dataclasses import dataclass +from typing import Callable, Optional + +@dataclass +class Command: + name: str # e.g. "tx add" + handler: Callable # fn(args, ctx) -> int + help: str = "" + args: Optional[Callable] = None # fn(argparse_subparser) -> None + +_COMMANDS = [] + +def command(name, help="", args=None): + def deco(fn): + _COMMANDS.append(Command(name=name, handler=fn, help=help, args=args)) + return fn + return deco + +def all_commands(): + return list(_COMMANDS) +``` + +- [ ] **Step 4: Write `firefly_cli/context.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from dataclasses import dataclass + +@dataclass +class Context: + client: object # firefly_cli.client.Client + resolver: object # firefly_cli.resolver.Resolver + human: bool = False +``` + +- [ ] **Step 5: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_registry -v` +Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add firefly_cli/registry.py firefly_cli/context.py tests/unit/test_registry.py +git commit -S -m "feat: command registry and context" +``` + +--- + +## Task 7: Resolver (name -> id) + +**Files:** +- Create: `firefly_cli/resolver.py` +- Test: `tests/unit/test_resolver.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from unittest.mock import MagicMock +from firefly_cli.resolver import Resolver +from firefly_cli.errors import ResolutionError + +def client_returning(items): + c = MagicMock() + c.request.return_value = { + "data": [ + {"id": i["id"], "type": "accounts", "attributes": i["attrs"]} + for i in items + ] + } + return c + +class TestResolver(unittest.TestCase): + def test_resolves_unique_account_name(self): + c = client_returning([ + {"id": "3", "attrs": {"name": "Checking", "type": "asset"}}, + {"id": "4", "attrs": {"name": "Savings", "type": "asset"}}, + ]) + r = Resolver(c) + acc = r.account("checking") # case-insensitive + self.assertEqual(acc["id"], "3") + self.assertEqual(acc["type"], "asset") + + def test_no_match_raises_with_candidates(self): + c = client_returning([{"id": "3", "attrs": {"name": "Checking", "type": "asset"}}]) + r = Resolver(c) + with self.assertRaises(ResolutionError) as ctx: + r.account("Nope") + self.assertIn("Checking", str(ctx.exception)) + + def test_ambiguous_match_raises(self): + c = client_returning([ + {"id": "3", "attrs": {"name": "Cash", "type": "asset"}}, + {"id": "9", "attrs": {"name": "Cash", "type": "asset"}}, + ]) + r = Resolver(c) + with self.assertRaises(ResolutionError) as ctx: + r.account("Cash") + self.assertIn("3", str(ctx.exception)) + self.assertIn("9", str(ctx.exception)) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_resolver -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/resolver.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli.errors import ResolutionError + +class Resolver: + def __init__(self, client): + self.client = client + + def _list(self, path): + resp = self.client.request("GET", path, params={"limit": 1000}) + out = [] + for item in resp.get("data", []): + attrs = item.get("attributes", {}) + out.append({"id": item.get("id"), **attrs}) + return out + + def _match(self, kind, items, name): + hits = [i for i in items if str(i.get("name", "")).lower() == name.lower()] + if len(hits) == 1: + return hits[0] + names = ", ".join(f'{i.get("name")}(id={i.get("id")})' for i in items) + if not hits: + raise ResolutionError( + f'No {kind} named "{name}". Available: {names or "(none)"}') + raise ResolutionError( + f'Ambiguous {kind} "{name}" matches ids ' + + ", ".join(i["id"] for i in hits)) + + def account(self, name): + return self._match("account", self._list("/api/v1/accounts"), name) + + def tag(self, name): + return self._match("tag", self._list("/api/v1/tags"), name) + + def category(self, name): + return self._match("category", self._list("/api/v1/categories"), name) +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_resolver -v` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/resolver.py tests/unit/test_resolver.py +git commit -S -m "feat: name-to-id resolver with loud ambiguity errors" +``` + +--- + +## Task 8: account + category + tag + auth commands + +**Files:** +- Create: `firefly_cli/commands/__init__.py`, `firefly_cli/commands/account.py`, + `firefly_cli/commands/category.py`, `firefly_cli/commands/tag.py`, + `firefly_cli/commands/auth.py` +- Test: `tests/unit/test_commands_account.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from unittest.mock import MagicMock +from firefly_cli.commands import account as acct +from firefly_cli.context import Context + +def make_ctx(): + client = MagicMock() + resolver = MagicMock() + return Context(client=client, resolver=resolver, human=False), client, resolver + +class TestAccountCmd(unittest.TestCase): + def test_list_passes_type_filter(self): + ctx, client, _ = make_ctx() + client.request.return_value = {"data": []} + args = MagicMock(type="asset") + acct.cmd_list(args, ctx) + client.request.assert_called_once_with( + "GET", "/api/v1/accounts", params={"type": "asset"}) + + def test_balance_resolves_name_and_returns_balance(self): + ctx, client, resolver = make_ctx() + resolver.account.return_value = {"id": "3", "name": "Checking", + "current_balance": "100.00"} + args = MagicMock(account="Checking") + rc = acct.cmd_balance(args, ctx) + resolver.account.assert_called_once_with("Checking") + self.assertEqual(rc, 0) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_commands_account -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/commands/account.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli import registry, output + +def _list_args(p): + p.add_argument("--type", help="filter: asset, expense, revenue, liability, ...") + +@registry.command("account list", help="list accounts", args=_list_args) +def cmd_list(args, ctx): + params = {"type": args.type} if getattr(args, "type", None) else None + resp = ctx.client.request("GET", "/api/v1/accounts", params=params) + output.emit(output.unwrap(resp), human=ctx.human) + return 0 + +def _name_arg(p): + p.add_argument("account", help="account name or id") + +@registry.command("account get", help="show one account", args=_name_arg) +def cmd_get(args, ctx): + acc = ctx.resolver.account(args.account) + output.emit(acc, human=ctx.human) + return 0 + +@registry.command("account balance", help="show account balance", args=_name_arg) +def cmd_balance(args, ctx): + acc = ctx.resolver.account(args.account) + output.emit({"id": acc["id"], "name": acc.get("name"), + "current_balance": acc.get("current_balance")}, human=ctx.human) + return 0 +``` + +- [ ] **Step 4: Write `firefly_cli/commands/category.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli import registry, output + +@registry.command("category list", help="list categories") +def cmd_list(args, ctx): + resp = ctx.client.request("GET", "/api/v1/categories") + output.emit(output.unwrap(resp), human=ctx.human) + return 0 +``` + +- [ ] **Step 5: Write `firefly_cli/commands/tag.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli import registry, output + +@registry.command("tag list", help="list tags") +def cmd_list(args, ctx): + resp = ctx.client.request("GET", "/api/v1/tags") + output.emit(output.unwrap(resp), human=ctx.human) + return 0 +``` + +- [ ] **Step 6: Write `firefly_cli/commands/auth.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import getpass +from firefly_cli import registry, output, config + +def _set_args(p): + p.add_argument("--url", help="Firefly III base URL") + p.add_argument("--token", help="Personal Access Token") + +@registry.command("auth set", help="write url+token to config", args=_set_args) +def cmd_set(args, ctx): + url = args.url or input("Firefly III URL: ").strip() + token = args.token or getpass.getpass("Personal Access Token: ").strip() + path = config.write(url, token) + output.emit({"written": str(path)}, human=ctx.human) + return 0 + +@registry.command("auth test", help="verify connectivity and token") +def cmd_test(args, ctx): + resp = ctx.client.request("GET", "/api/v1/about") + output.emit(resp.get("data", resp), human=ctx.human) + return 0 +``` + +- [ ] **Step 7: Write `firefly_cli/commands/__init__.py`** (import to self-register) + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +# Importing each module runs its @registry.command decorators. +from firefly_cli.commands import auth, account, category, tag, transaction # noqa: F401 +``` + +Note: `transaction` is created in Task 9. Until then, temporarily drop +`transaction` from this import OR create Task 9 first. Executor: do Task 9 +before running the full CLI in Task 10; this unit test imports only `account`. + +- [ ] **Step 8: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_commands_account -v` +Expected: PASS. + +- [ ] **Step 9: Commit** + +```bash +git add firefly_cli/commands/ tests/unit/test_commands_account.py +git commit -S -m "feat: account, category, tag, auth commands" +``` + +--- + +## Task 9: transaction commands (add/list/get/search) + +**Files:** +- Create: `firefly_cli/commands/transaction.py` +- Test: `tests/unit/test_commands_transaction.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from unittest.mock import MagicMock +from firefly_cli.commands import transaction as tx +from firefly_cli.context import Context + +def make_ctx(): + client = MagicMock() + resolver = MagicMock() + return Context(client=client, resolver=resolver, human=False), client, resolver + +class TestTxAdd(unittest.TestCase): + def test_infers_withdrawal_from_asset_to_expense(self): + ctx, client, resolver = make_ctx() + resolver.account.side_effect = lambda n: { + "Checking": {"id": "1", "name": "Checking", "type": "asset"}, + "Groceries": {"id": "2", "name": "Groceries", "type": "expense"}, + }[n] + client.request.return_value = {"data": {"id": "55", "type": "transactions", + "attributes": {}}} + args = MagicMock(amount="42.50", source="Checking", dest="Groceries", + desc="food", date="2026-06-30", category=None, + tags=None, type=None) + rc = tx.cmd_add(args, ctx) + self.assertEqual(rc, 0) + method, path = client.request.call_args[0][:2] + body = client.request.call_args[1]["body"] + split = body["transactions"][0] + self.assertEqual((method, path), ("POST", "/api/v1/transactions")) + self.assertEqual(split["type"], "withdrawal") + self.assertEqual(split["source_id"], "1") + self.assertEqual(split["destination_id"], "2") + self.assertEqual(split["amount"], "42.50") + + def test_infers_deposit_revenue_to_asset(self): + ctx, client, resolver = make_ctx() + resolver.account.side_effect = lambda n: { + "Salary": {"id": "7", "name": "Salary", "type": "revenue"}, + "Checking": {"id": "1", "name": "Checking", "type": "asset"}, + }[n] + client.request.return_value = {"data": {"id": "1", "attributes": {}}} + args = MagicMock(amount="1000", source="Salary", dest="Checking", + desc="pay", date=None, category=None, tags=None, type=None) + tx.cmd_add(args, ctx) + self.assertEqual(client.request.call_args[1]["body"]["transactions"][0]["type"], + "deposit") + + def test_explicit_type_overrides_inference(self): + ctx, client, resolver = make_ctx() + resolver.account.side_effect = lambda n: {"id": "1", "type": "asset", "name": n} + client.request.return_value = {"data": {"id": "1", "attributes": {}}} + args = MagicMock(amount="5", source="A", dest="B", desc=None, date=None, + category=None, tags="food,fun", type="transfer") + tx.cmd_add(args, ctx) + split = client.request.call_args[1]["body"]["transactions"][0] + self.assertEqual(split["type"], "transfer") + self.assertEqual(split["tags"], ["food", "fun"]) + +class TestTxList(unittest.TestCase): + def test_list_passes_date_params(self): + ctx, client, _ = make_ctx() + client.request.return_value = {"data": []} + args = MagicMock(since="2026-06-01", until="2026-06-30", + account=None, limit=10) + tx.cmd_list(args, ctx) + params = client.request.call_args[1]["params"] + self.assertEqual(params["start"], "2026-06-01") + self.assertEqual(params["end"], "2026-06-30") + self.assertEqual(params["limit"], 10) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_commands_transaction -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/commands/transaction.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +from firefly_cli import registry, output + +# Inference table keyed by (source_type, destination_type) -> firefly tx type. +def _infer_type(src_type, dst_type): + s, d = (src_type or "").lower(), (dst_type or "").lower() + if s == "asset" and d == "asset": + return "transfer" + if s in ("revenue",) and d == "asset": + return "deposit" + if s == "asset" and d in ("expense",): + return "withdrawal" + # Fallback: asset source -> withdrawal, asset dest -> deposit. + if s == "asset": + return "withdrawal" + if d == "asset": + return "deposit" + raise ValueError( + f"Cannot infer transaction type from {src_type!r}->{dst_type!r}; " + "pass --type withdrawal|deposit|transfer.") + +def _add_args(p): + p.add_argument("amount") + p.add_argument("--from", dest="source", required=True, help="source account") + p.add_argument("--to", dest="dest", required=True, help="destination account") + p.add_argument("--desc", default=None) + p.add_argument("--date", default=None, help="YYYY-MM-DD (default today)") + p.add_argument("--category", default=None) + p.add_argument("--tags", default=None, help="comma-separated") + p.add_argument("--type", default=None, + help="withdrawal|deposit|transfer (overrides inference)") + +@registry.command("tx add", help="record a transaction", args=_add_args) +def cmd_add(args, ctx): + src = ctx.resolver.account(args.source) + dst = ctx.resolver.account(args.dest) + ttype = args.type or _infer_type(src.get("type"), dst.get("type")) + from datetime import date as _date + split = { + "type": ttype, + "date": args.date or _date.today().isoformat(), + "amount": str(args.amount), + "description": args.desc or "", + "source_id": src["id"], + "destination_id": dst["id"], + } + if args.category: + split["category_name"] = ctx.resolver.category(args.category).get("name", args.category) + if args.tags: + split["tags"] = [t.strip() for t in args.tags.split(",") if t.strip()] + resp = ctx.client.request("POST", "/api/v1/transactions", + body={"transactions": [split]}) + output.emit(output.unwrap(resp), human=ctx.human) + return 0 + +def _list_args(p): + p.add_argument("--since", default=None, help="start date YYYY-MM-DD") + p.add_argument("--until", default=None, help="end date YYYY-MM-DD") + p.add_argument("--account", default=None, help="filter by account name") + p.add_argument("--limit", type=int, default=20) + +@registry.command("tx list", help="list transactions", args=_list_args) +def cmd_list(args, ctx): + if args.account: + acc = ctx.resolver.account(args.account) + path = f"/api/v1/accounts/{acc['id']}/transactions" + else: + path = "/api/v1/transactions" + params = {"limit": args.limit} + if args.since: + params["start"] = args.since + if args.until: + params["end"] = args.until + resp = ctx.client.request("GET", path, params=params) + output.emit(output.unwrap(resp), human=ctx.human) + return 0 + +def _id_arg(p): + p.add_argument("id") + +@registry.command("tx get", help="show one transaction", args=_id_arg) +def cmd_get(args, ctx): + resp = ctx.client.request("GET", f"/api/v1/transactions/{args.id}") + output.emit(output.unwrap(resp), human=ctx.human) + return 0 + +def _query_arg(p): + p.add_argument("query") + +@registry.command("tx search", help="search transactions", args=_query_arg) +def cmd_search(args, ctx): + resp = ctx.client.request("GET", "/api/v1/search/transactions", + params={"query": args.query}) + output.emit(output.unwrap(resp), human=ctx.human) + return 0 +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_commands_transaction -v` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add firefly_cli/commands/transaction.py tests/unit/test_commands_transaction.py +git commit -S -m "feat: transaction add/list/get/search with type inference" +``` + +--- + +## Task 10: CLI wiring (argparse from registry, error handling) + +**Files:** +- Create: `firefly_cli/cli.py` +- Test: `tests/unit/test_cli.py` + +- [ ] **Step 1: Write the failing test** + +```python +import unittest +from unittest.mock import patch, MagicMock +from firefly_cli import cli + +class TestCli(unittest.TestCase): + @patch("firefly_cli.cli.config.load") + @patch("firefly_cli.cli.Client") + def test_dispatches_account_list(self, Client, load): + load.return_value = {"url": "https://f", "token": "t"} + Client.return_value.request.return_value = {"data": []} + rc = cli.main(["account", "list"]) + self.assertEqual(rc, 0) + + @patch("firefly_cli.cli.config.load") + def test_config_error_returns_nonzero(self, load): + from firefly_cli.errors import ConfigError + load.side_effect = ConfigError("no config") + rc = cli.main(["account", "list"]) + self.assertEqual(rc, 1) + + def test_auth_set_does_not_require_config(self): + # auth set must run even with no config/client + with patch("firefly_cli.cli.config.write") as w: + w.return_value = "/tmp/x" + rc = cli.main(["auth", "set", "--url", "https://f", "--token", "t"]) + self.assertEqual(rc, 0) +``` + +- [ ] **Step 2: Run test, verify it fails** + +Run: `python -m unittest tests.unit.test_cli -v` +Expected: FAIL, no module. + +- [ ] **Step 3: Write `firefly_cli/cli.py`** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import argparse +import sys +from firefly_cli import config, registry, output +from firefly_cli.client import Client +from firefly_cli.resolver import Resolver +from firefly_cli.context import Context +from firefly_cli.errors import FireflyError +import firefly_cli.commands # noqa: F401 triggers registration + +# Commands that must work without a configured client. +_NO_CLIENT = {"auth set"} + +def _build_parser(): + parser = argparse.ArgumentParser(prog="firefly", + description="CLI for Firefly III") + parser.add_argument("--human", action="store_true", + help="human-readable tables instead of JSON") + parser.add_argument("--url", help="override base URL for this call") + parser.add_argument("--token", help="override token for this call") + sub = parser.add_subparsers(dest="_group", required=True) + + # Group "tx add" / "account list" into nested subparsers. + groups = {} + for cmd in registry.all_commands(): + group, _, leaf = cmd.name.partition(" ") + if group not in groups: + gp = sub.add_parser(group) + groups[group] = gp.add_subparsers(dest="_leaf", required=True) + lp = groups[group].add_parser(leaf, help=cmd.help) + if cmd.args: + cmd.args(lp) + lp.set_defaults(_handler=cmd.handler, _cmdname=cmd.name) + return parser + +def main(argv=None): + argv = sys.argv[1:] if argv is None else argv + parser = _build_parser() + args = parser.parse_args(argv) + try: + if args._cmdname in _NO_CLIENT: + ctx = Context(client=None, resolver=None, human=args.human) + else: + cfg = config.load() + url = args.url or cfg["url"] + token = args.token or cfg["token"] + client = Client(url, token) + ctx = Context(client=client, resolver=Resolver(client), + human=args.human) + return args._handler(args, ctx) + except FireflyError as e: + output.emit_error(str(e)) + return 1 + +if __name__ == "__main__": + raise SystemExit(main()) +``` + +- [ ] **Step 4: Run test, verify it passes** + +Run: `python -m unittest tests.unit.test_cli -v` +Expected: PASS. + +- [ ] **Step 5: Run the whole unit suite and the CLI help** + +Run: +```bash +python -m unittest discover -s tests/unit -v +python -m firefly_cli --help +python -m firefly_cli tx add --help +``` +Expected: all tests PASS; help shows groups and the `tx add` flags. + +- [ ] **Step 6: Commit** + +```bash +git add firefly_cli/cli.py tests/unit/test_cli.py +git commit -S -m "feat: CLI wiring from command registry" +``` + +--- + +## Task 11: Integration tests (gated, live test account, self-cleaning) + +**Files:** +- Create: `tests/integration/__init__.py`, `tests/integration/test_live.py` + +- [ ] **Step 1: Write the gated integration test** + +```python +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> GPL-2.0-only +import os, unittest +from firefly_cli.client import Client +from firefly_cli.resolver import Resolver +from firefly_cli.output import unwrap + +URL = os.environ.get("FIREFLY_TEST_URL") +TOKEN = os.environ.get("FIREFLY_TEST_TOKEN") + +@unittest.skipUnless(URL and TOKEN, + "set FIREFLY_TEST_URL and FIREFLY_TEST_TOKEN to run live tests") +class TestLive(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.client = Client(URL, TOKEN) + cls.resolver = Resolver(cls.client) + + def test_about_shape(self): + resp = self.client.request("GET", "/api/v1/about") + self.assertIn("version", resp["data"]) + + def test_accounts_envelope_and_balance_field(self): + resp = self.client.request("GET", "/api/v1/accounts", + params={"type": "asset", "limit": 5}) + self.assertIn("data", resp) + accs = unwrap(resp) + if accs: + # Confirm the balance field name assumed by the design. + self.assertIn("current_balance", accs[0], + "balance field name differs; update account balance cmd + unit test") + + def test_create_then_delete_transaction(self): + # Needs two asset accounts (or an asset + expense) on the TEST account. + accs = unwrap(self.client.request("GET", "/api/v1/accounts", + params={"type": "asset", "limit": 2})) + if len(accs) < 1: + self.skipTest("test account has no asset account") + exp = unwrap(self.client.request("GET", "/api/v1/accounts", + params={"type": "expense", "limit": 1})) + if not exp: + self.skipTest("test account has no expense account") + body = {"transactions": [{ + "type": "withdrawal", + "date": "2026-06-30", + "amount": "0.01", + "description": "firefly-cli integration test", + "source_id": accs[0]["id"], + "destination_id": exp[0]["id"], + }]} + created = self.client.request("POST", "/api/v1/transactions", body=body) + tx_id = created["data"]["id"] + try: + got = self.client.request("GET", f"/api/v1/transactions/{tx_id}") + self.assertEqual(got["data"]["id"], tx_id) + finally: + self.client.request("DELETE", f"/api/v1/transactions/{tx_id}") +``` + +- [ ] **Step 2: Run gated tests with no env (must skip)** + +Run: `python -m unittest discover -s tests/integration -v` +Expected: tests SKIPPED (no env vars set). + +- [ ] **Step 3: Run against the live test account** + +Ask the user to provide test-account creds, then: +```bash +FIREFLY_TEST_URL=<url> FIREFLY_TEST_TOKEN=<tok> \ + python -m unittest discover -s tests/integration -v +``` +Expected: PASS. If `current_balance` or the envelope differs, fix the relevant +production code + its unit test, then re-run. + +- [ ] **Step 4: Commit** + +```bash +git add tests/integration/ +git commit -S -m "test: gated live integration tests, self-cleaning" +``` + +--- + +## Task 12: Final pass, docs, push + +- [ ] **Step 1: Full suite + editable install smoke test** + +```bash +python -m unittest discover -s tests -v +pip install -e . +firefly --help +``` +Expected: tests PASS; `firefly` entry point works. + +- [ ] **Step 2: Update README** with the final verified command list and a + short "for agents" note (JSON default, exit codes, name resolution behavior). + +- [ ] **Step 3: Commit and push** + +```bash +git add README.md +git commit -S -m "docs: finalize README command reference" +git push +``` +Expected: pushed to `origin` (danix_git:firefly-cli). Verify signed: +`git log --format='%h %G? %s' | head` (want `G`). + +--- + +## Appendix A: CLAUDE.md content (copy verbatim in Task 1, Step 7) + +```markdown +# firefly-cli + +CLI tool letting an LLM agent (and the user) interact with a Firefly III +instance over its REST API. Python package, command `firefly`. + +## Reference, do not modify +The Firefly III source is cloned at `../GITHUB/firefly-iii/` for reference only +(API shapes, transformers, route definitions). NEVER write to it. + +## Architecture +- `firefly_cli/` package. Shared primitives: `config.py` (env over TOML file), + `client.py` (HTTP + auth + error surfacing), `resolver.py` (name->id), + `output.py` (JSON default, `--human` tables), `registry.py` + `context.py`. +- Commands live in `firefly_cli/commands/`, one module per group. Each command + registers via the `@registry.command("group leaf", ...)` decorator. +- `cli.py` builds argparse subparsers from the registry. `commands/__init__.py` + imports every command module so they self-register. + +## Adding a command (the expandability rule) +1. Add or edit a module in `firefly_cli/commands/`. +2. Decorate the handler: `@registry.command("budget status", help=..., args=fn)`. + `args` is `fn(subparser)` adding argparse arguments; handler is + `fn(args, ctx) -> int`. `ctx` has `.client`, `.resolver`, `.human`. +3. If it is a new module, add it to the import line in `commands/__init__.py`. +4. Write a unit test under `tests/unit/` (mock `ctx.client` / `ctx.resolver`). +No other files change. + +## Conventions +- Python 3.11+, standard library only. No third-party runtime deps. +- Output JSON by default (agent-first); `--human` for tables. +- Name args resolve to IDs; ambiguous or missing names are HARD errors listing + candidates. Never silently guess an account (real money). +- All errors are `firefly_cli.errors.FireflyError` subclasses; `cli.main` + catches them, prints `{"error": ...}` to stderr, returns exit code 1. + +## Testing +- `python -m unittest discover -s tests/unit` — mocked, always run. TDD. +- Integration tests in `tests/integration/` hit a LIVE TEST ACCOUNT, gated by + `FIREFLY_TEST_URL` / `FIREFLY_TEST_TOKEN`, skipped otherwise. Write tests + create-then-delete their own records. NEVER point these at real data. + +## License +GPLv2-only. Per-file header: `Copyright (C) 2026 Danilo M. <danix@danix.xyz>`. +``` +``` |