0xrsydn/idx-cli
1
mirror of https://github.com/0xrsydn/idx-cli.git synced 2026-11-07 01:35:36 +00:00
Code Issues Projects Releases 1 Packages Wiki Activity
idx-cli/AGENTS.md
hermes 2c85acb829 feat(ownership): import IDX above-1% XLSX holder register 
Since June 2026 IDX publishes the monthly "Pemegang Saham di Atas 1%"
list as an XLSX workbook on the Data Kepemilikan Saham page instead of
a PDF announcement. Add a parser for it and accept `.xlsx` in
`ownership import --file`.

- src/ownership/xlsx.rs: zip + quick-xml reader (shared strings incl.
  rich text, sheet cells), exact 12-column header match so the daily
  above-5% and investor-type/classification workbooks are rejected,
  Excel serial dates, numeric shares, percent -> bps with float-noise
  rounding. Builds KseiHoldingDraft directly and reuses the entity
  normalizers, so investor types stay uppercase like the PDF path.
- Fixtures: trimmed excerpts of the real 2026-08-31 above-1% and
  2026-09-23 above-5% workbooks.
- Unit + CLI tests: import, ticker, releases, above-5% rejection.
- Docs: ARCHITECTURE parser pipeline, AGENTS ownership inputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017a5Cv5Z1NzdYKgKnTiAF4E
2026-09-24 20:48:07 +00:00

3.2 KiB
Raw Blame History

AGENTS.md

Project

idx-cli is a Rust CLI for Indonesian stock market analysis and ownership workflows.

The repo currently has two main product areas:

  • stocks: live market data and analysis
  • ownership: import/sync once, then query locally from SQLite

Stack

  • Rust stable
  • clap 4 for CLI
  • ureq 3 for HTTP
  • comfy-table and owo-colors for output
  • rusqlite + bundled SQLite/FTS5 for ownership
  • TOML config in ~/.config/idx/config.toml
  • file cache in ~/.cache/idx/

Source Map

src/
├── main.rs
├── cli/
│   ├── stocks.rs
│   ├── ownership.rs
│   ├── config.rs
│   └── cache.rs
├── api/
│   ├── mod.rs
│   ├── types.rs
│   ├── yahoo/
│   └── msn/
├── analysis/
├── ownership/
│   ├── archive.rs
│   ├── db.rs
│   ├── entities.rs
│   ├── parser.rs
│   ├── remote.rs
│   ├── snapshot.rs
│   └── types.rs
├── output/
├── cache.rs
├── config.rs
└── error.rs

Provider Model

  • MSN is the primary/default provider for quotes, fundamentals, profile, earnings, financials, sentiment, insights, news, and screener data.
  • Yahoo is the fallback provider for history/OHLCV because MSN history for IDX is still not supported.
  • Current config knobs:
    • IDX_PROVIDER=msn|yahoo
    • IDX_HISTORY_PROVIDER=auto|yahoo|msn

Ownership Model

Ownership is local-first after bootstrap.

Preferred bootstrap/update path:

  1. idx ownership sync
  2. if no snapshot manifest is available: idx ownership discover then idx ownership import --url <pdf-url>
  3. local --file imports remain available for manual/fallback use

Ownership input paths:

  • primary remote source: discoverable IDX above1 holder-register PDF
  • maintained snapshot path: ownership sync
  • local file imports: IDX above-1% .xlsx (current format since June 2026), legacy .pdf, plus local archive .zip / .txt

Important scope note:

  • archive ZIP/TXT ingest is a fallback/backstop path, not the primary product ingest surface
  • ownership import --fetch-bing is still intentionally unsupported

Working Principles

  1. Keep data access provider-driven where possible; avoid adding new ad hoc fetch paths at the CLI layer.
  2. Prefer pure parse/normalize transforms over hidden state.
  3. Use fixtures in tests; do not hit live network in automated tests.
  4. Preserve the output contract: table to stdout, JSON with --output json, errors to stderr.
  5. Treat ownership schema/query compatibility as important: releases, ticker, and changes should keep working across ingest paths.

Verification

Core verification:

nix develop
cargo build
cargo clippy -- -D warnings
cargo test

Smoke tooling:

scripts/live-smoke.sh
scripts/live-smoke.sh --mode mock
scripts/live-smoke.sh --mode full

Read First

Start with these repo docs before making changes:

  • FEATURE_SPEC.md — active implementation backlog and remaining core gaps
  • TODO.md — execution tracker and smoke notes
  • docs/ARCHITECTURE.md — provider and ownership flow
  • docs/OWNERSHIP_SYNC.md — snapshot sync contract
  • docs/SMOKE.md — reusable smoke commands
  • docs/CONVENTIONS.md — repo conventions