nemo-cli 0.0.1__tar.gz

nemo_cli-0.0.1/.claude/skills/new-decision/SKILL.md

@@ -0,0 +1,59 @@
+---
+description: Capture a new architecture decision as an ADR file in docs/decisions/ before any implementation code is written. Use when the user is about to make a significant technical choice (stack, pattern, library, branching strategy, infra) or asks to "document a decision", "open an ADR", or "record this as an ADR".
+---
+
+Help the user document a new architecture decision as an ADR. Do **not** write any
+implementation code during this skill — its only output is the ADR file and the
+updated index.
+
+Steps:
+
+1. **Elicit the decision.** Ask the user, one focused question at a time:
+   - What problem is being solved? (the *context*)
+   - What is the proposed change? (the *decision*)
+   - What other options were considered, and why are they being rejected?
+   - What becomes easier and what becomes harder as a result?
+
+   Do not move on until you have crisp one-paragraph answers for each.
+
+2. **Pick the next ADR number.** List `docs/decisions/` and choose the next zero-
+   padded integer (e.g. if the highest is `005`, the new ADR is `006`).
+
+3. **Write the ADR file** at `docs/decisions/<NNN>-<kebab-case-title>.md` using
+   this exact template:
+
+   ````markdown
+   # ADR-<NNN>: <Title>
+
+   ## Status
+
+   Accepted
+
+   ## Date
+
+   <YYYY-MM-DD — today's date>
+
+   ## Context
+
+   <One or two paragraphs describing the problem.>
+
+   ## Decision
+
+   <The decision itself, stated as imperatives.>
+
+   ## Alternatives Considered
+
+   - **<Option A>.** <Why it was rejected.>
+   - **<Option B>.** <Why it was rejected.>
+
+   ## Consequences
+
+   <Bullets describing what changes — positive and negative — as a result.>
+   ````
+
+4. **Update `docs/decisions/_index.md`** by appending a new row to the table.
+   Preserve column alignment.
+
+5. **Stop.** Do not modify source code in this skill. Tell the user the ADR is
+   ready and that the next step is to implement it (or to invoke a separate task
+   to do so).

nemo_cli-0.0.1/.claude/skills/start-session/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Begin a CFD session by orienting on the nemo-cli project's current status and recent decisions without scanning source code. Use when the user asks to "start session", "get oriented", or invokes the CFD session-start ritual.
+---
+
+Run the Context-First Development session-start ritual. Read **only** the following
+files, in order, and do not scan source code unless a follow-up question requires it:
+
+1. `docs/CURRENT_STATUS.md` — what is in progress, what is blocked, what is next.
+2. `docs/decisions/_index.md` — recent decisions that may affect the next change.
+
+Then produce a brief (≤ 8 lines) summary covering:
+
+- What was being worked on in the previous session.
+- What is currently blocked and why.
+- What the next priority should be, based on `CURRENT_STATUS.md` and any open
+  questions noted there.
+
+Stop after the summary. Do not begin implementing anything until the user gives you a
+specific task.

nemo_cli-0.0.1/.claude/skills/status/SKILL.md

@@ -0,0 +1,27 @@
+---
+description: Summarise the current nemo-cli project status by reading docs/CURRENT_STATUS.md and the ADR index. Use when the user asks "where are we", "what is the status", "what is in progress", or for a CFD project status read.
+---
+
+Summarise the current state of the project for the user. Read **only**:
+
+- `docs/CURRENT_STATUS.md`
+- `docs/decisions/_index.md`
+
+Output the summary in this exact shape:
+
+````
+In progress:
+  - <item> (<short note>)
+
+Blocked / open questions:
+  - <item> (<why it is blocked>)
+
+Recently decided:
+  - <ADR id and title>
+
+Next priority:
+  - <item>
+````
+
+Do not read source code. Do not propose changes. The goal is to give the user a
+30-second read of where things stand.

nemo_cli-0.0.1/.claude/skills/validate-context/SKILL.md

@@ -0,0 +1,26 @@
+---
+description: Audit CFD context-file integrity — verify CLAUDE.md size, @-references resolve, ADR index consistency, no duplicated context, and CURRENT_STATUS.md freshness. Use when the user asks to "validate context", "audit docs", or check whether the CFD scaffolding is healthy.
+---
+
+Run a CFD context-integrity check. Do not modify files; just report findings.
+
+Checks to perform:
+
+1. **CLAUDE.md size.** It should be under ~150 lines and consist mostly of
+   `@docs/...` references plus the build/run section and critical rules. Flag if
+   it has grown into a long-form document.
+2. **`@`-references resolve.** Every `@docs/...` reference in `CLAUDE.md` points to
+   a file that exists.
+3. **ADR index integrity.** Every file matching `docs/decisions/[0-9]*.md` is listed
+   in `docs/decisions/_index.md`, and every row in the index points to a file that
+   exists.
+4. **No duplicated context.** Spot-check that the tech stack is described in
+   `docs/STACK.md` only (not also expanded inside `CLAUDE.md` or `ARCHITECTURE.md`),
+   and that decision rationale is in the relevant ADR (not duplicated in
+   `ARCHITECTURE.md`).
+5. **`CURRENT_STATUS.md` freshness.** Look at the `Last updated:` line. If it is
+   more than two working days behind today's date, flag it.
+
+Output a short report grouped by check, with `✓` / `✗` and a one-line note for each.
+End with a one-line overall verdict: `Context healthy.` or
+`Context needs attention: <N> issues.`

nemo_cli-0.0.1/.env.example

@@ -0,0 +1,2 @@
+NEMO_USERNAME=your-email@example.com
+NEMO_PASSWORD=your-password

nemo_cli-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build backend
+        run: python -m pip install --upgrade pip build
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/nemo-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: publish-to-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nemo-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

nemo_cli-0.0.1/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Secrets
+.env
+.env.local
+.env.*.local
+
+# OS / editors
+*.log
+.DS_Store
+.idea/
+.vscode/
+
+# Claude Code local-only settings (per-user permissions, etc.)
+.claude/settings.local.json
+
+# CFD current project status — managed locally, not shared in the repo
+docs/CURRENT_STATUS.md

nemo_cli-0.0.1/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+Versioning policy and release process: [ADR-007](docs/decisions/007-versioning-and-changelog.md).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-06-04
+
+Initial public release on TestPyPI. The CLI is functional but versioned
+under `0.0.x` to signal that the public surface may still change without
+notice until `0.1.0` (see ADR-007).
+
+### Added
+
+- **Authentication.** `nemo login` / `nemo logout` / `nemo whoami`.
+  Credentials read from `NEMO_USERNAME` / `NEMO_PASSWORD` (env vars only,
+  never persisted by this CLI). Bearer token cached as JSON via
+  `platformdirs`. Proactive refresh when the cached JWT expires within
+  60s; reactive `RefreshToken → SignIn` ladder on `401`. Credentials
+  touch the wire only on bootstrap and as a last resort. (ADR-003,
+  ADR-012)
+- **Instruments listing.**
+  - `nemo instruments local` — Chilean instruments via
+    `GET /api/shared/Instrumentos/FiltrarInstrumentos`. Filters:
+    `--search`, `--classes`, `--page`, `--limit`.
+  - `nemo instruments international` — US-listed assets via
+    `GET /api/frontoffice/shared/Asset`. Filters: `--search`,
+    `--exchange`, `--page`, `--page-size`.
+  - Both commands accept `--json` for a machine-readable payload of the
+    form `{ market, page, page_size, total, items: [...] }`. (ADR-006)
+- **Instrument price history.** `nemo instruments prices --id <ID>`
+  returns ~1 year of daily prices for a local Chilean instrument
+  (`GET /api/frontoffice/shared/PublicadorPrecio/GetPreciosInstrumento`),
+  with computed stats (first/last, min/max with dates, mean, total
+  return %, daily-return σ) and an ASCII sparkline. `--json` emits the
+  full point series plus stats. **Local instruments only**: the upstream
+  endpoint does not serve international assets. (ADR-010)
+- **Portfolio summary.** `nemo portfolio summary` queries
+  `GET /api/frontoffice/shared/cartera/CierreCarteraResumidaOnline` and
+  returns each holding plus computed P&L and totals (per classification
+  + grand total). Flags: `--account-id`, `--currency`,
+  `--with-dividends/--no-dividends`, `--json`. (ADR-008)
+- **Portfolio movements with classification.** `nemo portfolio movements
+  --desde <YYYY-MM-DD> --hasta <YYYY-MM-DD>` queries
+  `GET /api/frontoffice/shared/MovimientosCajas/Movimientos` and parses
+  each movement description into a structured `kind` (`dividend`, `buy`,
+  `sell`, `commission`, `cash_in`, `cash_out`, `other`) plus, when
+  applicable, a typed `DividendInfo` (ex-date, nemotécnico, per-unit
+  amount) or `TradeInfo` (nemotécnico, side). The service computes
+  per-nemotécnico aggregates (`by_dividend`, `by_trade`) and global
+  totals at the boundary. Endpoint is slow; the call uses a **180s
+  timeout** documented in `docs/CONVENTIONS.md`. (ADR-011)
+- **Authenticated HTTP client** at `nemo_cli.api.client.api_request` —
+  the single point for portal HTTP, owns token injection and the
+  refresh ladder.
+- **Distribution.** `pipx install nemo-cli` (TestPyPI for now);
+  `pip install -e .[dev]` for development. `nemo --version` / `-V`
+  prints the CLI version from `nemo_cli.__version__`.
+- **Unit-test suite** — 203 tests, ~98% line coverage, mirrors the
+  package tree under `tests/`. `respx` mocks `httpx` at the transport
+  layer (no real network calls); `typer.testing.CliRunner` drives the
+  CLI. No CI/CD wired yet; tests run locally with `pytest`.
+- **Context-First Development scaffolding** — `CLAUDE.md`,
+  `docs/ARCHITECTURE.md`, `docs/STACK.md`, `docs/CONVENTIONS.md`,
+  `docs/decisions/` (ADRs 001–012 minus 009), and the four CFD skills
+  under `.claude/skills/` (`start-session`, `status`, `new-decision`,
+  `validate-context`).
+- **GitHub Flow** as the project branching strategy. (ADR-005)
+- **Versioning policy** — SemVer + Keep a Changelog. (ADR-007)
+
+[Unreleased]: https://github.com/albertomarturelo/nemo-cli/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/albertomarturelo/nemo-cli/releases/tag/v0.0.1

nemo_cli-0.0.1/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Project Does
+
+`nemo-cli` is a personal command-line tool to inspect holdings on Chilean
+stockbroker portals. Currently compatible with the Vector Capital client portal
+at `https://portalclientes.vectorcapital.cl/api`, which exposes three sub-
+prefixes the CLI calls into: `/publicapi` (auth), `/shared` (local Chilean
+instruments), and `/frontoffice` (international assets and portfolio summary).
+The CLI authenticates with the public `SignIn` endpoint using the user's own
+credentials provided via environment variables, caches the bearer token
+locally, and never redistributes data.
+
+> **Non-affiliation.** This project is not affiliated, endorsed, or sponsored
+> by Vector Capital S.A. Corredores de Bolsa or any other broker. The README
+> carries the user-facing version of this disclaimer.
+
+## Methodology
+
+This project follows **Context-First Development (CFD)**. The methodology itself lives
+in `context-first-development.md` at the repo root and is the source of truth for *how*
+context, decisions, and sessions are managed here. Read it once if you are new to the
+project; do not re-read it every session.
+
+## Architecture
+
+@docs/ARCHITECTURE.md
+
+## Tech Stack
+
+@docs/STACK.md
+
+## Conventions
+
+@docs/CONVENTIONS.md
+
+## Current Status
+
+Tracked locally only — `docs/CURRENT_STATUS.md` is gitignored, so each clone
+maintains its own working notes. Not loaded automatically; the CFD skills
+(`/start-session`, `/status`) read it from disk when present.
+
+## Key Decisions
+
+@docs/decisions/_index.md
+
+## Build & Run
+
+- Install for everyday use (recommended): `pipx install .`
+- Reinstall after local changes: `pipx install --force .`
+- Install editable with dev tools: `pip install -e .[dev]`
+- Run without installing: `python -m nemo_cli <command>`
+- Run after install: `nemo <command>`
+- Typecheck: `pyright`
+- Lint: `ruff check .`
+- Tests: `pytest`
+- Run a single test file: `pytest tests/test_<file>.py`
+
+## Environment
+
+Credentials are loaded from environment variables (via `python-dotenv`). See
+`.env.example`.
+
+| Variable           | Required | Purpose                          |
+|--------------------|----------|----------------------------------|
+| `NEMO_USERNAME`  | yes      | Email used to sign in            |
+| `NEMO_PASSWORD`  | yes      | Password used to sign in         |
+
+The Vector API base URL is hardcoded in `nemo_cli.config.API_BASE_URL` — there is
+no env override (see ADR-004). Reintroduce one via a new ADR if a staging environment
+appears.
+
+## Critical Rules
+
+- **All HTTP traffic to the Vector API must go through `api_request()` in
+  `src/nemo_cli/api/client.py`.** That function owns token retrieval, caching, and
+  the 401-retry-after-refresh flow. Calling `httpx.request(...)` directly from a
+  command bypasses re-authentication and will cause silent failures when tokens
+  expire. The only allowed exception is `nemo_cli.auth.service.sign_in`, which is
+  the bootstrap call. See ADR-003.
+- **Never commit `.env` or any real credential.** `.env.example` is the only template
+  in version control.
+- **Document significant decisions as ADRs *before* writing the code that implements
+  them.** Use the `/new-decision` skill. Update `docs/decisions/_index.md` in the
+  same change.
+  See ADR-001 for the rationale.
+- **English for all model-facing context** (CLAUDE.md, docs/, ADRs, slash commands,
+  code identifiers, code comments). PR descriptions and chat with the user can be in
+  Spanish — the user works in Spanish.
+- **Update `docs/CURRENT_STATUS.md` before closing every session.** This is how the
+  next session knows what was in flight. CFD treats this as non-negotiable.
+- **The Vector API response shapes are not yet officially typed.** When integrating a
+  new endpoint, capture a real response (redacted), then add a typed dataclass /
+  `TypedDict` in the module that owns the call. Do not assume field names from
+  external documentation without verification.

nemo_cli-0.0.1/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.