@yigemo/choosefire 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# ChooseFIRE CLI
+
+Command-line tools for ChooseFIRE data operations.
+
+This CLI is intentionally thin: it calls approved ChooseFIRE backend endpoints and prints stable JSON for humans, scripts, and AI agents. It does not read or upload the rich local FIRE workspace.
+
+## Setup
+
+Install the public package globally, then run it with the short `choosefire` command:
+
+```bash
+npm install --global @yigemo/choosefire
+choosefire --help
+```
+
+For local development:
+
+```bash
+pnpm install
+pnpm build
+```
+
+Log in through Accounts:
+
+```bash
+choosefire auth login
+```
+
+The CLI opens your browser, completes Accounts login, receives the callback on `127.0.0.1:8787`, and stores audience-separated legacy and workspace credentials in:
+
+```bash
+~/.choosefire/config.json
+```
+
+For local backend development, only set the API base URL:
+
+```bash
+export CHOOSEFIRE_API_BASE_URL=http://localhost:3000
+```
+
+Account workspace transport and account authority remain unavailable. Keep the flag off unless the 5A4 evidence gate and enablement owner explicitly approve a controlled synthetic-account drill; real accounts and real financial data are not authorized:
+
+```bash
+export CHOOSEFIRE_ACCOUNT_WORKSPACE_ENABLED=true
+export CHOOSEFIRE_OIDC_CLIENT_ID=choosefire-cli
+choosefire auth login --json
+```
+
+## Commands
+
+```bash
+choosefire auth status --json
+choosefire auth login --json
+choosefire auth logout --json
+choosefire workspace initialize --idempotency-key <key> --json
+choosefire workspace snapshot --json
+choosefire workspace summary --json
+choosefire workspace activity --limit 50 [--cursor <cursor>] --json
+choosefire workspace fact-record --expected-version <n> --idempotency-key <key> --field household.total_assets --amount 100.5 --currency CNY [--status confirmed|estimated] [--as-of <iso>] --json
+choosefire plan list --json
+choosefire plan get <plan-id> --json
+choosefire plan update-inputs <plan-id> --annual-return 0.035 --annual-inflation 0.04 --expected-updated-at <iso> --dry-run --json
+choosefire plan duplicate <plan-id> --name "Conservative" --set annualReturn=0.035 --expected-updated-at <iso> --dry-run --json
+choosefire plan set-default <plan-id> --expected-updated-at <iso> --dry-run --json
+choosefire plan archive <plan-id> --expected-updated-at <iso> --reason "cleanup" --dry-run --json
+choosefire asset upsert --plan <plan-id> --account-id asset-bank --amount 300000 --expected-return 0.02 --expected-updated-at <iso> --dry-run --json
+choosefire asset remove --plan <plan-id> --account-id asset-bank --reason "duplicate account" --expected-updated-at <iso> --dry-run --json
+choosefire visual dataset --plan <plan-id> --kind overview --json
+```
+
+The five `workspace` operations are a narrow account HTTP facade: initialize, snapshot, summary, activity, and fact record. They use the workspace bearer only, validate every request and response against the checked-in contract, never retry mutations, and never fall back to the legacy token or local files. When a mutation outcome is unknown, first read the latest snapshot and then explicitly retry the exact serialized body with the original idempotency key to recover the receipt-first outcome. Never generate a new key for that recovery attempt. The JSON error includes this exact recovery material and action.
+
+Existing legacy plan write commands still default to dry-run unless `--apply` is passed. For CLI and MCP sources, `--expected-updated-at` should be provided to avoid overwriting newer data.
+
+## Development
+
+```bash
+pnpm dev -- plan list --json
+pnpm typecheck
+pnpm build
+pnpm test
+pnpm contract:choosefire-workspace:check
+```

package/contracts/choosefire-family-wealth/v2/capability-matrix.v1.json

@@ -0,0 +1,464 @@
+{
+  "contractId": "choosefire-family-wealth.v2",
+  "entries": [
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "household.initialize",
+      "cliPath": "household init",
+      "commandOrQuery": "workspace.initialize.v2",
+      "fixtureIds": [
+        "CFW-FIX-009"
+      ],
+      "mcpSurface": "unavailable (R1 MCP is read-only)",
+      "milestone": "R1",
+      "requiredRole": "owner",
+      "riskLevel": "L1",
+      "status": "web",
+      "storyIds": [
+        "ONBOARD-01",
+        "CHANNEL-01"
+      ],
+      "webPath": "/app"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "household.summary",
+      "cliPath": "household summary",
+      "commandOrQuery": "workspace.summary.v2",
+      "fixtureIds": [
+        "CFW-FIX-009"
+      ],
+      "mcpSurface": "choosefire://workspace/metadata",
+      "milestone": "R1",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L0",
+      "status": "parity",
+      "storyIds": [
+        "OVERVIEW-01",
+        "CHANNEL-01"
+      ],
+      "webPath": "/app"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "activity.list",
+      "cliPath": "activity list",
+      "commandOrQuery": "activity.page.v2",
+      "fixtureIds": [
+        "CFW-FIX-007",
+        "CFW-FIX-009"
+      ],
+      "mcpSurface": "unavailable (metadata advertises activity.page.v2)",
+      "milestone": "R1",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L0",
+      "status": "web",
+      "storyIds": [
+        "CHANNEL-01",
+        "SHARE-01"
+      ],
+      "webPath": "/app#activity"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "asset.account.manage",
+      "cliPath": "wealth account-create|account-update|account-archive",
+      "commandOrQuery": "asset_account.create|update|archive.v2",
+      "fixtureIds": [
+        "CFW-FIX-001",
+        "CFW-FIX-005"
+      ],
+      "mcpSurface": "unavailable (R2 MCP is read-only)",
+      "milestone": "R2",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "web",
+      "storyIds": [
+        "CAPTURE-01",
+        "ONBOARD-01"
+      ],
+      "webPath": "/app#assets"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "valuation.append",
+      "cliPath": "wealth valuation-append",
+      "commandOrQuery": "valuation_snapshot.append.v2",
+      "fixtureIds": [
+        "CFW-FIX-001",
+        "CFW-FIX-002"
+      ],
+      "mcpSurface": "unavailable (R2 MCP is read-only)",
+      "milestone": "R2",
+      "requiredRole": "owner",
+      "riskLevel": "L1",
+      "status": "web",
+      "storyIds": [
+        "CAPTURE-01",
+        "TRACK-01"
+      ],
+      "webPath": "/app#assets"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "classification.replace",
+      "cliPath": "wealth classify",
+      "commandOrQuery": "classification.replace.v2",
+      "fixtureIds": [
+        "CFW-FIX-005"
+      ],
+      "mcpSurface": "unavailable (R2 MCP is read-only)",
+      "milestone": "R2",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "web",
+      "storyIds": [
+        "CAPTURE-01",
+        "OVERVIEW-01"
+      ],
+      "webPath": "/app#assets"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "purpose.manage",
+      "cliPath": "purpose create|allocate",
+      "commandOrQuery": "purpose_bucket.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-005"
+      ],
+      "mcpSurface": "choosefire.purpose.*",
+      "milestone": "R5",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "GOAL-01",
+        "OVERVIEW-01"
+      ],
+      "webPath": "/app/plan"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "overview.read",
+      "cliPath": "wealth overview",
+      "commandOrQuery": "workspace.overview.v2",
+      "fixtureIds": [
+        "CFW-FIX-005",
+        "CFW-FIX-007",
+        "CFW-FIX-009"
+      ],
+      "mcpSurface": "choosefire://workspace/overview|portfolio-tree|data-quality",
+      "milestone": "R2",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L0",
+      "status": "parity",
+      "storyIds": [
+        "OVERVIEW-01",
+        "CHANNEL-01"
+      ],
+      "webPath": "/app"
+    },
+    {
+      "builtinAi": "apply_with_confirmation",
+      "capabilityId": "holding.manage",
+      "cliPath": "holding create|update|archive",
+      "commandOrQuery": "holding.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-003"
+      ],
+      "mcpSurface": "choosefire.holding.*",
+      "milestone": "R3",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "CAPTURE-01"
+      ],
+      "webPath": "/app/assets/:id"
+    },
+    {
+      "builtinAi": "apply_with_confirmation",
+      "capabilityId": "transaction.record",
+      "cliPath": "transaction record",
+      "commandOrQuery": "transaction.record.v2",
+      "fixtureIds": [
+        "CFW-FIX-003"
+      ],
+      "mcpSurface": "choosefire.transaction.record",
+      "milestone": "R3",
+      "requiredRole": "owner",
+      "riskLevel": "L1",
+      "status": "absent",
+      "storyIds": [
+        "CAPTURE-01",
+        "TRACK-01"
+      ],
+      "webPath": "/app/assets/:id"
+    },
+    {
+      "builtinAi": "apply_with_confirmation",
+      "capabilityId": "cash_flow.record",
+      "cliPath": "transaction cash-flow",
+      "commandOrQuery": "external_cash_flow.record.v2",
+      "fixtureIds": [
+        "CFW-FIX-002"
+      ],
+      "mcpSurface": "choosefire.cashFlow.record",
+      "milestone": "R3",
+      "requiredRole": "owner",
+      "riskLevel": "L1",
+      "status": "absent",
+      "storyIds": [
+        "CAPTURE-01",
+        "PERFORMANCE-01"
+      ],
+      "webPath": "/app/assets/:id"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "import.apply",
+      "cliPath": "import inspect|preview|submit|apply",
+      "commandOrQuery": "import_batch.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-008"
+      ],
+      "mcpSurface": "choosefire.import.*",
+      "milestone": "R3",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "IMPORT-01",
+        "ONBOARD-01"
+      ],
+      "webPath": "/app/import"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "ai.capture",
+      "cliPath": "candidate list|decide",
+      "commandOrQuery": "capture_candidate.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-009"
+      ],
+      "mcpSurface": "choosefire.capture.propose",
+      "milestone": "R3",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "AI-01",
+        "ONBOARD-01"
+      ],
+      "webPath": "/app/ai"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "performance.read",
+      "cliPath": "performance show",
+      "commandOrQuery": "performance.period.v2",
+      "fixtureIds": [
+        "CFW-FIX-001",
+        "CFW-FIX-002",
+        "CFW-FIX-003",
+        "CFW-FIX-004"
+      ],
+      "mcpSurface": "choosefire.performance.get",
+      "milestone": "R4",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L0",
+      "status": "absent",
+      "storyIds": [
+        "PERFORMANCE-01",
+        "TRACK-01"
+      ],
+      "webPath": "/app/performance"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "performance.gaps",
+      "cliPath": "performance gaps",
+      "commandOrQuery": "performance.gaps.v2",
+      "fixtureIds": [
+        "CFW-FIX-002",
+        "CFW-FIX-003"
+      ],
+      "mcpSurface": "choosefire://performance/gaps",
+      "milestone": "R4",
+      "requiredRole": "owner",
+      "riskLevel": "L0",
+      "status": "absent",
+      "storyIds": [
+        "PERFORMANCE-01"
+      ],
+      "webPath": "/app/performance"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "goal.manage",
+      "cliPath": "goal create|update|retire",
+      "commandOrQuery": "financial_goal.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-006"
+      ],
+      "mcpSurface": "choosefire.goal.*",
+      "milestone": "R5",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "GOAL-01"
+      ],
+      "webPath": "/app/plan"
+    },
+    {
+      "builtinAi": "read",
+      "capabilityId": "scenario.compare",
+      "cliPath": "plan scenario compare",
+      "commandOrQuery": "plan.compare.v2",
+      "fixtureIds": [
+        "CFW-FIX-006"
+      ],
+      "mcpSurface": "choosefire.plan.compare",
+      "milestone": "R5",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L0",
+      "status": "absent",
+      "storyIds": [
+        "PLAN-01"
+      ],
+      "webPath": "/app/plan/scenarios"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "plan.confirm",
+      "cliPath": "plan scenario confirm",
+      "commandOrQuery": "wealth_plan.confirm.v2",
+      "fixtureIds": [
+        "CFW-FIX-006"
+      ],
+      "mcpSurface": "choosefire.plan.confirm",
+      "milestone": "R5",
+      "requiredRole": "owner",
+      "riskLevel": "L3",
+      "status": "absent",
+      "storyIds": [
+        "PLAN-01",
+        "TRACK-01"
+      ],
+      "webPath": "/app/plan"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "research.run",
+      "cliPath": "research start|refresh",
+      "commandOrQuery": "research_run.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-006"
+      ],
+      "mcpSurface": "choosefire.research.*",
+      "milestone": "R6",
+      "requiredRole": "owner",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "RESEARCH-01"
+      ],
+      "webPath": "/app/plan/research"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "proposal.review",
+      "cliPath": "proposal decide|confirm",
+      "commandOrQuery": "allocation_proposal.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-006"
+      ],
+      "mcpSurface": "choosefire.proposal.*",
+      "milestone": "R6",
+      "requiredRole": "owner",
+      "riskLevel": "L3",
+      "status": "absent",
+      "storyIds": [
+        "PROPOSAL-01"
+      ],
+      "webPath": "/app/plan/proposals/:id"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "household.invite",
+      "cliPath": "household invite|remove",
+      "commandOrQuery": "household_invite.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-007"
+      ],
+      "mcpSurface": "choosefire.household.*",
+      "milestone": "R7",
+      "requiredRole": "owner",
+      "riskLevel": "L3",
+      "status": "absent",
+      "storyIds": [
+        "SHARE-01"
+      ],
+      "webPath": "/app/household"
+    },
+    {
+      "builtinAi": "propose",
+      "capabilityId": "suggestion.manage",
+      "cliPath": "suggestion submit|decide",
+      "commandOrQuery": "member_suggestion.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-007"
+      ],
+      "mcpSurface": "choosefire.suggestion.*",
+      "milestone": "R7",
+      "requiredRole": "owner_or_viewer",
+      "riskLevel": "L2",
+      "status": "absent",
+      "storyIds": [
+        "SHARE-01"
+      ],
+      "webPath": "/app/pending"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "review.complete",
+      "cliPath": "review prepare|complete",
+      "commandOrQuery": "review.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-001",
+        "CFW-FIX-002",
+        "CFW-FIX-003"
+      ],
+      "mcpSurface": "choosefire.review.*",
+      "milestone": "R8",
+      "requiredRole": "owner",
+      "riskLevel": "L3",
+      "status": "absent",
+      "storyIds": [
+        "REVIEW-01"
+      ],
+      "webPath": "/app/reviews"
+    },
+    {
+      "builtinAi": "unavailable",
+      "capabilityId": "legacy.migrate",
+      "cliPath": "migration preview|activate",
+      "commandOrQuery": "legacy_migration.commands.v2",
+      "fixtureIds": [
+        "CFW-FIX-010"
+      ],
+      "mcpSurface": "choosefire.migration.*",
+      "milestone": "R8",
+      "requiredRole": "owner",
+      "riskLevel": "L3",
+      "status": "absent",
+      "storyIds": [
+        "IMPORT-01",
+        "CHANNEL-01"
+      ],
+      "webPath": "/app/import/migration"
+    }
+  ],
+  "kind": "choosefire_family_wealth_capability_matrix.v1"
+}

package/contracts/choosefire-family-wealth/v2/golden/performance.v1.json

@@ -0,0 +1,79 @@
+{
+  "calculationVersion": "performance.v1",
+  "cases": [
+    {
+      "caseId": "PERF-L1-001",
+      "expected": {
+        "balanceChange": "30000.00",
+        "estimatedProfit": null,
+        "level": "balance_change",
+        "moneyWeightedReturn": null,
+        "qualifiers": [
+          "not_investment_return"
+        ]
+      },
+      "fixtureId": "CFW-FIX-001",
+      "input": {
+        "beginningValue": "500000.00",
+        "endingValue": "530000.00",
+        "externalCashFlows": null
+      }
+    },
+    {
+      "caseId": "PERF-L2-001",
+      "expected": {
+        "assumptions": [
+          "midpoint_cashflow_assumption"
+        ],
+        "balanceChange": "15000.00",
+        "dietzDenominator": "105000.00",
+        "estimatedProfit": "5000.00",
+        "level": "estimated_return",
+        "moneyWeightedReturn": "0.047619047619"
+      },
+      "fixtureId": "CFW-FIX-002",
+      "input": {
+        "beginningValue": "100000.00",
+        "endingValue": "115000.00",
+        "externalCashFlows": [
+          {
+            "amount": "10000.00",
+            "weight": "0.50000000"
+          }
+        ]
+      }
+    },
+    {
+      "caseId": "PERF-L3-COVERAGE-001",
+      "expectedCoverage": {
+        "assumptions": [],
+        "calculationVersion": "performance.v1",
+        "eligibleMetrics": [
+          "money_weighted_return"
+        ],
+        "level": "detailed_performance",
+        "unavailableMetrics": [
+          {
+            "metric": "time_weighted_return",
+            "reason": "boundary_valuation_missing"
+          }
+        ],
+        "warnings": [
+          "r0_contract_only"
+        ]
+      },
+      "expectedResult": null,
+      "fixtureId": "CFW-FIX-003",
+      "input": {
+        "missingEvidence": [
+          "external_flow_boundary_valuation"
+        ],
+        "requestedMetrics": [
+          "money_weighted_return",
+          "time_weighted_return"
+        ]
+      }
+    }
+  ],
+  "kind": "choosefire_performance_golden_fixtures.v1"
+}