feat: Add entry price support for trailing stop-loss calculations

[tinnet]

Summary

Add support for specifying entry prices directly with ticker symbols using TICKER:PRICE format (e.g., AAPL:150, SHOP.TO:200). Entry prices work exclusively with trailing mode to set a floor for high water mark calculations based on actual cost basis.

Usage

CLI:

# Entry prices with trailing mode
uv run stop-loss calculate AAPL:150 GOOGL:2800 --trailing -p 5

# Mixed format (some with entry prices, some without)
uv run stop-loss calculate AAPL:150 NVDA --trailing

Config:

tickers = [
    "AAPL:150.50",   # Entry price $150.50 sets HWM floor
    "SHOP.TO:200",   # Entry price $200 CAD sets HWM floor
    "NVDA",          # No entry price - uses database HWM only
]
trailing_enabled = true  # Required for entry prices

How It Works

Entry price sets the minimum high water mark in trailing mode:

• hwm = max(database_hwm, entry_price)
• Ensures stop never goes below your entry point
• As price rises above entry, stop trails normally from the peak
• Protects gains while respecting cost basis

Example:

• Bought AAPL at $180
• Stock went to $200 (peak), now at $195
• HWM = max($200, $180) = $200
• Stop = $200 × 0.95 = $190
• Risk = $195 - $190 = $5 per share

Why Trailing Mode Only?

Entry prices are restricted to trailing mode because:

• Simple/ATR modes calculate from current price where entry price creates confusing "risk" calculations
• When stock is UP from entry: Shows huge misleading "risk"
• When stock is DOWN: Shows negative risk or stop > current (triggers immediately)
• Trailing mode naturally protects gains from cost basis point forward—the math is intuitive and correct

Implementation Details

Built in 7 incremental commits with full test coverage:

1. ✅ Ticker parsing - parse_ticker_with_price() utility function
2. ✅ Data layer - Extended StockPrice and PriceFetcher
3. ✅ Calculator layer - Extended StopLossResult with entry_price field
4. ✅ CLI integration - Argument parsing and calculation logic
5. ✅ Display - Dynamic "Entry Price" column in results table (magenta)
6. ✅ Documentation - README and config.toml updates
7. ✅ Validation - Restrict to trailing mode with clear error messages

Testing

• All 83 tests pass ✅
• Backward compatible (plain tickers unchanged) ✅
• Validation rejects simple/ATR modes with helpful error ✅
• Entry Price column only appears when entry prices present ✅
• Mixed format works (some tickers with prices, some without) ✅

Test Plan

# 1. Entry price with trailing mode (should work)
uv run stop-loss calculate AAPL:150 --trailing -p 5 --no-history

# 2. Entry price with simple mode (should reject)
uv run stop-loss calculate AAPL:150 --simple -p 5
# Expected: Error: Entry prices only supported with trailing mode

# 3. Mixed format
uv run stop-loss calculate AAPL:150 GOOGL --trailing -p 5 --no-history

# 4. Backward compatibility (no entry prices)
uv run stop-loss calculate AAPL GOOGL --simple -p 5 --no-history

# 5. Invalid format (should error)
uv run stop-loss calculate AAPL:abc --trailing
# Expected: Error: Invalid price in 'AAPL:abc'

Breaking Changes

None - fully backward compatible.

---

🤖 Generated with Claude Code

[claude]

Code Review

Found 2 issues that need attention:

---

Issue 1: Cache Mutation Side Effect

File: src/trailing_stop_loss/fetcher.py (lines 47-52)
Severity: Bug

When using the cache with an entry_price, the code mutates the cached StockPrice object directly:

trailing-stops/src/trailing_stop_loss/fetcher.py

Lines 46 to 52 in 28ccf39

	"""
	if use_cache and ticker in self._cache:
	cached = self._cache[ticker]
	# Update entry price in cached result if provided
	if entry_price is not None:
	cached.entry_price = entry_price
	return cached

The Problem:
The cached object's entry_price field is permanently modified. If a subsequent call fetches the same ticker from cache without providing an entry price, the previously set entry price will persist unexpectedly.

Example failure scenario:

1. Call fetch_price("AAPL", use_cache=True, entry_price=150.0) - sets entry_price to 150.0 in cache
2. Call fetch_price("AAPL", use_cache=True) (no entry_price) - returns cached object with entry_price=150.0 instead of None

Suggested fix:
Instead of mutating the cached object, create a new instance with the modified entry_price:

if use_cache and ticker in self._cache:
    cached = self._cache[ticker]
    # Return a copy with updated entry price if provided
    if entry_price is not None:
        return dataclasses.replace(cached, entry_price=entry_price)
    return cached

---

Issue 2: Type Annotation Mismatch

File: src/trailing_stop_loss/fetcher.py (lines 85-86)
Severity: Type Error

The type annotation doesn't match the actual implementation:

trailing-stops/src/trailing_stop_loss/fetcher.py

Lines 84 to 87 in 28ccf39

	def fetch_multiple(
	self, tickers: list[str] | list[tuple[str, float | None]], skip_errors: bool = True
	) -> dict[str, StockPrice | Exception]:

The Problem:
The current type annotation list[str] | list[tuple[str, float | None]] indicates the parameter is either a list of all strings OR a list of all tuples. However, the implementation (lines 99-105) uses isinstance(item, tuple) to handle mixed lists containing both strings and tuples.

The test file even uses the correct type:

trailing-stops/tests/test_fetcher.py

Lines 153 to 154 in 28ccf39

	"""Test fetching with mixed format (some with entry prices, some without)."""
	tickers: list[str | tuple[str, float]] = [("AAPL", 150.0), "GOOGL", ("MSFT", 400.0)]

Impact:
Type checkers like mypy would flag passing a mixed list to this function as a type error.

Suggested fix:

def fetch_multiple(
    self, tickers: list[str | tuple[str, float | None]], skip_errors: bool = True
) -> dict[str, StockPrice | Exception]:

---

Reviewed for bugs and CLAUDE.md compliance