commit

Author: bufdev

cmd/ibctl/internal/command/holding/holding.go

@@ -13,6 +13,7 @@ import (
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/holdinglist"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/holdingvalue"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/lot"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/projectedincome"
 )
 
 // NewCommand returns a new holding command group.
@@ -25,6 +26,7 @@ func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
 			geo.NewCommand("geo", builder),
 			holdinglist.NewCommand("list", builder),
 			lot.NewCommand("lot", builder),
+			projectedincome.NewCommand("projected-income", builder),
 			holdingvalue.NewCommand("value", builder),
 		},
 	}

cmd/ibctl/internal/command/holding/projectedincome/projectedincome.go

@@ -0,0 +1,265 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package projectedincome implements the "holding projected-income" command.
+package projectedincome
+
+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/ibctlprojectedincome"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
+	"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"
+	// baseCurrencyFlagName is the flag name for the base currency for value conversion.
+	baseCurrencyFlagName = "base-currency"
+)
+
+// NewCommand returns a new projected income command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "Project annual and remaining-year income from the portfolio",
+		Long: `Project estimated income from bonds (coupons), equities (dividends),
+and cash (interest), with pre-tax and post-tax estimates.
+
+INCOME SOURCES
+
+  Bond coupons     Parsed from the bond symbol (e.g., "CVX 2.236 05/11/30" is
+                   a 2.236% coupon). Semiannual payments. Annual income is
+                   face value * coupon rate. Remaining-year income counts
+                   coupon dates between today and December 31.
+
+  ETF/stock divs   Trailing 12-month per-share dividends fetched from Yahoo
+                   Finance, multiplied by current position quantity.
+                   Remaining-year income is pro-rated by remaining fraction.
+
+  Cash interest    Cash balance * annual rate from interest_rates config map.
+                   Remaining-year income is pro-rated by remaining fraction.
+
+COLUMNS
+
+  GROUP            BOND, EQUITY, or CASH
+  SYMBOL           Ticker symbol (currency code for cash)
+  TYPE             COUPON, DIVIDEND, or INTEREST
+  YIELD %          Annualized yield percentage
+  EST ANNUAL       Estimated annual income in base currency
+  EST REMAINING    Estimated remaining calendar year income in base currency
+
+TAX RATES
+
+  Tax rates from config: taxes.dividend_tax applied to dividends,
+  taxes.interest_tax applied to coupons and cash interest.
+  Cash interest rates from interest_rates config map.`,
+		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 {
+	// Format is the output format (table, csv, json).
+	Format string
+	// Download fetches fresh data before displaying.
+	Download bool
+	// BaseCurrency is the target currency for value 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.Format, formatFlagName, "table", "Output format (table, csv, json)")
+	flagSet.BoolVar(&f.Download, downloadFlagName, false, "Download fresh data before displaying")
+	flagSet.StringVar(&f.BaseCurrency, baseCurrencyFlagName, "USD", "Base currency for value 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)
+	// Resolve the ibctl directory from the IBKR_DIR environment variable.
+	dirPath, err := ibctlcmd.DirPath(container)
+	if err != nil {
+		return err
+	}
+	// Read and validate the configuration file from the base directory.
+	config, err := ibctlconfig.ReadConfig(dirPath)
+	if err != nil {
+		return err
+	}
+	// Download fresh data if --download is set.
+	if flags.Download {
+		downloader, err := ibctlcmd.NewDownloader(container, dirPath)
+		if err != nil {
+			return err
+		}
+		if err := downloader.Download(ctx); err != nil {
+			return err
+		}
+	}
+	// Merge seed lots + Activity Statement CSVs + Flex Query cached data across all accounts.
+	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))
+	// Create Yahoo Finance client for dividend data.
+	yahooClient := yahoofinance.NewClient()
+	// Compute projected income from all positions, dividend data, and cash balances.
+	result, err := ibctlprojectedincome.GetProjectedIncome(
+		ctx,
+		container.Logger(),
+		mergedData.Positions,
+		mergedData.CashPositions,
+		config,
+		fxStore,
+		yahooClient,
+		baseCurrency,
+		time.Now(),
+	)
+	if err != nil {
+		return err
+	}
+	// Write output in the requested format.
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		return writeTable(writer, result, baseCurrency, formatBase, formatBaseMicros)
+	case cliio.FormatCSV:
+		return writeCSV(writer, result, baseCurrency)
+	case cliio.FormatJSON:
+		return cliio.WriteJSON(writer, result.Rows...)
+	default:
+		return appcmd.NewInvalidArgumentErrorf("unsupported format: %s", format)
+	}
+}
+
+// writeTable writes the projected income as a formatted table with group sections,
+// subtotals, and pre/post-tax grand totals.
+func writeTable(writer *os.File, result *ibctlprojectedincome.ProjectedIncomeResult, baseCurrency string, formatBase func(string) string, formatBaseMicros func(int64) string) error {
+	headers := ibctlprojectedincome.ProjectedIncomeHeaders(baseCurrency)
+	var rows [][]string
+	// Group rows by their GROUP field for ordered display with subtotals.
+	groups := []string{ibctlprojectedincome.IncomeGroupBond, ibctlprojectedincome.IncomeGroupEquity, ibctlprojectedincome.IncomeGroupCash}
+	rowsByGroup := make(map[string][]*ibctlprojectedincome.ProjectedIncomeRow)
+	for _, row := range result.Rows {
+		rowsByGroup[row.Group] = append(rowsByGroup[row.Group], row)
+	}
+	for _, group := range groups {
+		groupRows := rowsByGroup[group]
+		if len(groupRows) == 0 {
+			continue
+		}
+		// Add data rows for this group.
+		for _, row := range groupRows {
+			rows = append(rows, ibctlprojectedincome.ProjectedIncomeRowToTableRow(row, formatBase))
+		}
+		// Add subtotal row for this group.
+		for _, subtotal := range result.GroupSubtotals {
+			if subtotal.Group == group {
+				// Blank separator row before subtotal.
+				rows = append(rows, make([]string, len(headers)))
+				subtotalRow := make([]string, len(headers))
+				subtotalRow[0] = group + " TOTAL"
+				subtotalRow[4] = formatBaseMicros(subtotal.AnnualBaseMicros)
+				subtotalRow[5] = formatBaseMicros(subtotal.RemainingBaseMicros)
+				rows = append(rows, subtotalRow)
+				// Blank separator row after subtotal.
+				rows = append(rows, make([]string, len(headers)))
+				break
+			}
+		}
+	}
+	// Append pre-tax and post-tax grand total rows.
+	grandTotal := result.GrandTotal
+	preTaxRow := make([]string, len(headers))
+	preTaxRow[0] = "TOTAL (pre-tax)"
+	preTaxRow[4] = formatBaseMicros(grandTotal.AnnualPreTaxMicros)
+	preTaxRow[5] = formatBaseMicros(grandTotal.RemainingPreTaxMicros)
+	rows = append(rows, preTaxRow)
+	postTaxRow := make([]string, len(headers))
+	postTaxRow[0] = "TOTAL (post-tax)"
+	postTaxRow[4] = formatBaseMicros(grandTotal.AnnualPostTaxMicros)
+	postTaxRow[5] = formatBaseMicros(grandTotal.RemainingPostTaxMicros)
+	rows = append(rows, postTaxRow)
+	return cliio.WriteTable(writer, headers, rows)
+}
+
+// writeCSV writes the projected income as CSV records.
+func writeCSV(writer *os.File, result *ibctlprojectedincome.ProjectedIncomeResult, baseCurrency string) error {
+	headers := ibctlprojectedincome.ProjectedIncomeHeaders(baseCurrency)
+	records := make([][]string, 0, len(result.Rows)+1)
+	records = append(records, headers)
+	for _, row := range result.Rows {
+		records = append(records, ibctlprojectedincome.ProjectedIncomeRowToRow(row))
+	}
+	return cliio.WriteCSVRecords(writer, records)
+}
+
+// formatBaseFunc returns a formatting function for display values in the given currency.
+func formatBaseFunc(baseCurrency string) func(string) string {
+	switch baseCurrency {
+	case "USD":
+		return cliio.FormatUSD
+	case "CAD":
+		return cliio.FormatCAD
+	default:
+		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:
+		return func(micros int64) string {
+			return moneypb.MoneyValueToString(moneypb.MoneyFromMicros(baseCurrency, micros))
+		}
+	}
+}

internal/ibctl/ibctlconfig/ibctlconfig.go

@@ -63,6 +63,13 @@ accounts:
 # realtime_symbols:
 #   SHOP: SHOP.TO
 #   RY: RY.TO
+# Annual interest rates on cash balances for projected income.
+#
+# Optional. Maps currency codes to annual rates (e.g., 0.0312 = 3.12%).
+# Used by "holding projected-income" to estimate cash interest income.
+# interest_rates:
+#   USD: 0.0312
+#   CAD: 0.0154
 `
 
 // ExternalConfigV1 is the YAML-serializable configuration file structure for version v1.
@@ -85,6 +92,9 @@ type ExternalConfigV1 struct {
 	// RealtimeSymbols maps IBKR symbols to Yahoo Finance symbols for --realtime quote lookups.
 	// Only needed for international tickers where symbols differ (e.g., SHOP → SHOP.TO).
 	RealtimeSymbols map[string]string `yaml:"realtime_symbols"`
+	// InterestRates maps currency codes to annual interest rates on cash balances.
+	// Used by projected-income to estimate cash interest income (e.g., {"USD": 0.0312}).
+	InterestRates map[string]float64 `yaml:"interest_rates"`
 }
 
 // ExternalTaxConfigV1 holds capital gains tax rate configuration.
@@ -93,6 +103,10 @@ type ExternalTaxConfigV1 struct {
 	STCG float64 `yaml:"stcg"`
 	// LTCG is the long-term capital gains tax rate (e.g., 0.28 for 28%).
 	LTCG float64 `yaml:"ltcg"`
+	// DividendTax is the tax rate on dividend income (e.g., 0.5353 for 53.53%).
+	DividendTax float64 `yaml:"dividend_tax"`
+	// InterestTax is the tax rate on interest and bond coupon income (e.g., 0.5353 for 53.53%).
+	InterestTax float64 `yaml:"interest_tax"`
 }
 
 // ExternalCategorizationV1 holds classification metadata for a symbol in v1 config.
@@ -160,6 +174,12 @@ type Config struct {
 	// RealtimeSymbols maps IBKR symbols to Yahoo Finance symbols for --realtime quote lookups.
 	// Only needed for international tickers where symbols differ (e.g., SHOP → SHOP.TO).
 	RealtimeSymbols map[string]string
+	// TaxRateDividend is the tax rate on dividend income (e.g., 0.5353).
+	TaxRateDividend float64
+	// TaxRateInterest is the tax rate on interest and bond coupon income (e.g., 0.5353).
+	TaxRateInterest float64
+	// CashInterestRates maps currency codes to annual interest rates on cash balances.
+	CashInterestRates map[string]float64
 }
 
 // SymbolConfig holds classification metadata for a symbol.
@@ -250,22 +270,30 @@ func NewConfigV1(externalConfig ExternalConfigV1, dirPath string) (*Config, erro
 		}
 		cashAdjustments[currency] = units*1_000_000 + micros
 	}
-	// Extract tax rates if configured.
-	var taxRateSTCG, taxRateLTCG float64
+	// Extract tax rates if configured (zero defaults mean no tax impact).
+	var taxRateSTCG, taxRateLTCG, taxRateDividend, taxRateInterest float64
 	if externalConfig.Taxes != nil {
 		taxRateSTCG = externalConfig.Taxes.STCG
 		taxRateLTCG = externalConfig.Taxes.LTCG
+		taxRateDividend = externalConfig.Taxes.DividendTax
+		taxRateInterest = externalConfig.Taxes.InterestTax
 	}
 	// Parse and validate additions from non-IBKR brokers.
 	additions, additionLastPrices, err := parseAdditions(externalConfig.Additions, accountAliases)
 	if err != nil {
 		return nil, err
 	}
 	// Build realtime symbols map, defaulting to empty if not configured.
+	// Build realtime symbols map, defaulting to empty if not configured.
 	realtimeSymbols := externalConfig.RealtimeSymbols
 	if realtimeSymbols == nil {
 		realtimeSymbols = make(map[string]string)
 	}
+	// Build cash interest rates map, defaulting to empty if not configured.
+	cashInterestRates := externalConfig.InterestRates
+	if cashInterestRates == nil {
+		cashInterestRates = make(map[string]float64)
+	}
 	return &Config{
 		DirPath:            dirPath,
 		IBKRFlexQueryID:    externalConfig.FlexQueryID,
@@ -275,9 +303,12 @@ func NewConfigV1(externalConfig ExternalConfigV1, dirPath string) (*Config, erro
 		CashAdjustments:    cashAdjustments,
 		TaxRateSTCG:        taxRateSTCG,
 		TaxRateLTCG:        taxRateLTCG,
+		TaxRateDividend:    taxRateDividend,
+		TaxRateInterest:    taxRateInterest,
 		Additions:          additions,
 		AdditionLastPrices: additionLastPrices,
 		RealtimeSymbols:    realtimeSymbols,
+		CashInterestRates:  cashInterestRates,
 	}, nil
 }