feat: tx list --flat, account create --if-not-exists, --since/--until doc (v0.3.6)v0.3.6

Three smaller ISSUES.md items, one PATCH (two optional flags + a doc fix; no
existing caller or JSON shape changes).

- tx list --flat: emit one top-level object per split (journal id repeated),
  dropping the transactions[] nesting so single-split journals script cleanly.
  JSON-only; --human already explodes splits into a table.
- account create --if-not-exists: resolve the name first; on a clash return the
  existing account with "existed": true (exit 0) instead of surfacing Firefly's
  422, so import scripts are idempotent. Detects via resolver, not by parsing
  the error string.
- SKILL.md documents that --since/--until filter on the transaction date (the
  value date); Firefly journals have a single date field, no separate book date
  (verified against firefly-iii TimeCollection setRange).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

3 files changed, 100 insertions, 6 deletions

diff --git a/tests/unit/test_commands_account.py b/tests/unit/test_commands_account.py
index 4a01292..c328890 100644
--- a/tests/unit/test_commands_account.py
+++ b/tests/unit/test_commands_account.py
@@ -43,7 +43,8 @@ class TestAccountCmd(unittest.TestCase):
 
 class TestAccountCreate(unittest.TestCase):
     def _args(self, **kw):
-        base = dict(name=None, type=None, opening_balance=None, currency=None)
+        base = dict(name=None, type=None, opening_balance=None, currency=None,
+                    if_not_exists=False)
         base.update(kw)
         m = MagicMock()
         m.configure_mock(**base)  # 'name' is reserved in MagicMock ctor, not configure_mock
@@ -89,3 +90,36 @@ class TestAccountCreate(unittest.TestCase):
         with self.assertRaises(FireflyError):
             acct.cmd_create(self._args(name="X", type="bogus"), ctx)
         client.request.assert_not_called()
+
+    def test_if_not_exists_returns_existing_no_post(self):
+        ctx, client, resolver = make_ctx()
+        resolver.account.return_value = {"id": "5", "name": "Savings",
+                                         "type": "asset"}
+        rc = acct.cmd_create(
+            self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(rc, 0)
+        resolver.account.assert_called_once_with("Savings")
+        client.request.assert_not_called()  # existed -> no create
+
+    def test_if_not_exists_creates_when_missing(self):
+        from firefly_cli.errors import ResolutionError
+        ctx, client, resolver = make_ctx()
+        resolver.account.side_effect = ResolutionError('No account named "Savings"')
+        client.request.return_value = {"data": {"id": "9", "attributes": {}}}
+        rc = acct.cmd_create(
+            self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(rc, 0)
+        method, path = client.request.call_args[0][:2]
+        self.assertEqual((method, path), ("POST", "/api/v1/accounts"))
+
+    def test_if_not_exists_emits_existed_flag(self):
+        import io, json
+        from contextlib import redirect_stdout
+        ctx, client, resolver = make_ctx()
+        resolver.account.return_value = {"id": "5", "name": "Savings"}
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            acct.cmd_create(
+                self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(json.loads(buf.getvalue()),
+                         {"id": "5", "name": "Savings", "existed": True})
diff --git a/tests/unit/test_commands_transaction.py b/tests/unit/test_commands_transaction.py
index 0fa02ac..28882d3 100644
--- a/tests/unit/test_commands_transaction.py
+++ b/tests/unit/test_commands_transaction.py
@@ -264,7 +264,7 @@ class TestTxList(unittest.TestCase):
         ctx, client, _ = make_ctx()
         client.request.return_value = {"data": []}
         args = MagicMock(since="2026-06-01", until="2026-06-30",
-                         account=None, limit=10, all=False)
+                         account=None, limit=10, all=False, flat=False)
         tx.cmd_list(args, ctx)
         params = client.request.call_args[1]["params"]
         self.assertEqual(params["start"], "2026-06-01")
@@ -280,7 +280,7 @@ class TestTxList(unittest.TestCase):
             "meta": {"pagination": {"total": 90, "count": 20,
                                     "current_page": 1, "total_pages": 5}},
         }
-        args = MagicMock(since=None, until=None, account=None, limit=20, all=False)
+        args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False)
         buf = io.StringIO()
         with redirect_stderr(buf):
             tx.cmd_list(args, ctx)
@@ -296,12 +296,49 @@ class TestTxList(unittest.TestCase):
             "meta": {"pagination": {"total": 1, "count": 1,
                                     "current_page": 1, "total_pages": 1}},
         }
-        args = MagicMock(since=None, until=None, account=None, limit=20, all=False)
+        args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False)
         buf = io.StringIO()
         with redirect_stderr(buf):
             tx.cmd_list(args, ctx)
         self.assertEqual(buf.getvalue(), "")
 
+    def test_list_flat_explodes_splits_json(self):
+        import io, json
+        from contextlib import redirect_stdout
+        ctx, client, _ = make_ctx()
+        client.request.return_value = {
+            "data": [{"id": "7", "type": "transactions", "attributes": {
+                "transactions": [{"amount": "5", "source_name": "A"}]}}],
+            "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}},
+        }
+        args = MagicMock(since=None, until=None, account=None, limit=20,
+                         all=False, flat=True)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            tx.cmd_list(args, ctx)
+        out = json.loads(buf.getvalue())
+        self.assertEqual(out, [{"amount": "5", "source_name": "A", "id": "7"}])
+
+    def test_list_flat_skipped_for_human(self):
+        # --human path must keep nested rows so the table renderer explodes them.
+        import io
+        from contextlib import redirect_stdout
+        ctx, client, _ = make_ctx()
+        ctx = Context(client=client, resolver=ctx.resolver, human=True)
+        client.request.return_value = {
+            "data": [{"id": "7", "attributes": {
+                "transactions": [{"amount": "5", "source_name": "A",
+                                  "destination_name": "B", "type": "withdrawal"}]}}],
+            "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}},
+        }
+        args = MagicMock(since=None, until=None, account=None, limit=20,
+                         all=False, flat=True)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            tx.cmd_list(args, ctx)
+        # human table shows the exploded split value; not raw JSON
+        self.assertIn("5", buf.getvalue())
+
     def test_list_all_paginates(self):
         ctx, client, _ = make_ctx()
         def page(method, path, params=None, body=None):
@@ -312,7 +349,7 @@ class TestTxList(unittest.TestCase):
                                         "current_page": p, "total_pages": 2}},
             }
         client.request.side_effect = page
-        args = MagicMock(since=None, until=None, account=None, limit=2, all=True)
+        args = MagicMock(since=None, until=None, account=None, limit=2, all=True, flat=False)
         rc = tx.cmd_list(args, ctx)
         self.assertEqual(rc, 0)
         self.assertEqual(client.request.call_count, 2)
diff --git a/tests/unit/test_output.py b/tests/unit/test_output.py
index 2e3e5ea..069a21d 100644
--- a/tests/unit/test_output.py
+++ b/tests/unit/test_output.py
@@ -1,6 +1,6 @@
 import io, json, unittest
 from contextlib import redirect_stdout
-from firefly_cli.output import unwrap, emit
+from firefly_cli.output import unwrap, emit, flatten_tx
 
 class TestOutput(unittest.TestCase):
     def test_unwrap_list_returns_clean_objects(self):
@@ -22,6 +22,29 @@ class TestOutput(unittest.TestCase):
             emit([{"id": "1", "name": "x"}], human=False)
         self.assertEqual(json.loads(buf.getvalue()), [{"id": "1", "name": "x"}])
 
+    def test_flatten_single_split(self):
+        rows = [{"id": "10", "group_title": None, "transactions": [
+            {"amount": "5.00", "source_name": "A", "destination_name": "B",
+             "type": "withdrawal"}]}]
+        flat = flatten_tx(rows)
+        self.assertEqual(len(flat), 1)
+        self.assertNotIn("transactions", flat[0])
+        self.assertEqual(flat[0]["id"], "10")
+        self.assertEqual(flat[0]["amount"], "5.00")
+        self.assertEqual(flat[0]["source_name"], "A")
+
+    def test_flatten_multi_split_repeats_id(self):
+        rows = [{"id": "20", "transactions": [
+            {"amount": "1", "type": "withdrawal"},
+            {"amount": "2", "type": "withdrawal"}]}]
+        flat = flatten_tx(rows)
+        self.assertEqual([f["id"] for f in flat], ["20", "20"])
+        self.assertEqual([f["amount"] for f in flat], ["1", "2"])
+
+    def test_flatten_passes_through_non_tx_rows(self):
+        rows = [{"id": "1", "name": "Checking"}]
+        self.assertEqual(flatten_tx(rows), rows)
+
     def test_emit_human_table_contains_values(self):
         buf = io.StringIO()
         with redirect_stdout(buf):