@retiregolden/planner-ui 0.1.0

package/src/data/fedInvestClient.ts

@@ -0,0 +1,113 @@
+/**
+ * FedInvest live TIPS prices — the IO half: the ONLY network touch in the
+ * app, and it is strictly opt-in. The pure parsing/date/matching half lives
+ * in the engine package (`@retiregolden/engine/ladder/fedInvest`); this
+ * module owns the fetch and the per-day cache, keeping the engine free of
+ * browser globals.
+ *
+ * Privacy posture:
+ *  - Nothing runs without an explicit button press; there is no background
+ *    refresh, no fetch on page load, and the embedded real-yield curve always
+ *    remains the planning source of truth (offline-first).
+ *  - The request goes directly to the U.S. Treasury's FedInvest service and
+ *    carries only a price date — never any plan data.
+ *  - Responses are cached per day in localStorage (`retiregolden.fedinvest.v1`),
+ *    so repeat looks are served offline; "Clear all data" removes the cache.
+ *  - FedInvest does not currently send CORS headers, so the direct fetch can
+ *    be blocked by the browser. The UI degrades to a manual import of the
+ *    same `securityprice.csv` the FedInvest site downloads — zero network
+ *    from the app, same data, same cache.
+ */
+
+import {
+  FEDINVEST_CSV_URL,
+  latestPriceDate,
+  latestPriceDateIso,
+  parseFedInvestCsv,
+  type FedInvestSnapshot,
+} from '@retiregolden/engine/ladder/fedInvest'
+
+import { STORAGE_KEYS, readLocal, writeLocal } from './localStore'
+
+export function readFedInvestCache(): FedInvestSnapshot | null {
+  const raw = readLocal(STORAGE_KEYS.fedInvestCache)
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as FedInvestSnapshot
+    if (!Array.isArray(parsed.tips)) return null
+    if (typeof parsed.priceDateIso !== 'string' && parsed.priceDateIso !== null) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function cacheSnapshot(snapshot: FedInvestSnapshot): void {
+  writeLocal(STORAGE_KEYS.fedInvestCache, JSON.stringify(snapshot))
+}
+
+/**
+ * Fetch (cache-first) the TIPS price list for the latest business day. Only
+ * ever called from an explicit user action. Throws a readable Error when the
+ * network, CORS policy, or parse fails — the caller shows it (offering the
+ * manual CSV import) and the app carries on with the embedded curve.
+ */
+export async function fetchFedInvestTips(now = new Date()): Promise<FedInvestSnapshot> {
+  const date = latestPriceDate(now)
+  const priceDateIso = latestPriceDateIso(now)
+  const cached = readFedInvestCache()
+  // Only a same-day FETCHED snapshot satisfies a fetch request: an imported
+  // file has no known price date, so it must never suppress a real refresh.
+  if (cached && cached.source === 'fetch' && cached.priceDateIso === priceDateIso) return cached
+
+  const body = new URLSearchParams({
+    priceDateDay: String(date.getDate()),
+    priceDateMonth: String(date.getMonth() + 1),
+    priceDateYear: String(date.getFullYear()),
+    fileType: 'csv',
+    csv: 'CSV FORMAT',
+  })
+  let response: Response
+  try {
+    response = await fetch(FEDINVEST_CSV_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    })
+  } catch {
+    throw new Error('Could not reach the Treasury FedInvest service (blocked or offline).')
+  }
+  if (!response.ok) {
+    throw new Error(`The Treasury FedInvest service answered ${response.status}; try again later.`)
+  }
+  const tips = parseFedInvestCsv(await response.text())
+  if (tips.length === 0) {
+    throw new Error('FedInvest returned no TIPS rows for the latest business day (a holiday, or the format changed).')
+  }
+  const snapshot: FedInvestSnapshot = { priceDateIso, fetchedAtIso: new Date().toISOString(), source: 'fetch', tips }
+  cacheSnapshot(snapshot)
+  return snapshot
+}
+
+/**
+ * Manual fallback with zero network from the app: the user downloads
+ * `securityprice.csv` from the FedInvest site themselves and hands the file
+ * content here. The CSV carries no date, so the snapshot's priceDateIso stays
+ * null (unknown) rather than guessing — and an import never counts as "fresh"
+ * for the fetch cache. Throws a readable Error when the file isn't a
+ * FedInvest CSV.
+ */
+export function importFedInvestCsv(text: string): FedInvestSnapshot {
+  const tips = parseFedInvestCsv(text)
+  if (tips.length === 0) {
+    throw new Error("That file doesn't look like a FedInvest securityprice.csv (no TIPS rows found).")
+  }
+  const snapshot: FedInvestSnapshot = {
+    priceDateIso: null,
+    fetchedAtIso: new Date().toISOString(),
+    source: 'import',
+    tips,
+  }
+  cacheSnapshot(snapshot)
+  return snapshot
+}

package/src/data/localStore.ts

@@ -0,0 +1,42 @@
+/**
+ * Guarded localStorage access plus the central registry of `retiregolden.*`
+ * keys. localStorage can throw (private browsing, quota, disabled storage);
+ * reads fall back to null and writes/removes fail silently — IndexedDB is the
+ * durable store, these are per-device conveniences. "Clear all data" removes
+ * every key with the `retiregolden.` prefix, so new keys must keep it.
+ */
+
+export const STORAGE_KEYS = {
+  theme: 'retiregolden.theme',
+  homeWelcomeDismissed: 'retiregolden.home.welcomeDismissed',
+  insightsDismissed: 'retiregolden.insights.dismissed',
+  examplesExpanded: 'retiregolden.examples.expanded',
+  longevity: 'retiregolden.longevity.v1',
+  longevityPartner: 'retiregolden.longevity.partner.v1',
+  socialSecurityForm: 'retiregolden.ss.v1',
+  fedInvestCache: 'retiregolden.fedinvest.v1',
+} as const
+
+export function readLocal(key: string): string | null {
+  try {
+    return localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+export function writeLocal(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value)
+  } catch {
+    /* storage unavailable — the visible state still applies this session */
+  }
+}
+
+export function removeLocal(key: string): void {
+  try {
+    localStorage.removeItem(key)
+  } catch {
+    /* storage unavailable */
+  }
+}

package/src/data/planOrigin.ts

@@ -0,0 +1,24 @@
+/** Shared provenance helpers — raw IndexedDB records skip Zod defaults. */
+
+export const EXAMPLE_PLAN_ID_PREFIX = 'example:'
+
+export function isExamplePlanId(id: string): boolean {
+  return id.startsWith(EXAMPLE_PLAN_ID_PREFIX)
+}
+
+export function exampleStorageId(exampleId: string): string {
+  return `${EXAMPLE_PLAN_ID_PREFIX}${exampleId}`
+}
+
+/** Exclude only explicit demos; missing `origin` is treated as a user plan. */
+export function isUserPlan(raw: Record<string, unknown>): boolean {
+  return raw['origin'] !== 'example'
+}
+
+export function isExamplePlan(raw: Record<string, unknown>): boolean {
+  return raw['origin'] === 'example'
+}
+
+export function planOriginFromRaw(raw: Record<string, unknown>): 'user' | 'example' {
+  return raw['origin'] === 'example' ? 'example' : 'user'
+}

package/src/data/planStore.ts

@@ -0,0 +1,165 @@
+/**
+ * IndexedDB persistence for v2 plans. Replaces v1's localStorage approach —
+ * plans (earnings histories, scenarios, cached results later) outgrow the
+ * ~5 MB synchronous localStorage budget. Every read passes through schema
+ * migration + validation; corrupt records are surfaced, never silently used.
+ */
+
+import { openDB, type IDBPDatabase } from 'idb'
+
+import { isUserPlan, planOriginFromRaw } from './planOrigin'
+import { migratePlanToCurrent, type MigrateResult } from '@retiregolden/engine/model/migrations'
+import { parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+
+const DB_NAME = 'retiregolden.v2'
+const DB_VERSION = 1
+const PLANS_STORE = 'plans'
+
+let dbPromise: Promise<IDBPDatabase> | null = null
+
+function db(): Promise<IDBPDatabase> {
+  dbPromise ??= openDB(DB_NAME, DB_VERSION, {
+    upgrade(database) {
+      if (!database.objectStoreNames.contains(PLANS_STORE)) {
+        database.createObjectStore(PLANS_STORE, { keyPath: 'id' })
+      }
+    },
+  })
+  return dbPromise
+}
+
+/** Test hook: drop the cached connection so fake-indexeddb resets take effect. */
+export function _resetPlanStoreForTests(): void {
+  dbPromise = null
+}
+
+export interface PlanSummary {
+  id: string
+  name: string
+  updatedAtIso: string
+  origin: 'user' | 'example'
+}
+
+function toSummary(raw: Record<string, unknown>): PlanSummary | null {
+  const id = String(raw['id'] ?? '')
+  if (id === '') return null
+  return {
+    id,
+    name: String(raw['name'] ?? '(unnamed)'),
+    updatedAtIso: String(raw['updatedAtIso'] ?? ''),
+    origin: planOriginFromRaw(raw),
+  }
+}
+
+async function summariesWhere(predicate: (raw: Record<string, unknown>) => boolean): Promise<PlanSummary[]> {
+  const all = (await (await db()).getAll(PLANS_STORE)) as Array<Record<string, unknown>>
+  return all
+    .filter(predicate)
+    .map(toSummary)
+    .filter((s): s is PlanSummary => s !== null)
+    .sort((a, b) => b.updatedAtIso.localeCompare(a.updatedAtIso))
+}
+
+/** All stored plans, including library demos. Prefer the filtered helpers for UI. */
+export async function listPlanSummaries(): Promise<PlanSummary[]> {
+  return summariesWhere(() => true)
+}
+
+export async function listUserPlanSummaries(): Promise<PlanSummary[]> {
+  return summariesWhere(isUserPlan)
+}
+
+export async function listExampleSummaries(): Promise<PlanSummary[]> {
+  return summariesWhere((raw) => !isUserPlan(raw))
+}
+
+/** Loads, migrates, and validates a stored plan. */
+export async function loadPlan(id: string): Promise<MigrateResult> {
+  const raw = (await (await db()).get(PLANS_STORE, id)) as unknown
+  if (raw === undefined) return { ok: false, reason: 'not_object' }
+  return migratePlanToCurrent(raw)
+}
+
+export type SavePlanResult = { ok: true; plan: Plan } | { ok: false; issues: string[] }
+
+/** Validates and writes a plan, bumping `updatedAtIso`. */
+export async function savePlan(plan: Plan, now: () => Date = () => new Date()): Promise<SavePlanResult> {
+  const stamped: Plan = { ...plan, updatedAtIso: now().toISOString() }
+  const checked = parsePlan(stamped)
+  if (!checked.ok) return { ok: false, issues: checked.issues }
+  await (await db()).put(PLANS_STORE, checked.plan)
+  return { ok: true, plan: checked.plan }
+}
+
+export interface DuplicatePlanOptions {
+  name?: string
+  newId?: () => string
+  now?: () => Date
+  /**
+   * Clone this in-memory plan instead of reloading the stored copy. The open
+   * workspace passes its live (possibly just-edited, not-yet-autosaved) plan so
+   * a duplicate doesn't silently drop unsaved changes.
+   */
+  source?: Plan
+}
+
+export async function duplicatePlan(id: string, opts: DuplicatePlanOptions = {}): Promise<SavePlanResult> {
+  let source = opts.source
+  if (!source) {
+    const loaded = await loadPlan(id)
+    if (!loaded.ok) return { ok: false, issues: [`Could not load source plan (${loaded.reason}).`] }
+    source = loaded.plan
+  }
+  const now = opts.now ?? (() => new Date())
+  const nowIso = now().toISOString()
+  const clone: Plan = structuredClone(source)
+  clone.id = (opts.newId ?? (() => crypto.randomUUID()))()
+  clone.name = opts.name?.trim() || `Copy of ${source.name}`
+  clone.origin = 'user'
+  clone.exampleSourceId = source.exampleSourceId
+  clone.createdAtIso = nowIso
+  clone.updatedAtIso = nowIso
+  return savePlan(clone, () => new Date(nowIso))
+}
+
+/**
+ * Atomically converts a library demo to a user plan: delete the reserved
+ * `example:*` record and put the converted plan under a fresh id.
+ */
+export async function convertExampleToUserPlan(
+  plan: Plan,
+  opts: { newId?: () => string; now?: () => Date } = {},
+): Promise<SavePlanResult> {
+  const newId = (opts.newId ?? (() => crypto.randomUUID()))()
+  const now = opts.now ?? (() => new Date())
+  const nowIso = now().toISOString()
+  const converted: Plan = {
+    ...plan,
+    id: newId,
+    origin: 'user',
+    exampleSourceId: plan.exampleSourceId ?? plan.id.replace(/^example:/, ''),
+    updatedAtIso: nowIso,
+  }
+  const checked = parsePlan(converted)
+  if (!checked.ok) return { ok: false, issues: checked.issues }
+
+  const database = await db()
+  const tx = database.transaction(PLANS_STORE, 'readwrite')
+  await tx.store.delete(plan.id)
+  await tx.store.put(checked.plan)
+  await tx.done
+  return { ok: true, plan: checked.plan }
+}
+
+export async function deletePlan(id: string): Promise<void> {
+  await (await db()).delete(PLANS_STORE, id)
+}
+
+export async function clearAllPlans(): Promise<void> {
+  await (await db()).clear(PLANS_STORE)
+}
+
+/** Raw record count — includes library demos. */
+export async function countStoredPlans(): Promise<number> {
+  return (await (await db()).count(PLANS_STORE))
+}

package/src/data/v2Backup.ts

@@ -0,0 +1,101 @@
+/**
+ * v2 JSON backup envelope — ports the retired v1 pattern (versioned envelope,
+ * size cap, validate-before-replace) to multi-plan v2 data.
+ * Plans inside the envelope carry their own schemaVersion and are individually
+ * migrated on import, so old backups stay restorable forever.
+ */
+
+import { migratePlanToCurrent } from '@retiregolden/engine/model/migrations'
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { isExamplePlanId } from './planOrigin'
+import { listPlanSummaries } from './planStore'
+
+export const V2_BACKUP_KIND = 'retiregolden.v2.backup'
+/** Legacy envelope kinds from before the RetireGolden rebrand — still accepted on import. */
+export const LEGACY_V2_BACKUP_KIND = 'retirecalc.v2.backup'
+export const RETIREMINT_V2_BACKUP_KIND = 'retiremint.v2.backup'
+export const V2_BACKUP_VERSION = 1
+/** Generous cap; primarily guards against importing the wrong (huge) file. */
+export const MAX_BACKUP_JSON_CHARS = 10_000_000
+
+export interface V2BackupEnvelope {
+  kind: typeof V2_BACKUP_KIND
+  backupVersion: typeof V2_BACKUP_VERSION
+  exportedAtIso: string
+  plans: unknown[]
+}
+
+export function serializeV2Backup(plans: Plan[], now: () => Date = () => new Date()): string {
+  const envelope: V2BackupEnvelope = {
+    kind: V2_BACKUP_KIND,
+    backupVersion: V2_BACKUP_VERSION,
+    exportedAtIso: now().toISOString(),
+    plans,
+  }
+  return JSON.stringify(envelope, null, 2)
+}
+
+export type ParseV2BackupResult =
+  | { ok: true; plans: Plan[]; warnings: string[] }
+  | { ok: false; reason: 'too_large' | 'not_json' | 'wrong_kind' | 'unsupported_version' | 'no_valid_plans' }
+
+export function parseV2Backup(json: string): ParseV2BackupResult {
+  if (json.length > MAX_BACKUP_JSON_CHARS) return { ok: false, reason: 'too_large' }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(json)
+  } catch {
+    return { ok: false, reason: 'not_json' }
+  }
+  if (typeof raw !== 'object' || raw === null) return { ok: false, reason: 'wrong_kind' }
+  const env = raw as { kind?: string; backupVersion?: number; plans?: unknown }
+  if (
+    (env.kind !== V2_BACKUP_KIND &&
+      env.kind !== RETIREMINT_V2_BACKUP_KIND &&
+      env.kind !== LEGACY_V2_BACKUP_KIND) ||
+    !Array.isArray(env.plans)
+  ) {
+    return { ok: false, reason: 'wrong_kind' }
+  }
+  if (env.backupVersion !== V2_BACKUP_VERSION) return { ok: false, reason: 'unsupported_version' }
+
+  const plans: Plan[] = []
+  const warnings: string[] = []
+  env.plans.forEach((rawPlan, i) => {
+    const result = migratePlanToCurrent(rawPlan)
+    if (result.ok) {
+      plans.push(result.plan)
+    } else {
+      warnings.push(`plan ${i + 1}: skipped (${result.reason})`)
+    }
+  })
+  if (plans.length === 0) return { ok: false, reason: 'no_valid_plans' }
+  return { ok: true, plans, warnings }
+}
+
+/**
+ * On import, demos become user plans and reserved `example:*` ids are rekeyed
+ * so they cannot collide with library demo slots.
+ */
+export async function normalizePlansForImport(plans: Plan[]): Promise<Plan[]> {
+  const existing = new Set((await listPlanSummaries()).map((s) => s.id))
+  const used = new Set(existing)
+  const normalized: Plan[] = []
+
+  for (const plan of plans) {
+    let id = plan.id
+    if (plan.origin === 'example' || isExamplePlanId(id) || used.has(id)) {
+      do {
+        id = crypto.randomUUID()
+      } while (used.has(id))
+    }
+    used.add(id)
+    normalized.push({
+      ...plan,
+      id,
+      origin: 'user',
+    })
+  }
+  return normalized
+}