From 3299093e1899abb5d08c44920fbdc9a898e3d06c Mon Sep 17 00:00:00 2001 From: hermes Date: Fri, 25 Sep 2026 23:39:25 +0000 Subject: [PATCH] docs: refresh README for v0.2.4 - Install: add npm/npx (with the pnpm/bun opt-in), platform coverage, pin example v0.2.4; Cargo builds from source. - Runtime helpers as a table, corrected: curl-impersonate is needed for IDX ownership discover/import and Yahoo fundamentals (IDX_PROVIDER=yahoo), not for stocks history; mutool only for legacy PDF reports. Everyday use needs neither. - Quick start and Features now cover ownership (sync, ticker, entity, search, changes, concentration, cross-holders, graph; XLSX source on the IDX Data Kepemilikan Saham page) and the full stocks command set and providers. Every example was run against v0.2.4. - Documentation index; script test suites. - docs: example versions -> v0.2.4; npm publish needs 2FA and a fresh version number. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017a5Cv5Z1NzdYKgKnTiAF4E --- README.md | 108 ++++++++++++++++++++++++++++++++------- docs/INSTALL.md | 2 +- docs/NPM_DISTRIBUTION.md | 9 ++-- 3 files changed, 96 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 27d7d75..357cddd 100644 --- a/README.md +++ b/README.md @@ -13,22 +13,23 @@ curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | s Downloads the prebuilt `idx` binary for your platform from GitHub Releases, verifies it against the release `SHA256SUMS`, and installs it into `~/.local/bin` without sudo. Pin a version or change the directory with -`sh -s -- --version v0.2.3 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md). +`sh -s -- --version v0.2.4 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md). -### Cargo +### npm / npx ```bash -cargo install idx-cli +npx idx-cli --help # run without installing +npm install --global idx-cli ``` -This installs the `idx` binary. `idx-cli` currently requires Rust `1.85+`. +The npm package downloads the same checksum-verified release binary during +`postinstall`. pnpm 10+ and bun skip install scripts by default; allow them +with `pnpm add --global --allow-build=idx-cli idx-cli` or +`bun add --global --trust idx-cli`. See +[docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md). -If you use the install script or the Cargo install path directly, some commands also require helper tools at runtime: - -- Yahoo-authenticated flows require a `curl_chrome*` binary from `curl-impersonate-chrome` in `PATH`, or `IDX_CURL_IMPERSONATE_BIN` pointing at that binary. -- Ownership PDF import requires `mutool` from MuPDF in `PATH`. - -Install those helpers with your OS package manager, or use the Nix app/package below so they are wrapped automatically. +Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64. +On Windows, use WSL. ### Nix @@ -37,26 +38,81 @@ nix run github:0xrsydn/idx-cli -- version nix profile install github:0xrsydn/idx-cli#default ``` -The Nix app wraps `idx` with `curl-impersonate` and `mupdf`, so the Yahoo auth and ownership PDF helper tools are available automatically. +The Nix package wraps `idx` with `curl-impersonate` and `mupdf`, so every +helper tool below is available automatically. + +### Cargo + +```bash +cargo install idx-cli +``` + +Builds from source; requires Rust `1.85+`. + +### Runtime helper tools + +The install script, npm, and Cargo installs ship only the `idx` binary. A few +commands call external tools: + +| Tool | Needed for | +| --- | --- | +| `curl_chrome*` / `curl_firefox*` from [curl-impersonate](https://github.com/lexiforest/curl-impersonate) (or `IDX_CURL_IMPERSONATE_BIN`) | `ownership discover` / `import --url` from IDX (behind Cloudflare), and Yahoo fundamentals when `IDX_PROVIDER=yahoo` | +| `mutool` from MuPDF | importing legacy PDF ownership reports only | + +Everyday use (`stocks` with the default MSN provider, including history, +`ownership sync`, and every local ownership query) needs neither. ## Quick start ```bash +# Stocks idx stocks quote BBCA idx stocks quote BBCA,BBRI,BMRI -idx -o json stocks quote BBCA idx stocks history BBCA --period 3mo -idx config init -idx cache info -idx --offline stocks quote BBCA +idx stocks technical BBCA +idx stocks fundamental BBCA +idx stocks compare BBCA BBRI BMRI +idx -o json stocks quote BBCA + +# Ownership: download the maintained snapshot once, then query locally +idx ownership sync +idx ownership ticker BBCA +idx ownership entity "ANTHONI SALIM" +idx ownership search salim +idx ownership changes --from 2026-07-31 --to 2026-08-31 ``` ## Features -- Provider abstraction (swap data sources behind one interface) -- Local file cache with TTL -- Offline mode with stale-cache fallback -- Human table output and machine-friendly JSON output +### Stocks + +- Quotes, OHLC history, company profile, financial statements, earnings, + news, crowd sentiment, and AI insights +- Analysis: `technical`, `growth`, `valuation`, `risk`, and a combined + `fundamental` report; multi-symbol `compare`; MSN `screen`er +- Providers: MSN is the default for quotes, fundamentals, and screening; + Yahoo serves history. Switch with `IDX_PROVIDER=msn|yahoo` and + `IDX_HISTORY_PROVIDER=auto|yahoo|msn` +- Local file cache with TTL, and `--offline` mode with stale-cache fallback + +### Ownership (KSEI shareholders above 1%) + +- Source: the monthly KSEI holder register ("Pemegang Saham di Atas 1%") + published by IDX. Since June 2026 it is an XLSX file on IDX's + [Data Kepemilikan Saham](https://www.idx.co.id/id/perusahaan-tercatat/data-kepemilikan-saham/) + page; earlier months were PDF announcements +- `ownership sync` installs a maintained SQLite snapshot (checked daily, + currently the latest three months), after which every query runs offline +- Queries: holders per `ticker`, holdings per `entity`, entity `search`, + month-over-month `changes`, `concentration`, `cross-holders`, and an + ownership `graph` +- Self-serve ingest: `ownership discover` finds the latest reports, and + `ownership import --url ` / `--file` loads them into your + local database. See [docs/OWNERSHIP_SYNC.md](docs/OWNERSHIP_SYNC.md) + +### Output + +- Human-readable tables on stdout, JSON with `-o json`, errors on stderr ## Configuration @@ -81,6 +137,17 @@ Precedence order: - Use `idx --help` and subcommand help for discoverability - Use `-o json` / `--output json` for structured output +- `idx completions ` generates shell completions + +## Documentation + +- [docs/INSTALL.md](docs/INSTALL.md): install script options +- [docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md): npm package and release flow +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): providers, ownership ingest, and discovery +- [docs/OWNERSHIP_SYNC.md](docs/OWNERSHIP_SYNC.md): snapshot manifest and sync rules +- [docs/OWNERSHIP_PUBLISH.md](docs/OWNERSHIP_PUBLISH.md) and + [docs/OWNERSHIP_SELF_HOSTED.md](docs/OWNERSHIP_SELF_HOSTED.md): maintainer snapshot publishing +- [docs/SMOKE.md](docs/SMOKE.md): smoke tests against live providers ## Development @@ -94,6 +161,9 @@ Prek hooks are configured for quality gates: - pre-commit: `cargo fmt --check` + `cargo clippy -- -D warnings` - pre-push: `cargo test` +Script test suites (no live network): `scripts/install-sh-test.sh`, +`scripts/publish-ownership-snapshot-test.sh`, and `scripts/npm-smoke.sh`. + ## License MIT diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 7de16b6..f31b1fc 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -45,7 +45,7 @@ them yourself. Pass flags through the pipe with `sh -s --`: ```bash -curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.3 --dir ~/bin +curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.4 --dir ~/bin ``` ## Supported platforms diff --git a/docs/NPM_DISTRIBUTION.md b/docs/NPM_DISTRIBUTION.md index dafcd12..d09ed7a 100644 --- a/docs/NPM_DISTRIBUTION.md +++ b/docs/NPM_DISTRIBUTION.md @@ -31,7 +31,7 @@ npx idx-cli --help ``` The package version and the release tag must match. For example, package -version `0.2.3` downloads assets from the `v0.2.3` GitHub Release. +version `0.2.4` downloads assets from the `v0.2.4` GitHub Release. The postinstall script downloads `SHA256SUMS` from the same release and refuses to install a binary whose checksum does not match. @@ -81,7 +81,7 @@ URLs must stay aligned with `scripts/install.js`. To attach binaries to a tag that already exists, run the workflow manually: ```bash -gh workflow run release.yml -f tag=v0.2.3 +gh workflow run release.yml -f tag=v0.2.4 ``` Pull requests that touch the workflow or the installer run the build jobs @@ -91,4 +91,7 @@ Release order: 1. Push the tag, or run the workflow for an existing tag. 2. Confirm the release has all binaries plus `SHA256SUMS`. -3. Run `npm publish`. +3. Run `npm publish` from the tagged commit. The account has two-factor auth, + so npm asks for a browser approval or `--otp=`. A version number + can never be republished, so bump `Cargo.toml` and `package.json` together + before tagging.