Initial commit

Signed-off-by: birkhoff <git@birkhoff.me>

Author: birkhofflee

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Setup Cachix
+        uses: cachix/cachix-action@v15
+        with:
+          name: devenv
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          skipPush: true
+
+      - name: Check flake
+        run: nix flake check
+
+      - name: Build default package
+        run: nix build
+
+      - name: Test cross-compilation
+        run: |
+          echo "Testing cross-compilation builds..."
+          nix build .#statements-linux-amd64
+          nix build .#statements-darwin-arm64

.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Setup Cachix
+        uses: cachix/cachix-action@v15
+        with:
+          name: devenv
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          skipPush: true
+
+      - name: Build Linux AMD64
+        run: |
+          nix build .#statements-linux-amd64
+          cp result/bin/statements statements-linux-amd64
+
+      - name: Build Linux ARM64
+        run: |
+          nix build .#statements-linux-arm64
+          cp result/bin/statements statements-linux-arm64
+
+      - name: Build Darwin AMD64
+        run: |
+          nix build .#statements-darwin-amd64
+          cp result/bin/statements statements-darwin-amd64
+
+      - name: Build Darwin ARM64
+        run: |
+          nix build .#statements-darwin-arm64
+          cp result/bin/statements statements-darwin-arm64
+
+      - name: Build Windows AMD64
+        run: |
+          nix build .#statements-windows-amd64
+          cp result/bin/statements statements-windows-amd64.exe
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            statements-linux-amd64
+            statements-linux-arm64
+            statements-darwin-amd64
+            statements-darwin-arm64
+            statements-windows-amd64.exe
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,44 @@
+statements
+
+# ---- Go ----
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Code coverage profiles and other test artifacts
+*.out
+coverage.*
+*.coverprofile
+profile.cov
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# Editor/IDE
+# .idea/
+# .vscode/
+
+# ---- Nix ----
+# Ignore build outputs from performing a nix-build or `nix build` command
+result
+result-*
+
+# Ignore automatically generated direnv output
+.direnv
+

CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A Terminal User Interface (TUI) application for analyzing credit card statements. Built with Go and the Bubble Tea framework, it provides an interactive interface to browse statements and categorize transactions. Currently tested with HSBC Taiwan credit card statements.
+
+## Building and Running
+
+### Traditional Go Build
+
+```bash
+# Build the application
+go build -o statements
+
+# Run the application
+./statements <path-to-statementlist.json>
+```
+
+### Nix Flakes
+
+The project includes a Nix flake for reproducible builds. Requires Nix with flakes enabled.
+
+```bash
+# Run directly
+nix run . -- <path-to-statementlist.json>
+
+# Build the application
+nix build
+./result/bin/statements <path-to-statementlist.json>
+
+# Enter development environment (provides Go 1.25, gopls, gotools, claude, git, jq)
+nix develop
+
+# Cross-platform builds
+nix build .#statements-linux-amd64
+nix build .#statements-linux-arm64
+nix build .#statements-darwin-amd64
+nix build .#statements-darwin-arm64
+nix build .#statements-windows-amd64
+```
+
+Note: The flake is configured to allow unfree packages (required for claude-code).
+
+## Architecture
+
+### Core Components
+
+The codebase is structured around three main files:
+
+- **types.go**: Defines the data model (`Transaction`, `Statement`, `CategorizedTransactions`)
+- **analyzer.go**: Transaction analysis logic including categorization, normalization, and data loading
+- **main.go**: TUI implementation using Bubble Tea framework (model, view, update pattern)
+
+### Data Flow
+
+1. JSON statements are loaded via `LoadStatements()` in analyzer.go
+2. Transactions are categorized by `CategorizeTransactions()` which:
+   - Normalizes descriptions using `ToCDB()` (full-width to half-width character conversion)
+   - Detects Apple Pay transactions and extracts card metadata
+   - Categorizes transactions by type (Transport, Food, Shopping, Travel, Utilities, Other)
+3. The Bubble Tea model manages two views (Summary, Statements) with dual-panel layout
+4. The Statements view uses two Bubble Tea table components for navigation
+
+### Transaction Categorization System
+
+The categorization happens in two layers:
+
+1. **Payment Method Detection** (analyzer.go:124-159): Detects Apple Pay (`APE` prefix with card last 4 digits), PayPal, and foreign transaction fees
+2. **Merchant Category Detection** (analyzer.go:48-97): Uses prefix/substring matching to categorize by merchant type
+
+Each transaction gets:
+- A `NormalizedDescription` (half-width characters)
+- An `ApplePayCardLast4` field (if applicable)
+- A `Category` field (Transport/Food/Shopping/Travel/Utilities/Other)
+
+### View State Management
+
+The model tracks:
+- Current view mode (summary or statements)
+- Selected statement index
+- Sort mode (Date/Amount/Location/Category)
+- Category filter (All or specific category)
+- Focused table (statements or transactions)
+
+Key state update: `updateTransactionsTable()` (main.go:437-610) rebuilds the transaction table when:
+- Statement selection changes
+- Sort mode changes
+- Category filter changes
+
+### Foreign Transaction Fee Handling
+
+Foreign fees are aggregated and displayed as a single row per statement (main.go:446-462, 580-606). They are filtered out from regular transactions and summarized to avoid cluttering the transaction list.
+
+## Key Technical Details
+
+### Character Normalization
+
+The `ToCDB()` function (analyzer.go:24-38) converts full-width CJK characters to half-width for consistent string matching. This is critical for proper categorization of Chinese/Japanese merchant names.
+
+### Apple Pay Extraction
+
+Uses regex `^APE(\d{4})` to extract the last 4 digits of the card used for Apple Pay transactions. The clean description (without the APE prefix) is obtained via `GetCleanDescription()`.
+
+### Table Navigation
+
+Implements wrap-around navigation (main.go:256-312) - pressing up at the first item wraps to the last item, and vice versa. Also supports Home/End keys and Page Up/Down for quick navigation.
+
+### Dynamic Column Layout
+
+The transactions table adjusts columns based on the active category filter (main.go:502-523). When filtering by a specific category, the Category column is hidden to provide more space for the Description column.