bybit-analysis 0.1.5

package/README.md

@@ -0,0 +1,400 @@
+# bybit-analysis
+
+> **Repository publication rule**
+>
+> This repository previously contained API credentials in `.openclaude-profile.json` which were committed and pushed to GitHub. Even after local history cleanup, GitHub can retain old refs such as `refs/pull/*` that still expose those secrets.
+>
+> **Do not make this existing repository public.** Create a completely new public repository and clean-push only the current working tree without history.
+
+Read-only analytics CLI for Bybit accounts. Outputs schema-stable Markdown for operators and versioned JSON for automation and agent consumption.
+
+## Install
+
+### Local development
+
+```bash
+bun install
+```
+
+### Global install from npm
+
+```bash
+npm i -g bybit-analysis
+```
+
+This package uses Bun at runtime, so Bun must be installed on the machine where you run the CLI.
+
+## Run
+
+### Local source run
+
+```bash
+bun run src/index.ts <command> [options]
+```
+
+### Installed CLI
+
+```bash
+bybit-analysis <command> [options]
+```
+
+When `.env` and `.bybit-profiles.json` live in a workspace directory rather than the current shell directory, pass `--project-root <path>`.
+
+```bash
+bybit-analysis summary --project-root workspace/skills/bybit-analysis --profile main --window 30d
+```
+
+Command-specific help:
+
+```bash
+bun run src/index.ts <command> --help
+bybit-analysis <command> --help
+```
+
+## Exchange Readiness Status
+
+- Shared domain entities use extensible exchange identifiers (no hardcoded `exchange: "bybit"` contract in core types).
+- Exchange-specific DTO mapping/normalization lives under `src/services/bybit/normalizers`.
+- Composition root is provider-based via `src/services/composition/createServiceBundle.ts`.
+- Provider contract is capability-based (`supportedMarketCategories`, `supportedSourceModes`, `botData`) and exposed in `ServiceBundle`.
+- Shared request/config contracts keep provider payloads in generic `providerContext`; runtime config now carries explicit `exchangeProvider`; Bybit bot strategy IDs live under `providerContext.bybit.botStrategyIds`.
+- `botService` is optional in `ServiceBundle` and only required by providers that expose bot capability.
+- Current implementation status: only the `bybit` provider is implemented and registered.
+- This is not full multi-exchange support yet; it is a structural split so new providers can be added without rewriting shared domain models.
+
+## Exit Codes (Automation Contract)
+
+- `0` complete success (and for `health`, connectivity/auth checks passed)
+- `3` optional partial success (report generated, but only optional enrichment/data degraded)
+- `4` critical incomplete analytics (report generated, but output is not safely actionable for automation; expected spot-intrinsic unsupported exposure/risk reports stay successful)
+- `5` health-check failure (`health` command returned failed connectivity and/or auth)
+- `1` runtime failure (unexpected execution error)
+- `2` usage/config failure (invalid args or runtime validation error)
+
+Automation should branch on exit code only; no prose parsing is required.
+
+## Testing
+
+```bash
+# unit + integration suite
+bun run test
+
+# watch mode during development
+bun run test:watch
+
+# optional local coverage report
+bun run test:coverage
+
+# standard local gate (types + tests + build)
+bun run verify
+
+# release validation before tag/release
+bun run validate:local-release
+```
+
+Current suite covers production-critical paths: spot PnL normalization, pagination safety handling, secret redaction, CLI stdout/stderr contract, all report schema contracts, and CLI smoke/integration flow.
+
+## CI / release flow
+
+- CI workflow: `.github/workflows/verify.yml`
+- npm publish workflow: `.github/workflows/npm-publish.yml`
+- CI runs on pull requests, pushes to `main`, version tags `v*`, and can be started manually with `workflow_dispatch`
+- npm publish is triggered by GitHub Release `published` and validates `release.tag_name == v<package.json.version>`
+- npm publish requires `NPM_TOKEN` in the new public GitHub repository secrets
+
+### npm release steps
+
+1. Bump `package.json.version`.
+2. Commit and push changes to the new public repository.
+3. Create and push tag `v<version>`.
+4. Publish a GitHub Release from that tag.
+5. GitHub Actions publishes `bybit-analysis` to npm with the `latest` tag.
+
+## Open-source publication safety
+
+Before publishing this project publicly:
+
+1. Create a new public GitHub repository.
+2. Copy or clean-push only the current working tree.
+3. Do not migrate old git history from this private repository.
+4. Run `bun run validate:local-release` before creating the release tag.
+5. Verify `npm pack --dry-run` contains only intended package files.
+
+Do not publish local secret material such as `.env`, `.bybit-profiles.json`, `.openclaude-profile.json`, tarballs, or ad-hoc local logs.
+
+
+## Commands
+
+- `summary` - Period analytics summary (explicitly mixes period metrics with current snapshot context)
+- `balance` - Live wallet/equity/margin balances
+- `pnl` - Period PnL analysis
+- `positions` - Live open position inventory and status
+- `exposure` - Live exposure and concentration analysis
+- `performance` - Period ROI and capital efficiency analysis
+- `risk` - Live leverage and downside risk analysis
+- `bots` - Optional bot/copy-trading analytics
+- `permissions` - Live API key permission diagnostics
+- `config` - Effective runtime config (redacted)
+- `health` - Live API/connectivity/readiness checks
+
+## Markdown Schema Contracts (All Commands)
+
+All commands now expose schema-stable Markdown contracts:
+
+- Report-level `Schema: <command>-markdown-v1` is present for every command.
+- Report metadata lines are fixed and ordered: `Generated at`, `As Of` (for live snapshot reports when available), `Schema`, `Command`, `Outcome`, `Exit Code`, `Data Completeness`, `Health Status`, `Source Freshness`.
+- Every section has a fixed `id` and is rendered as `## [section.id] Title`.
+- Section order and section type are fixed per command contract.
+- Sections are never removed because of missing data; reports use deterministic placeholders (`<empty>` table rows), `N/A`, `0`, `unsupported`, or info alerts.
+- `Data Completeness` is a fixed section in every command contract:
+  - Data-backed commands render merged completeness issues in that section.
+  - Non data-backed commands (for example `config`, `health`, `permissions`) render explicit `unsupported` completeness status.
+- `Data Completeness` states are machine-classified as `complete`, `partial_optional`, `partial_critical`, `unsupported`, or `failed`.
+
+## Summary Markdown Contract (`summary-markdown-v1`)
+
+`summary` now uses a schema-stable section contract across market categories (`linear`, `spot`) and source modes (`market`, `bot`).
+
+- Section IDs are fixed and rendered in headings as `## [section.id] Title`.
+- Section order and section type are fixed.
+- Section typing is pinned by explicit section contract mapping (`id + title + type`), not inferred from payload data.
+- Missing category-specific data is represented as empty rows / zero values / info alerts, not by omitting sections.
+- `summary.alerts` is always `alerts`; if a tabular/alternative representation is needed, it must use a different section ID and title.
+- Bot enrichment failure policy:
+  - `--source market`: bot summary is optional enrichment. Failures do not abort report generation, but are surfaced explicitly in `summary.alerts` and `summary.data_completeness` with the original error reason.
+  - `--source bot`: bot summary is required input. Bot fetch failures are fail-fast and abort summary generation.
+
+Report-level metadata:
+
+- `Schema: summary-markdown-v1` line is present in output.
+
+Fixed section order:
+
+1. `summary.contract` (`text`)
+2. `summary.overview` (`kpi`)
+3. `summary.activity` (`kpi`)
+4. `summary.allocation` (`kpi`)
+5. `summary.exposure` (`kpi`)
+6. `summary.risk` (`kpi`)
+7. `summary.open_positions` (`table`)
+8. `summary.top_holdings` (`table`)
+9. `summary.symbol_pnl` (`table`)
+10. `summary.bots` (`table`)
+11. `summary.alerts` (`alerts`)
+12. `summary.data_completeness` (`alerts`)
+
+## Spot PnL Inventory Method
+
+- Cost basis method: `weighted_average`.
+- Opening inventory at `--from` is reconstructed from pre-window spot executions (lookback: last 365 days) for symbols sold inside the window.
+- If sell quantity cannot be matched to reconstructed inventory, the report is marked `dataCompleteness.state=partial_optional`, and unmatched quantity is excluded from realized PnL (no fallback to sell execution price).
+
+## PnL ROI Contract
+
+- `pnl` uses explicit ROI status: `supported` or `unsupported`.
+- ROI is `supported` only when both start and end equity are available.
+- Start equity is resolved from `account.equityHistory` using the latest sample at or before `--from`.
+- If start equity is unavailable, ROI KPI is rendered as `unsupported`, and the report includes an explicit reason in `ROI Status`.
+- In the current Bybit account snapshot flow, historical equity is not fetched from a dedicated endpoint, so ROI/capital efficiency are explicitly marked `unsupported`.
+
+Example (`pnl` section):
+
+```md
+## ROI Status
+- Status: unsupported
+- Reason: no equity sample found at or before period start
+```
+
+## Global Options
+
+- `--project-root <path>`
+- `--profile <name>`
+- `--profiles-file <path>`
+- `--exchange-provider <bybit>`
+- `--category <linear|spot>`
+- `--source <market|bot>`
+- `--fgrid-bot-ids <id1,id2,...>`
+- `--spot-grid-ids <id1,id2,...>`
+- `--format <md|compact|json>`
+- `--from <ISO8601>` period commands only: `summary`, `pnl`, `performance`, `bots`
+- `--to <ISO8601>` period commands only: `summary`, `pnl`, `performance`, `bots`
+- `--window <7d|30d|90d>` period commands only: `summary`, `pnl`, `performance`, `bots`
+- `--timeout-ms <number>`
+- `--positions-max-pages <number>`
+- `--executions-max-pages-per-chunk <number>`
+- `--pagination-limit-mode <error|partial>`
+- `--no-env`
+- `--help, -h`
+
+## Config & Environment Contract
+
+Supported env vars:
+
+- `BYBIT_API_KEY`
+- `BYBIT_SECRET`
+- `BYBIT_API_SECRET`
+- `BYBIT_ALLOW_INSECURE_CLI_SECRETS`
+- `BYBIT_DISABLE_ENV`
+- `BYBIT_PROFILE`
+- `BYBIT_PROFILES_FILE`
+- `BYBIT_EXCHANGE_PROVIDER`
+- `BYBIT_CATEGORY`
+- `BYBIT_SOURCE_MODE`
+- `BYBIT_FGRID_BOT_IDS`
+- `BYBIT_SPOT_GRID_IDS`
+- `BYBIT_FORMAT`
+- `BYBIT_TIMEOUT_MS`
+- `BYBIT_WINDOW`
+- `BYBIT_POSITIONS_MAX_PAGES`
+- `BYBIT_EXECUTIONS_MAX_PAGES_PER_CHUNK`
+- `BYBIT_PAGINATION_LIMIT_MODE`
+- `BYBIT_CONFIG_DIAGNOSTICS`
+
+Precedence rules:
+
+- General runtime fields: `CLI args -> profile (if applicable) -> env -> defaults`
+- `--project-root` changes where `.env` and the default `.bybit-profiles.json` are resolved from; absolute `--profiles-file` paths are still used as-is.
+- Exchange/provider selection is explicit via `--exchange-provider` / `BYBIT_EXCHANGE_PROVIDER` (currently only `bybit` is supported).
+- Credentials: `profile env references -> env -> legacy CLI flags (only with BYBIT_ALLOW_INSECURE_CLI_SECRETS=1) -> defaults`
+- Time range: `--from + --to -> --window -> BYBIT_WINDOW -> default 30d window`
+- Live snapshot commands reject explicit historical intent from `--from`, `--to`, `--window`, and `BYBIT_WINDOW`
+- Ambient env loading can be disabled with `--no-env` or `BYBIT_DISABLE_ENV=1`
+
+Legacy hidden aliases are intentionally removed and not supported:
+
+- `WINDOW`
+- `DEFAULT_CATEGORY`
+- `DEFAULT_FORMAT`
+- `DEFAULT_TIMEOUT_MS`
+
+CLI parsing conventions:
+
+- Value options support both `--flag value` and `--flag=value`.
+- `--` stops option parsing; everything after is treated as positional arguments.
+- Repeated scalar options use last-value-wins semantics.
+- Repeatable list options `--fgrid-bot-ids` and `--spot-grid-ids` append values in argument order.
+
+Parser strategy:
+
+- The project keeps a custom parser for now to preserve strict, predictable behavior and zero runtime dependencies.
+- Behavior is locked with table-driven tests in `src/cli/parseArgs.test.ts`.
+
+Output formats:
+
+- `md` - standard Markdown layout.
+- `compact` - lossless Markdown layout with tighter spacing (presentation-only; no row/text truncation).
+- `json` - versioned machine-readable envelope with report metadata, outcome classification, source freshness, stable sections, and structured `data`.
+
+## JSON Contract
+
+- `--format json` emits `report-json-v1`.
+- JSON includes:
+  - `jsonSchemaVersion`
+  - `reportSchemaVersion`
+  - `command`, `title`, `generatedAt`, `asOf`
+  - `outcome` (status, exit code, label, completeness class, health status)
+  - `dataCompleteness`
+  - `sources`
+  - `sections`
+  - `data` with machine-usable numeric/report payloads
+- `sources` entries expose provider/exchange context, `kind`, `fetchedAt`, optional `capturedAt`, optional `exchangeServerTime`, optional period window, and cache status when known.
+
+## Credentials (Secure Default)
+
+Recommended production paths:
+
+- Environment variables (`BYBIT_API_KEY` + `BYBIT_SECRET` or `BYBIT_API_SECRET`)
+- Explicit env-file launch, for example `bun --env-file=.env run src/index.ts ...`
+- Profile-based env references (`--profile` + `--profiles-file` with `apiKeyEnv` / `apiSecretEnv`)
+- OS secret store -> export to env before launch
+
+Example (`.env` used explicitly via `bun --env-file=.env ...`):
+
+```env
+BYBIT_API_KEY=xxx
+BYBIT_SECRET=yyy
+```
+
+Legacy path (deprecated, insecure):
+
+- `--api-key` and `--api-secret` are disabled by default because command-line secrets can leak via shell history, process listing, and command logging.
+- Temporary bypass only: set `BYBIT_ALLOW_INSECURE_CLI_SECRETS=1`.
+
+## Config Priority
+
+- General runtime fields: `CLI args -> profile (if applicable) -> env -> defaults`
+- Credentials only: `profile env references -> env -> legacy CLI flags (only with BYBIT_ALLOW_INSECURE_CLI_SECRETS=1) -> defaults`
+- Repo-local `.env` is not auto-loaded; the repository sets `bunfig.toml` with `env = false` for hermetic CLI/test runs.
+- Use `--no-env` or `BYBIT_DISABLE_ENV=1` when you need deterministic argv-only resolution even if the parent process exported `BYBIT_*` vars.
+
+## Credential Profiles
+
+Use profiles to keep non-secret runtime settings plus env variable names for each account and switch by name:
+
+```bash
+bun run src/index.ts summary --profile subaccount-a
+```
+
+Default profiles file is `./.bybit-profiles.json` (or set `BYBIT_PROFILES_FILE` / `--profiles-file`).
+
+Profiles must not contain plaintext secrets. Use `apiKeyEnv` and `apiSecretEnv` to point at exported env variable names for that profile.
+
+Example:
+
+```json
+{
+  "subaccount-a": {
+    "apiKeyEnv": "SUBACCOUNT_A_API_KEY",
+    "apiSecretEnv": "SUBACCOUNT_A_API_SECRET"
+  },
+  "subaccount-b": {
+    "apiKeyEnv": "SUBACCOUNT_B_API_KEY",
+    "apiSecretEnv": "SUBACCOUNT_B_API_SECRET",
+    "category": "linear",
+    "sourceMode": "bot",
+    "futuresGridBotIds": ["612330315406398322"]
+  }
+}
+```
+
+## Bot Mode In CLI
+
+You can run built-in reports against grid bots by setting:
+
+- `--source bot`
+- `--category linear|spot` (optional; default `linear`)
+- `--fgrid-bot-ids <id1,id2,...>` for Futures Grid bots
+- `--spot-grid-ids <id1,id2,...>` for Spot Grid bots
+
+Those bot identifiers are resolved in the Bybit adapter layer and mapped into provider request context. Provider selection is explicit via `--exchange-provider bybit` (or `BYBIT_EXCHANGE_PROVIDER=bybit`):
+
+- `providerContext.bybit.botStrategyIds.futuresGridBotIds`
+- `providerContext.bybit.botStrategyIds.spotGridBotIds`
+
+Or set bot IDs once via env:
+
+- `BYBIT_FGRID_BOT_IDS=<id1,id2,...>`
+- `BYBIT_SPOT_GRID_IDS=<id1,id2,...>`
+
+Pagination safety (optional):
+
+- `BYBIT_POSITIONS_MAX_PAGES=<number>`
+- `BYBIT_EXECUTIONS_MAX_PAGES_PER_CHUNK=<number>`
+- `BYBIT_PAGINATION_LIMIT_MODE=<error|partial>`
+
+Example:
+
+```bash
+bun run src/index.ts summary \
+  --source bot \
+  --fgrid-bot-ids 612330315406398322 \
+  --spot-grid-ids 612340768081708828
+```
+
+Permissions check:
+
+```bash
+bun run src/index.ts permissions
+```
+
+Security note: `config` and `permissions` outputs are redacted for logs/CI and do not print raw API keys, API secrets, or full IP whitelist values.

package/bin/bybit-analysis.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../dist/index.js";