commit

Author: bufdev

cmd/ibctl/internal/command/trade/trade.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package trade implements the "trade" command group.
+package trade
+
+import (
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/trade/tradelist"
+)
+
+// NewCommand returns a new trade command group.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	return &appcmd.Command{
+		Use:   name,
+		Short: "Display realized trade information",
+		SubCommands: []*appcmd.Command{
+			tradelist.NewCommand("list", builder),
+		},
+	}
+}

cmd/ibctl/internal/command/trade/tradelist/tradelist.go

@@ -0,0 +1,248 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package tradelist implements the "trade list" command.
+package tradelist
+
+import (
+	"context"
+	"os"
+	"strings"
+	"time"
+
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/ibctlcmd"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlconfig"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlfxrates"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlmerge"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctltrades"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/mathpb"
+	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/standard/xtime"
+	"github.com/spf13/pflag"
+)
+
+const (
+	// formatFlagName is the flag name for the output format.
+	formatFlagName = "format"
+	// downloadFlagName is the flag name for downloading fresh data before displaying.
+	downloadFlagName = "download"
+	// fromFlagName is the flag name for filtering on sale date (inclusive, YYYYMMDD).
+	fromFlagName = "from"
+	// toFlagName is the flag name for filtering on sale date (inclusive, YYYYMMDD).
+	toFlagName = "to"
+	// baseCurrencyFlagName is the flag name for the base currency for P&L conversion.
+	baseCurrencyFlagName = "base-currency"
+)
+
+// NewCommand returns a new trade list command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "List realized trades with FIFO lot matching for tax reporting",
+		Long: `List realized trades (sells matched to their FIFO buy lots) for tax reporting.
+
+Each row represents one lot match. A sell of 150 shares that consumes two
+FIFO lots (100 + 50) produces two rows, each with its own purchase date
+and cost basis.
+
+P&L is computed in native currency and the --base-currency. FX rates are
+looked up for the specific purchase and sale dates:
+
+  Example: Buy 100 shares of VFV.TO (CAD) on 2024-03-15 at C$102.50,
+  sell on 2025-01-10 at C$115.30, with --base-currency USD:
+
+  - Purchase rate CAD→USD on 2024-03-15: 0.7380
+  - Sale rate CAD→USD on 2025-01-10: 0.6950
+  - Purchase USD = 102.50 * 0.7380 = $75.64
+  - Sale USD     = 115.30 * 0.6950 = $80.13
+  - P&L USD      = (80.13 - 75.64) * 100 = $449.00
+  - Holding period: 301 days (< 365) → STCG USD = $449.00
+
+Use --from and --to to filter by sale date (YYYYMMDD format) for a specific
+tax year, e.g. --from 20250101 --to 20251231.`,
+		Args: appcmd.NoArgs,
+		Run: builder.NewRunFunc(
+			func(ctx context.Context, container appext.Container) error {
+				return run(ctx, container, flags)
+			},
+		),
+		BindFlags: flags.Bind,
+	}
+}
+
+type flags struct {
+	// Dir is the base directory containing ibctl.yaml and data subdirectories.
+	Dir string
+	// Format is the output format (table, csv, json).
+	Format string
+	// Download fetches fresh data before displaying.
+	Download bool
+	// From filters on sale date (inclusive). Format: YYYYMMDD.
+	From string
+	// To filters on sale date (inclusive). Format: YYYYMMDD.
+	To string
+	// BaseCurrency is the target currency for P&L conversion (e.g., "USD", "CAD").
+	BaseCurrency string
+}
+
+func newFlags() *flags {
+	return &flags{}
+}
+
+// Bind registers the flag definitions with the given flag set.
+func (f *flags) Bind(flagSet *pflag.FlagSet) {
+	flagSet.StringVar(&f.Dir, ibctlcmd.DirFlagName, ".", "The ibctl directory containing ibctl.yaml")
+	flagSet.StringVar(&f.Format, formatFlagName, "table", "Output format (table, csv, json)")
+	flagSet.BoolVar(&f.Download, downloadFlagName, false, "Download fresh data before displaying")
+	flagSet.StringVar(&f.From, fromFlagName, "", "Filter on sale date (inclusive, format: YYYYMMDD)")
+	flagSet.StringVar(&f.To, toFlagName, "", "Filter on sale date (inclusive, format: YYYYMMDD)")
+	flagSet.StringVar(&f.BaseCurrency, baseCurrencyFlagName, "USD", "Base currency for P&L conversion (e.g., USD, CAD)")
+}
+
+func run(ctx context.Context, container appext.Container, flags *flags) error {
+	format, err := cliio.ParseFormat(flags.Format)
+	if err != nil {
+		return appcmd.NewInvalidArgumentError(err.Error())
+	}
+	// Normalize base currency to uppercase for case-insensitive matching.
+	baseCurrency := strings.ToUpper(flags.BaseCurrency)
+	// Select the formatting function based on the base currency.
+	formatBase := formatBaseFunc(baseCurrency)
+	formatBaseMicros := formatBaseMicrosFunc(baseCurrency)
+	// Parse --from and --to date filters.
+	fromDate, err := parseDateFlag(flags.From, fromFlagName)
+	if err != nil {
+		return err
+	}
+	toDate, err := parseDateFlag(flags.To, toFlagName)
+	if err != nil {
+		return err
+	}
+	// Read and validate the configuration file from the base directory.
+	config, err := ibctlconfig.ReadConfig(flags.Dir)
+	if err != nil {
+		return err
+	}
+	// Download fresh data if --download is set.
+	if flags.Download {
+		downloader, err := ibctlcmd.NewDownloader(container, flags.Dir)
+		if err != nil {
+			return err
+		}
+		if err := downloader.Download(ctx); err != nil {
+			return err
+		}
+	}
+	// Merge trade data from all sources.
+	mergedData, err := ibctlmerge.Merge(
+		ibctlpath.DataAccountsDirPath(config.DirPath),
+		ibctlpath.CacheAccountsDirPath(config.DirPath),
+		ibctlpath.ActivityStatementsDirPath(config.DirPath),
+		ibctlpath.SeedDirPath(config.DirPath),
+		config.AccountAliases,
+		config.Additions,
+	)
+	if err != nil {
+		return err
+	}
+	// Load FX rates for base currency conversion.
+	fxStore := ibctlfxrates.NewStore(ibctlpath.CacheFXDirPath(config.DirPath))
+	// Compute realized trades via FIFO lot matching.
+	result, err := ibctltrades.GetTradeList(mergedData.Trades, fxStore, baseCurrency, fromDate, toDate)
+	if err != nil {
+		return err
+	}
+	// Log any unmatched sells as warnings.
+	logger := container.Logger()
+	for _, unmatched := range result.UnmatchedSells {
+		logger.Warn("unmatched sell (buy likely before data window)",
+			"account", unmatched.AccountAlias,
+			"symbol", unmatched.Symbol,
+			"unmatched_quantity", mathpb.ToString(unmatched.UnmatchedQuantity),
+		)
+	}
+	// Write output in the requested format.
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		headers := ibctltrades.TradeOverviewHeaders(baseCurrency)
+		rows := make([][]string, 0, len(result.Trades))
+		for _, t := range result.Trades {
+			rows = append(rows, ibctltrades.TradeOverviewToTableRow(t, formatBase))
+		}
+		// Build totals row with sums for pnl/stcg/ltcg in base currency.
+		totals := ibctltrades.ComputeTotals(result.Trades, formatBaseMicros)
+		totalsRow := make([]string, len(headers))
+		totalsRow[0] = "TOTAL"
+		// P&L BASE at column 13, STCG BASE at 14, LTCG BASE at 15.
+		totalsRow[13] = totals.PnLBase
+		totalsRow[14] = totals.STCGBase
+		totalsRow[15] = totals.LTCGBase
+		return cliio.WriteTableWithTotals(writer, headers, rows, totalsRow)
+	case cliio.FormatCSV:
+		headers := ibctltrades.TradeOverviewHeaders(baseCurrency)
+		records := make([][]string, 0, len(result.Trades)+1)
+		records = append(records, headers)
+		for _, t := range result.Trades {
+			records = append(records, ibctltrades.TradeOverviewToRow(t))
+		}
+		return cliio.WriteCSVRecords(writer, records)
+	case cliio.FormatJSON:
+		return cliio.WriteJSON(writer, result.Trades...)
+	default:
+		return appcmd.NewInvalidArgumentErrorf("unsupported format: %s", format)
+	}
+}
+
+// parseDateFlag parses a YYYYMMDD date string into an xtime.Date.
+// Returns a zero date if the input is empty.
+func parseDateFlag(value string, flagName string) (xtime.Date, error) {
+	if value == "" {
+		return xtime.Date{}, nil
+	}
+	parsed, err := time.Parse("20060102", value)
+	if err != nil {
+		return xtime.Date{}, appcmd.NewInvalidArgumentErrorf("--%s must be in YYYYMMDD format: %s", flagName, value)
+	}
+	return xtime.Date{
+		Year:  parsed.Year(),
+		Month: parsed.Month(),
+		Day:   parsed.Day(),
+	}, nil
+}
+
+// formatBaseFunc returns a formatting function for display values in the given currency.
+// Uses currency-specific prefixes ($ for USD, C$ for CAD) when available,
+// falls back to raw decimal for other currencies.
+func formatBaseFunc(baseCurrency string) func(string) string {
+	switch baseCurrency {
+	case "USD":
+		return cliio.FormatUSD
+	case "CAD":
+		return cliio.FormatCAD
+	default:
+		// For other currencies, return the raw decimal value.
+		return func(v string) string { return v }
+	}
+}
+
+// formatBaseMicrosFunc returns a formatting function for micros values in the given currency.
+func formatBaseMicrosFunc(baseCurrency string) func(int64) string {
+	switch baseCurrency {
+	case "USD":
+		return cliio.FormatUSDMicros
+	case "CAD":
+		return cliio.FormatCADMicros
+	default:
+		// For other currencies, format as raw decimal without a prefix.
+		return func(micros int64) string {
+			return moneypb.MoneyValueToString(moneypb.MoneyFromMicros(baseCurrency, micros))
+		}
+	}
+}

cmd/ibctl/main.go

@@ -14,6 +14,7 @@ import (
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/download"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/probe"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/trade"
 )
 
 func main() {
@@ -39,6 +40,7 @@ Run "ibctl config init" to create a new ibctl directory.`,
 			download.NewCommand("download", builder),
 			holding.NewCommand("holding", builder),
 			probe.NewCommand("probe", builder),
+			trade.NewCommand("trade", builder),
 		},
 	}
 }