nexusquant-cli 0.2.1__tar.gz → 0.4.0__tar.gz

nexusquant_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,59 @@
+# nexusquant-cli
+
+Python CLI for NexusQuant users, strategy providers and admins. Cognito PKCE browser login, token storage/refresh, and wrappers over the nexus-service REST API.
+
+Two entry points, one login (credentials shared with nexusquant-sdk under `platformdirs/nexusquant-sdk/credentials.json`):
+
+- `nexus-cli` (`nexusquant_cli/nexus.py`) — `nexus-cli <role> <verb> <resource>`; roles `investor` / `provider` / `admin`, plus `auth`.
+- `nexusquant` (`nexusquant_cli/main.py`) — legacy flat provider layout. Keep it working: scheduled tasks and the nexus-admin webhook-adapter skill call it, and `webhook_admin.py` imports `nexusquant_cli.api_client`, `config` and `auth_pkce.ensure_fresh_id_token` directly.
+
+## Code structure
+
+```
+nexusquant_cli/
+  nexus.py          # nexus-cli entry (role groups)
+  main.py           # legacy nexusquant entry
+  roles/            # auth / investor / provider / admin — verb-first sub-apps
+                    #   provider.py mounts the functions from commands/ rather than copying them
+  commands/         # legacy command bodies (auth, strategy, policy) + _util (fail / JSON helpers)
+  api_client.py     # HTTP wrapper; ApiError; retries once on stale-Wall-Pro 403
+  identity.py       # decode local ID token for whoami / 403 hints (display only, never gates)
+  auth_pkce.py      # Cognito PKCE flow
+  config.py         # endpoints, credential path
+docs/investor-operations.md  # investor API surface survey + phase-2 roadmap
+tests/              # pytest, httpx.MockTransport — no network
+```
+
+Tests: `pip install -e '.[dev]' && python -m pytest -q tests`.
+
+Investor commands deliberately exclude anything that arms auto-trading, changes sizing, or touches broker secrets — see docs/investor-operations.md before adding those.
+
+## Install
+
+```bash
+# Development (editable)
+pip install -e .
+
+# From PyPI
+pip install nexusquant-cli
+```
+
+## Usage
+
+See README.md.
+
+## Deploy / publish
+
+```bash
+# Build distribution
+python -m build
+
+# Publish to PyPI
+twine upload dist/*
+```
+
+## Configuration
+
+API base URL is set in `nexusquant_cli/config.py`. Change `API_BASE_URL` to point at a different environment (staging vs production).
+
+Provider commands need `custom:userType=strategyProvider` or admin; admin commands need admin (or the `admin` Cognito group). User commands work for any login; some need Wall Pro.

{nexusquant_cli-0.2.1 → nexusquant_cli-0.4.0}/PKG-INFO

@@ -1,20 +1,25 @@
 Metadata-Version: 2.5
 Name: nexusquant-cli
-Version: 0.2.1
-Summary: NexusQuant strategy provider CLI
+Version: 0.4.0
+Summary: NexusQuant CLI for users, strategy providers and admins
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: nexusquant-sdk>=0.2
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: rich>=13.7
 Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # nexusquant-cli
 
-Command line tool for NexusQuant strategy providers.
+Command line tool for NexusQuant investors, strategy providers and admins.
 
-It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus strategy provider APIs. Provider commands require a Cognito user with `custom:userType=strategyProvider` or `custom:userType=admin`.
+It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus APIs. Two entry points share one login:
+
+- **`nexus-cli`** — role-first grammar, `nexus-cli <role> <verb> <resource> [args]`. Use this.
+- `nexusquant` — the original flat provider layout (`nexusquant strategy|policy …`), kept unchanged for existing scripts. Everything below the `nexus-cli` section documents it.
 
 ## Install
 
@@ -26,7 +31,108 @@ python3 -m pip install -e .
 pip install nexusquant-cli
 ```
 
-## Login
+## nexus-cli
+
+```bash
+nexus-cli auth login          # browser login; one login covers every role
+nexus-cli auth whoami         # account, userType, Wall Pro tier, usable roles
+```
+
+The role is not picked at login — it is the account's `custom:userType` (or the `admin` Cognito group), and the server checks it on every call. `whoami` reads it from the local token; on a 403 the CLI prints which account type is logged in.
+
+Every read takes `--json` for scripting; the default output is a table.
+
+### investor — any logged-in account
+
+| Command | What it does |
+|---|---|
+| `investor list strategies [--subscribed]` | Marketplace, with backtest summary and a flag for strategies whose sizing reads your holdings |
+| `investor read strategy <id>` | Detail + 30 most recent signals |
+| `investor read backtest <id>` | Backtest stats, rolling returns, per-ticker attribution, return since you added it |
+| `investor subscribe strategy <id>...` | Add to My Strategies (Wall Pro). **Does not start auto-trading** |
+| `investor unsubscribe strategy <id> [-y]` | Remove from My Strategies; asks first, and warns if it is listening (this stops auto-trading) |
+| `investor list subscriptions` | My Strategies: listening on/off, config saved, broker |
+| `investor read config <id>` | Your personal config, effective config, and the schema of what you can set |
+| `investor list signals [--strategy-id --status --direction --limit --offset]` | Signals that reached you, with your own broker result for each |
+| `investor read stats` | Signal counts and broker success rate |
+| `investor read profile` / `investor read settings` | Account; daily-report setting |
+| `investor update settings --daily-report/--no-daily-report` | Toggle the daily report email |
+| `investor read container` | Trading environment state, broker login, selected account |
+| `investor list brokers` | Supported brokers and their login fields |
+| `investor list activity` | Your own activity log |
+
+#### Nexus AI agent — permissions and logs
+
+Nexus AI is the agent you chat with in the web app. Commands for the agent are under `investor`, and you can only **narrow** what it may do. The ceiling comes from your profile and is enforced on the agent host.
+
+```bash
+nexus-cli investor read agent-access                       # enabled?, profile, tools, extra denied tools
+nexus-cli investor update agent-access --profile readonly  # investor | readonly (admins: operator) | default
+nexus-cli investor update agent-access --deny-tool Write --deny-tool Edit
+nexus-cli investor update agent-access --clear-deny
+nexus-cli investor list agent-sessions                     # past conversations: title, turns, tool calls, denials, cost
+nexus-cli investor read agent-session ws-…                  # the full conversation, as it happened
+nexus-cli investor delete agent-session ws-…                # remove it from your history (soft delete)
+nexus-cli investor list agent-logs --denied                # every refused tool call
+nexus-cli investor list agent-logs --session ws-… --event tool_executed
+```
+
+| Profile | Tools | Files |
+|---|---|---|
+| `investor` | Read, Glob, Grep, Write, Edit, MultiEdit, TodoWrite, WebSearch. No shell, no sub-agents, no WebFetch | Only your own workspace |
+| `readonly` | `investor` without the write tools | Only your own workspace |
+| `operator` (admins only) | Everything | The whole agent workspace |
+
+- Conversations are kept permanently so you can read your history. Deleting one hides it from you; the platform keeps a copy, and admins can still see it.
+- Audit entries (the per-tool-call log) are kept for 90 days.
+- Changes apply to sessions opened afterwards.
+- Every tool call is logged: which tool, a summary of its input, and whether it was auto-allowed, approved by you, or refused. Refusals record who refused it: the profile, you, or a timeout.
+- Each turn also logs its cost.
+
+Not in the CLI yet, on purpose: switching listening on (arms auto-trading), editing sizing config, broker connect, container start/stop/reset, and webhook strategies. They place real orders or carry broker secrets and need their own confirmation / secret-handling design — see `docs/investor-operations.md`.
+
+### provider — `custom:userType=strategyProvider` or admin
+
+| Command | Same as legacy |
+|---|---|
+| `provider create strategy -i ID -n NAME [--schema-file …]` | `nexusquant strategy create` |
+| `provider list strategies` | `nexusquant strategy list` |
+| `provider list signals <id> [--limit --offset --status --direction]` | `nexusquant strategy signal <id> --history` |
+| `provider send signal <id> --ticker … --direction … --price … --quantity …` / `--signals-file` | `nexusquant strategy signal <id> --ticker …` |
+| `provider list subscribers <id>` | `nexusquant strategy sub config <id>` |
+| `provider list features [--scope --json]` | `nexusquant policy features` |
+| `provider publish policy --strategy-id … --ticker … --file …` | `nexusquant policy publish` |
+| `provider list policies <id>` | `nexusquant policy list` |
+| `provider update policy --policy-id … --mode off` | `nexusquant policy set-mode` |
+| `provider send policy-signal …` | `nexusquant policy send-signal` |
+
+Options are identical to the legacy commands documented below. One difference: `provider send signal` with no send fields is an error, where the legacy `strategy signal` silently listed history.
+
+### admin — `custom:userType=admin`
+
+```bash
+nexus-cli admin list reviews [--status all] [--verbose]
+nexus-cli admin review strategy <id> --action approve|reject|suspend [--note …]
+```
+
+```bash
+nexus-cli admin list agent-access                       # who besides admins may use Nexus AI
+nexus-cli admin grant agent-access --email someone@x.com
+nexus-cli admin revoke agent-access --email someone@x.com
+nexus-cli admin list agent-sessions [--email … | --user-id …] [--include-deleted]
+nexus-cli admin read agent-session ws-…                  # any user's conversation; each read goes into your admin activity log
+nexus-cli admin list agent-logs --email someone@x.com --denied
+```
+
+How grant and revoke take effect:
+- Granting adds the user to the `NEXUS_AI_USERS` flag. Non-admins can only connect once the backend's `NEXUS_AI_BRIDGE_POLICY` is also on.
+- Revoking refuses new connections within about 30 seconds. A session that is already open closes at its next token renewal; the web app renews every 20 minutes.
+
+Agent ops (weekly analysis uploads, S3 reads, Discord KB, notify) stay in `nexus-agent` (nexus-agent-cli) for now.
+
+## Legacy `nexusquant` commands
+
+### Login
 
 ```bash
 nexusquant auth

{nexusquant_cli-0.2.1 → nexusquant_cli-0.4.0}/README.md

@@ -1,8 +1,11 @@
 # nexusquant-cli
 
-Command line tool for NexusQuant strategy providers.
+Command line tool for NexusQuant investors, strategy providers and admins.
 
-It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus strategy provider APIs. Provider commands require a Cognito user with `custom:userType=strategyProvider` or `custom:userType=admin`.
+It supports browser login through Cognito, stores tokens locally, refreshes tokens, and calls the Nexus APIs. Two entry points share one login:
+
+- **`nexus-cli`** — role-first grammar, `nexus-cli <role> <verb> <resource> [args]`. Use this.
+- `nexusquant` — the original flat provider layout (`nexusquant strategy|policy …`), kept unchanged for existing scripts. Everything below the `nexus-cli` section documents it.
 
 ## Install
 
@@ -14,7 +17,108 @@ python3 -m pip install -e .
 pip install nexusquant-cli
 ```
 
-## Login
+## nexus-cli
+
+```bash
+nexus-cli auth login          # browser login; one login covers every role
+nexus-cli auth whoami         # account, userType, Wall Pro tier, usable roles
+```
+
+The role is not picked at login — it is the account's `custom:userType` (or the `admin` Cognito group), and the server checks it on every call. `whoami` reads it from the local token; on a 403 the CLI prints which account type is logged in.
+
+Every read takes `--json` for scripting; the default output is a table.
+
+### investor — any logged-in account
+
+| Command | What it does |
+|---|---|
+| `investor list strategies [--subscribed]` | Marketplace, with backtest summary and a flag for strategies whose sizing reads your holdings |
+| `investor read strategy <id>` | Detail + 30 most recent signals |
+| `investor read backtest <id>` | Backtest stats, rolling returns, per-ticker attribution, return since you added it |
+| `investor subscribe strategy <id>...` | Add to My Strategies (Wall Pro). **Does not start auto-trading** |
+| `investor unsubscribe strategy <id> [-y]` | Remove from My Strategies; asks first, and warns if it is listening (this stops auto-trading) |
+| `investor list subscriptions` | My Strategies: listening on/off, config saved, broker |
+| `investor read config <id>` | Your personal config, effective config, and the schema of what you can set |
+| `investor list signals [--strategy-id --status --direction --limit --offset]` | Signals that reached you, with your own broker result for each |
+| `investor read stats` | Signal counts and broker success rate |
+| `investor read profile` / `investor read settings` | Account; daily-report setting |
+| `investor update settings --daily-report/--no-daily-report` | Toggle the daily report email |
+| `investor read container` | Trading environment state, broker login, selected account |
+| `investor list brokers` | Supported brokers and their login fields |
+| `investor list activity` | Your own activity log |
+
+#### Nexus AI agent — permissions and logs
+
+Nexus AI is the agent you chat with in the web app. Commands for the agent are under `investor`, and you can only **narrow** what it may do. The ceiling comes from your profile and is enforced on the agent host.
+
+```bash
+nexus-cli investor read agent-access                       # enabled?, profile, tools, extra denied tools
+nexus-cli investor update agent-access --profile readonly  # investor | readonly (admins: operator) | default
+nexus-cli investor update agent-access --deny-tool Write --deny-tool Edit
+nexus-cli investor update agent-access --clear-deny
+nexus-cli investor list agent-sessions                     # past conversations: title, turns, tool calls, denials, cost
+nexus-cli investor read agent-session ws-…                  # the full conversation, as it happened
+nexus-cli investor delete agent-session ws-…                # remove it from your history (soft delete)
+nexus-cli investor list agent-logs --denied                # every refused tool call
+nexus-cli investor list agent-logs --session ws-… --event tool_executed
+```
+
+| Profile | Tools | Files |
+|---|---|---|
+| `investor` | Read, Glob, Grep, Write, Edit, MultiEdit, TodoWrite, WebSearch. No shell, no sub-agents, no WebFetch | Only your own workspace |
+| `readonly` | `investor` without the write tools | Only your own workspace |
+| `operator` (admins only) | Everything | The whole agent workspace |
+
+- Conversations are kept permanently so you can read your history. Deleting one hides it from you; the platform keeps a copy, and admins can still see it.
+- Audit entries (the per-tool-call log) are kept for 90 days.
+- Changes apply to sessions opened afterwards.
+- Every tool call is logged: which tool, a summary of its input, and whether it was auto-allowed, approved by you, or refused. Refusals record who refused it: the profile, you, or a timeout.
+- Each turn also logs its cost.
+
+Not in the CLI yet, on purpose: switching listening on (arms auto-trading), editing sizing config, broker connect, container start/stop/reset, and webhook strategies. They place real orders or carry broker secrets and need their own confirmation / secret-handling design — see `docs/investor-operations.md`.
+
+### provider — `custom:userType=strategyProvider` or admin
+
+| Command | Same as legacy |
+|---|---|
+| `provider create strategy -i ID -n NAME [--schema-file …]` | `nexusquant strategy create` |
+| `provider list strategies` | `nexusquant strategy list` |
+| `provider list signals <id> [--limit --offset --status --direction]` | `nexusquant strategy signal <id> --history` |
+| `provider send signal <id> --ticker … --direction … --price … --quantity …` / `--signals-file` | `nexusquant strategy signal <id> --ticker …` |
+| `provider list subscribers <id>` | `nexusquant strategy sub config <id>` |
+| `provider list features [--scope --json]` | `nexusquant policy features` |
+| `provider publish policy --strategy-id … --ticker … --file …` | `nexusquant policy publish` |
+| `provider list policies <id>` | `nexusquant policy list` |
+| `provider update policy --policy-id … --mode off` | `nexusquant policy set-mode` |
+| `provider send policy-signal …` | `nexusquant policy send-signal` |
+
+Options are identical to the legacy commands documented below. One difference: `provider send signal` with no send fields is an error, where the legacy `strategy signal` silently listed history.
+
+### admin — `custom:userType=admin`
+
+```bash
+nexus-cli admin list reviews [--status all] [--verbose]
+nexus-cli admin review strategy <id> --action approve|reject|suspend [--note …]
+```
+
+```bash
+nexus-cli admin list agent-access                       # who besides admins may use Nexus AI
+nexus-cli admin grant agent-access --email someone@x.com
+nexus-cli admin revoke agent-access --email someone@x.com
+nexus-cli admin list agent-sessions [--email … | --user-id …] [--include-deleted]
+nexus-cli admin read agent-session ws-…                  # any user's conversation; each read goes into your admin activity log
+nexus-cli admin list agent-logs --email someone@x.com --denied
+```
+
+How grant and revoke take effect:
+- Granting adds the user to the `NEXUS_AI_USERS` flag. Non-admins can only connect once the backend's `NEXUS_AI_BRIDGE_POLICY` is also on.
+- Revoking refuses new connections within about 30 seconds. A session that is already open closes at its next token renewal; the web app renews every 20 minutes.
+
+Agent ops (weekly analysis uploads, S3 reads, Discord KB, notify) stay in `nexus-agent` (nexus-agent-cli) for now.
+
+## Legacy `nexusquant` commands
+
+### Login
 
 ```bash
 nexusquant auth

nexusquant_cli-0.4.0/docs/investor-operations.md

@@ -0,0 +1,60 @@
+# What a normal user can do — API surface and CLI roadmap
+
+Surveyed 2026-10-07 against nexus-service `58f1d16` and nexus-frontend-platform.
+"User" = any Cognito login that is neither `strategyProvider` nor `admin`.
+Paths are under `/api`.
+
+**Auth.** Send the **ID token** (Bearer). An access token alone authenticates, but
+carries no `custom:access*` claims, so every Wall Pro endpoint 403s. The backend
+reads `custom:userType`, falling back to the `admin` Cognito group.
+
+**Wall Pro.** Wall Pro requires `custom:accessStatus=active` plus `custom:accessLevel=pro` in the ID token. Admins bypass the check.
+
+A token minted before an upgrade fails until it is refreshed. The web app and `nexus-cli` both handle this the same way: on a 403 that mentions "Wall Pro", they force a refresh and retry once.
+
+## Phase 1 — in `nexus-cli investor` now
+
+| Command | Endpoint | Tier |
+|---|---|---|
+| list strategies | GET `strategy/market/` | login |
+| list strategies --subscribed | GET `strategy/market/subscribed/` | login |
+| read strategy | GET `strategy/market/<id>/` | login |
+| read backtest | GET `strategy/market/<id>/backtest/` | login (private: owner/admin) |
+| subscribe strategy | POST `strategy/market/checkout/` `{strategy_ids}` | Pro |
+| unsubscribe strategy | POST `strategy/unsubscribe/<id>/` | login |
+| list subscriptions | GET `user/strategy/list/` | login |
+| read config | GET `user/strategy/list/` (one row) | login |
+| list signals | GET `strategy-signal/logs/` | login |
+| read stats | GET `strategy-signal/statistics/` | login |
+| read profile | GET `auth/profile/` | login |
+| read / update settings | GET / PUT `user/settings/` `{receive_daily_report}` | login |
+| read container | GET `user/container/health/` + `container/<cid>/status/` | login |
+| list brokers | GET `container/brokers/` | public |
+| list activity | GET `user/activity-logs/?mine=true` | login |
+
+Use the `strategy/market/*` endpoints, never `strategy/list|detail|subscribe/`. The latter filter by status only and skip `is_listed` and visibility.
+
+## Phase 2 — candidates, highest risk first
+
+| Operation | Endpoint | Risk / design needed |
+|---|---|---|
+| Listening on (arms auto-trading) | POST `user/strategy/subscribe/<id>/` (Pro) | **Real orders follow.** Needs a saved config (400 `needs_config_acknowledgement`); webhook strategies return 409 `WEBHOOK_PRECONDITION`. Show the effective config and broker account, then require typed confirmation. |
+| Listening off | POST `user/strategy/unsubscribe/<id>/` | Disarms. Returns 503 and leaves state unchanged if Redis fails. |
+| Save sizing config | PUT/PATCH `user/strategy/config/<id>/` `{personal_config}` or `{strategy_params, execution}` | Changes order size. **Any save after the first turns listening off** — say so. Validate against `strategy_schema` + `enabled_execution_keys` locally first. |
+| Broker connect wizard | POST `container/<cid>/connect/` `{step, broker_id, broker_credentials}` | Secrets: moomoo/futu password (the frontend MD5-hashes it, then RSA-encrypts it with the key from `user/kms/public-key/`); tiger private key; webull and schwab app_secret; ibkr password. Prompt for secrets and never take them from argv. Prompts can be built from the catalog's `login_fields`. Schwab uses OAuth: `oauth_start` → paste the redirect URL → `oauth_callback`. |
+| Trading PIN | POST `container/<cid>/unlock_trade/` `{trading_password}` | Secret; prompt only. |
+| Container start / restart / stop | POST `user/container/start/` (Pro), `container/<cid>/restart/` `{"mode":"in_place"}`, `user/container/stop/` | Stop returns 409 while the broker is connected. |
+| Container reset | POST `container/<cid>/reset/` | **Destructive:** wipes stored broker credentials. Typed confirmation. |
+| Broker health | GET `container/<cid>/broker_token_status/`, POST `…/ping/`, GET/POST `…/broker-disconnect-notice/[ack/]` | Read-mostly; low risk. Good next step. |
+| Webhook strategies (`wh_…`) | `webhook-strategies/` CRUD, `samples/`, `submit/`, `acknowledge/`, `rotate-secret/`, `deliveries/` (Pro + `WEBHOOK_STRATEGIES` flag) | Create and rotate return the secret once; print it once and never log it. |
+| Pro research reads | GET `nexus-agent/backtest|market-analysis/?ticker=`, `portfolio-recommendation/`, `wall-bot/triggers|price|nav/` | Read-only, Pro. Easy. |
+| Research jobs / KB files | `research/analysis-jobs/*`, `research/kb-files/*` | `run` spends platform LLM budget. |
+| Docs | GET `docs/nav/`, `docs/articles/<slug>/`, `docs/search/?q=` | Read-only. |
+
+## Do not wrap
+
+- **Stubs or mock data:** `user/opend/*` (fake stubs; `login` writes the verification code into the activity log) and `user/cognito/<sub>/strategies/` (mock).
+- **Legacy / dead:** `signal/*`. Its table is empty in prod, and `signal/<id>/retry/` has no ownership check.
+- **Too broad:** `logs/strategy/` exposes platform-wide logs, and `logs/filter-options/` lists every username. These are backend issues, not CLI material.
+- **Superseded:** the old DDD `container/list|detail|start|stop|delete`. The frontend uses the endpoints listed above instead.
+- **Billing:** there is none in nexus-service (`apps/subscriptions` is not routed). The tier lives on Cognito attributes, and the CLI can only report it.

nexusquant_cli-0.4.0/nexusquant_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"