nemo-cli 0.0.1__py3-none-any.whl

nemo_cli-0.0.1.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: nemo-cli
+Version: 0.0.1
+Summary: Personal CLI to query Chilean stockbroker portals (currently compatible with portalclientes.vectorcapital.cl).
+Project-URL: Homepage, https://github.com/albertomarturelo/nemo-cli
+Project-URL: Repository, https://github.com/albertomarturelo/nemo-cli
+Project-URL: Issues, https://github.com/albertomarturelo/nemo-cli/issues
+Project-URL: Changelog, https://github.com/albertomarturelo/nemo-cli/blob/main/CHANGELOG.md
+Author-email: Alberto Marturelo Lorenzo <amarturelo@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Alberto Marturelo Lorenzo
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: broker,chile,cli,finance,investment,stockbroker
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nemo-cli
+
+A personal command-line tool to inspect your holdings on Chilean stockbroker portals. Authenticates with your own credentials, caches a bearer token locally, and exposes portal operations as composable terminal commands.
+
+> **Disclaimer.** This project is **not affiliated, endorsed, or sponsored** by Vector Capital S.A. Corredores de Bolsa or any other broker. It is a personal, unofficial client and is provided "as is", without any warranty. You are the sole responsible party for compliance with your contract with the broker whose portal you connect to. The CLI calls only documented endpoints reachable from the official web UI under your own session, with your own credentials, and never redistributes data. Currently compatible with the Vector Capital client portal at `portalclientes.vectorcapital.cl`.
+
+## Highlights
+
+- One-command authentication — `nemo login` exchanges credentials for a token and caches it per user.
+- Transparent token refresh — every authenticated call retries once on `401` after re-authenticating.
+- Credentials live in environment variables; only the short-lived token is persisted.
+- Browse Chilean and US-listed instruments — `nemo instruments local` / `nemo instruments international`, with `--json` output for downstream agent / scripted consumption.
+- Inspect your portfolio — `nemo portfolio summary` returns each holding plus computed P&L and totals by classification.
+- 1-year price history per local instrument — `nemo instruments prices --id <ID>` with stats (total return, σ, min/max) and an ASCII sparkline.
+- Cash movements with classification — `nemo portfolio movements` parses each row into `dividend` / `buy` / `sell` / `commission` / `cash_in` / `cash_out` and aggregates by nemotécnico, ready for dividend-yield analysis.
+- Pure-Python, type-hinted (`pyright` strict), tested (~98% line coverage), distributed via `pipx`.
+
+## Requirements
+
+- Python **≥ 3.11**
+- [`pipx`](https://pipx.pypa.io/) (recommended) or `pip`
+- A Chilean stockbroker portal account (currently: Vector Capital)
+
+## Installation
+
+The recommended path is [`pipx`](https://pipx.pypa.io/) so the `nemo` command is available in every terminal — isolated venv, automatic `$PATH` wiring, clean uninstall.
+
+### 1. Install `pipx` (one-time)
+
+**macOS (Homebrew):**
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+**Any platform (with `pip`):**
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+After running `pipx ensurepath`, open a new terminal so the updated `$PATH` is picked up. Verify with `pipx --version`.
+
+### 2. Install nemo-cli
+
+```bash
+git clone <repo-url> nemo-cli
+cd nemo-cli
+pipx install .
+```
+
+To upgrade after pulling new changes:
+
+```bash
+pipx install --force .
+```
+
+To uninstall:
+
+```bash
+pipx uninstall nemo-cli
+```
+
+## Configuration
+
+Credentials are read from environment variables. The simplest way is a `.env` file at the project root (or your shell session):
+
+```bash
+cp .env.example .env
+# then edit .env with your credentials
+```
+
+| Variable           | Required | Description               |
+|--------------------|----------|---------------------------|
+| `NEMO_USERNAME`  | yes      | Email used to sign in     |
+| `NEMO_PASSWORD`  | yes      | Account password          |
+
+> The Vector API base URL is intentionally hardcoded in `nemo_cli.config`. There is no env override; if you need one (e.g. for a staging environment), add an ADR first.
+
+> The `.env` file is gitignored. Never commit real credentials.
+
+The cached bearer token is stored under your OS user-config directory, e.g. `~/Library/Application Support/nemo-cli/token.json` on macOS. Run `nemo logout` to clear it.
+
+## Usage
+
+```bash
+nemo login                              # authenticate and cache the token
+nemo whoami                             # show the configured user and token state
+nemo logout                             # drop the cached token
+nemo instruments local --search BCI     # list Chilean instruments matching "BCI"
+nemo instruments international --search aapl --page-size 5
+nemo instruments prices --id 52185      # 1-year price history (local instruments only)
+nemo portfolio summary                  # holdings + P&L + totals by classification
+nemo portfolio movements                              # default window: last 365 days
+nemo portfolio movements --desde 2025-01-18 --hasta 2026-01-25   # explicit date range (YYYY-MM-DD)
+nemo --version                          # print the CLI version and exit
+nemo --help                             # general help
+nemo <cmd> --help                       # per-command help
+```
+
+### Commands
+
+| Command                       | Description                                                                      |
+|-------------------------------|----------------------------------------------------------------------------------|
+| `login`                       | Authenticate against the configured broker portal and cache the bearer token.    |
+| `logout`                      | Clear the cached bearer token.                                                   |
+| `whoami`                      | Show the configured user and whether a token is currently cached.                |
+| `instruments local`           | List Chilean instruments. Filters: `--search`, `--classes`, `--page`, `--limit`. |
+| `instruments international`   | List US-listed assets. Filters: `--search`, `--exchange`, `--page`, `--page-size`. |
+| `instruments prices`          | Show ~1 year of daily prices for a local Chilean instrument (stats + sparkline). Flag: `--id`. **Local instruments only.** |
+| `portfolio summary`           | Show your holdings with P&L and totals by classification. Flags: `--account-id`, `--currency`, `--with-dividends/--no-dividends`. |
+| `portfolio movements`         | List cash movements over a date range, classified per kind (dividend / buy / sell / commission / cash flows) with per-nemotécnico aggregates. Flags: `--desde YYYY-MM-DD` (default: 1 year ago), `--hasta YYYY-MM-DD` (default: today), `--account-id`. |
+
+All listing commands accept `--json` to emit a machine-readable payload
+(`{ market, page, page_size, total, items: [...] }`) instead of a Rich table.
+That payload is the integration contract for downstream tooling.
+
+More commands will be added incrementally.
+
+## Development
+
+For day-to-day development, install editable inside a virtual environment so changes are picked up immediately and tooling stays isolated from the rest of your system.
+
+### Create and activate the venv
+
+```bash
+python3 -m venv .venv               # create the venv (one time)
+source .venv/bin/activate           # activate it — macOS / Linux (bash, zsh)
+# source .venv/bin/activate.fish      # fish shell
+# .venv\Scripts\Activate.ps1          # PowerShell on Windows
+pip install --upgrade pip
+pip install -e .[dev]               # editable install with dev deps
+```
+
+Your prompt will show `(.venv)` while the environment is active. Leave it with `deactivate`.
+
+### Day-to-day commands
+
+```bash
+python -m nemo_cli <cmd>     # run from source without installing the entry point
+nemo <cmd>                   # the entry point also works (editable install wires it)
+pyright                      # typecheck (strict, src/ only)
+ruff check .                 # lint + import sort (src/ + tests/)
+pytest                       # run the unit-test suite
+pytest -k <name>             # run a single test or pattern
+```
+
+> If you only want a one-off run without polluting your shell, you can skip activation and call the binaries directly: `.venv/bin/nemo <cmd>`, `.venv/bin/pytest`, etc.
+
+### Testing
+
+The unit-test suite mirrors the package tree under `tests/` and runs in well
+under a second. No real network calls — `httpx` is intercepted at the
+transport layer with [`respx`](https://github.com/lundberg/respx) — and no
+real filesystem writes outside `tmp_path`.
+
+```bash
+pytest                                   # ~144 tests, ~98% line coverage
+pytest tests/portfolio/                  # one package
+pytest tests/portfolio/test_summary.py   # one file
+pytest -k "compute_totals"               # by name pattern
+```
+
+What the suite covers:
+
+- Pure parsers (`_to_*`) and aggregators (`_compute_*`, `_sparkline`) — 100%.
+- HTTP services (`sign_in`, `api_request`, the four list / detail endpoints) — happy paths plus the 401-refresh-and-retry-once flow, mocked end-to-end with `respx`.
+- CLI commands via `typer.testing.CliRunner` — table output, args passthrough, `--json` envelope shape, error paths exit `1`.
+
+Conventions for adding tests live in
+[`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) (testing section). There is
+**no CI/CD configured** at the moment — checks run locally before opening
+a PR.
+
+## Project Structure
+
+```
+.
+├── CLAUDE.md                       # Index of agent-facing context
+├── CHANGELOG.md                    # Keep a Changelog (see Versioning)
+├── context-first-development.md    # CFD methodology
+├── pyproject.toml                  # Project metadata, deps, entry point
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── STACK.md
+│   ├── CONVENTIONS.md
+│   └── decisions/                  # Architecture Decision Records
+├── .claude/skills/                 # CFD skills (start-session, status, new-decision, validate-context)
+├── src/nemo_cli/
+│   ├── cli.py, __main__.py         # Entry + Typer app
+│   ├── commands/                   # One module per subcommand (login, logout, whoami, instruments, portfolio)
+│   ├── portfolio/                  # Holdings service + P&L / totals computation
+│   ├── instruments/                # Local + international market services + price history
+│   ├── api/client.py               # api_request — single point for portal HTTP
+│   ├── auth/                       # SignIn call and local token store
+│   └── config.py                   # Env-var loader; hardcoded base URL
+└── tests/                          # Unit tests, mirror src/nemo_cli/ tree
+    ├── conftest.py                 # Shared fixtures (env, isolated token store)
+    ├── auth/, api/, instruments/, portfolio/, commands/
+    └── test_cli.py, test_config.py
+```
+
+## Versioning
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/) and
+maintains a [Keep a Changelog](https://keepachangelog.com/) — see
+[`CHANGELOG.md`](CHANGELOG.md). The current version is the one declared in
+`pyproject.toml` and mirrored in `nemo_cli.__version__`. The release process
+is documented in [ADR-007](docs/decisions/007-versioning-and-changelog.md).
+
+## Methodology
+
+This repository follows **Context-First Development (CFD)**. Architecture, conventions, and decisions live in [`docs/`](docs/); the methodology itself is documented in [`context-first-development.md`](context-first-development.md). When pairing with an AI agent, start with [`CLAUDE.md`](CLAUDE.md).
+
+### Starting a development session
+
+The CFD session-start ritual loads project context without scanning source code — the agent orients itself in ~500 tokens instead of tens of thousands.
+
+```bash
+# 1. Sync the working copy with the remote
+git pull --ff-only
+
+# 2. Glance at open work (optional, requires GitHub CLI)
+gh pr list --state open
+gh issue list
+
+# 3. Start Claude Code from the repo root
+claude
+
+# 4. Inside the session, run the orientation skill
+> /start-session
+```
+
+`/start-session` reads `docs/CURRENT_STATUS.md` (a local-only file — see "Closing a session" below) and [`docs/decisions/_index.md`](docs/decisions/_index.md), and returns a short summary of what was in flight, what is blocked, and what the next priority should be. The other CFD skills shipped in [`.claude/skills/`](.claude/skills/):
+
+| Skill                | When to use                                                                                |
+|----------------------|--------------------------------------------------------------------------------------------|
+| `/start-session`     | At the start of every session — load current status + recent decisions.                    |
+| `/status`            | Quick "where are we" without the full orientation.                                         |
+| `/new-decision`      | Before implementing any significant technical choice — captures it as an ADR.              |
+| `/validate-context`  | Audit context-file integrity (CLAUDE.md size, @-references, ADR index, status freshness).  |
+
+### Closing a session
+
+Before ending, ask the agent to create or update `docs/CURRENT_STATUS.md` with what was done, what is still pending, and any blockers discovered. That file is the only thing the next session reads to know where work was left — skipping it breaks the loop.
+
+`docs/CURRENT_STATUS.md` is **gitignored on purpose** — it is working state, not a shared artifact, so each clone keeps its own notes. The file does not exist in a fresh clone; the first `/start-session` after `git clone` will simply have less context to summarise, and you create the file when you close the session.
+
+## Security
+
+- Credentials never touch disk through this CLI. They are read from `os.environ` at command time.
+- Only the bearer token is persisted, in a per-user JSON file under your OS config directory.
+- Run `nemo logout` (or delete the JSON file) to revoke the local session at any time.

nemo_cli-0.0.1.dist-info/RECORD

@@ -0,0 +1,28 @@
+nemo_cli/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+nemo_cli/__main__.py,sha256=faQsEifImPpBQreJnb0mhSDN8T-so8HAWMDP699LA34,69
+nemo_cli/cli.py,sha256=C_S_ScRQcOX7XDq5JvrSljz1kRmYjuQCWFUJdBa1i0E,1121
+nemo_cli/config.py,sha256=FqesRSkFMKHbu9DlkJHj208_YijEl_4AR_QJxFm-vm4,619
+nemo_cli/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nemo_cli/api/client.py,sha256=KaqRc1-iZ7F9RTqw6c93kkZ2zRIXhgXLpmu-62jyijo,2396
+nemo_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nemo_cli/auth/jwt.py,sha256=wVPAmYT2bY1-nKYQuMGK7pIXNXPWtfZy7XJiPOkEhK4,1431
+nemo_cli/auth/service.py,sha256=mT5d9h_r9c2ZGUve1Mho27KXjR7oSXckBOv13p_R3HI,1913
+nemo_cli/auth/token_store.py,sha256=gH16JsgKm6mFlAyo4iAWxSoeQfOr_9xnAjTHTnh_5Rk,894
+nemo_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nemo_cli/commands/instruments.py,sha256=XDghst2HdpKnPjxbnfOAJflzpkfpSNI7670FE_C3WxE,8962
+nemo_cli/commands/login.py,sha256=By9WYa0-PueumQOMtxie56oECNfkYaUXKWy7AhnwPqw,484
+nemo_cli/commands/logout.py,sha256=nKinYDXq8RRhkRGtD78OGznNqA1BSHjXK-dQ4kUMNtM,231
+nemo_cli/commands/portfolio.py,sha256=8FLRZ3y5MmSTLfH0nfRZn7HnuvKO50gWHve-RaNzHsY,9643
+nemo_cli/commands/whoami.py,sha256=D68d-c-lVI48vWMv9Bn-6Wjd4Eu7X5c0pTgb0y06qqs,625
+nemo_cli/instruments/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nemo_cli/instruments/international.py,sha256=t39ppONAfogw1LWQpaLc1n9bchppM6m8sSPK_lHOoVk,2976
+nemo_cli/instruments/local.py,sha256=VGAkU_XAH9D8Bf1yE1dYVpebJZ3MrvDgI55hdtxzpLM,2875
+nemo_cli/instruments/prices.py,sha256=n8FCPtdcVVYzgQckgW0gfWBc6Pw76gA8bHYoaoraIj0,3652
+nemo_cli/portfolio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nemo_cli/portfolio/movements.py,sha256=JV8tUETfkssmlFM3cG_4u5GXpGy-IpFs5AqWddnNX5I,9563
+nemo_cli/portfolio/summary.py,sha256=UQmN_48AG4t-ylI6lBX0vW7pXg8lRolIuos7hfCBb0w,5446
+nemo_cli-0.0.1.dist-info/METADATA,sha256=3lIY8Thd5egyV1L3yxOqFoWaEzOMXBRZ1FcntOWnvtQ,16210
+nemo_cli-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+nemo_cli-0.0.1.dist-info/entry_points.txt,sha256=6CgvxpKdqPj9rbAfvoLkxm0VaQ5LrOspLPGA6URCt50,43
+nemo_cli-0.0.1.dist-info/licenses/LICENSE,sha256=7EWQIdGWtI4AHWe7fxmjuepc8W195aWDzGbIM3uAs5k,1082
+nemo_cli-0.0.1.dist-info/RECORD,,

nemo_cli-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

nemo_cli-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nemo = nemo_cli.cli:main

nemo_cli-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Marturelo Lorenzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.