@kuandotdev/indicator 0.1.2 → 0.1.3

package/project/README.md

@@ -0,0 +1,419 @@
+# Indicator
+
+**TradingView integration for agents and humans.**
+PineScript authoring (skill) + market data (Python) + browser automation (Playwright),
+exposed as both a **terminal CLI** (`training-view ...`) and **MCP servers** for Claude/Cursor/pi/Cline.
+
+```
++--------------------------------------------------------------+
+|                      Agent (Claude)                          |
+|                                                              |
+|   #2 Pine v6 skill ---> authors .pine files locally          |
+|   #3 data MCP / CLI --> OHLCV + screener + ratings           |
+|   #5 browser MCP/CLI -> paste into TV, save, screenshot      |
++--------------------------------------------------------------+
+                          |
+                          v
+              Your TradingView Premium account
+```
+
+---
+
+## Quick start
+
+```bash
+make install             # idempotent core install + terminal wizard for .env, login, agent/MCP setup
+
+make rating SYMBOL=NASDAQ:TSLA
+make screenshot SYMBOL=NASDAQ:TSLA
+make push SCRIPT=scripts/indicators/example_rsi_bands.pine APPLY=NASDAQ:TSLA SHOT=1
+```
+
+For a visual, local-only integration guide, open:
+
+```bash
+open docs/integration.html
+```
+
+> Runtime screenshots are intentionally **not committed**. The repository tracks
+> only `screenshots/.gitkeep`; generated `screenshots/*.png` files stay local.
+
+---
+
+## What's inside
+
+| Path | What |
+|---|---|
+| `skills/pinescript-v6/` | **Canonical Pine v6 skill** (edit here); reference + templates + v5->v6 migration |
+| Market prompt skills | Protected market-analysis startup behavior and local-development update workflow |
+| `skills/agent-docs/` | Skill for agents to read the skill/MCP capability directory |
+| `docs/agent-skill-directory.md` | Generated directory of available skills, MCP tools, and routing rules |
+| `docs/agent-install.md` | Step-by-step installation/setup guide written for AI agents (Pi/Claude/Codex/Gemini/Cursor) |
+| `.claude/skills/`, `.pi/agent/skills/`, `.pi/skills/` | Symlinks into canonical skills for Claude Code / pi |
+| Pi startup context | Generated Pi agent startup context |
+| `.cursor/rules/*.mdc` | Cursor rules (auto-generated thin pointers to canonical skills) |
+| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` | Project-root agent instructions/startup prompt (auto-generated) for Codex/OpenCode/Aider/Claude/Gemini |
+| `tools/install_skills.sh` | Idempotent installer that wires skills/startup files into all agent dirs |
+| `tools/interactive_install.sh` | New-user terminal wizard for platform selection, optional .env values, login, and agent/MCP import |
+| `tools/import_agent_tools.sh` | Detects/configures Pi/Claude Desktop/Claude Code/Codex/Gemini/Cursor package/context/MCP tooling |
+| `src/tv_indicator/data/` | OHLCV via `tvdatafeed`, screener + ratings via `tradingview-screener` |
+| `src/tv_indicator/browser/` | Playwright flows: login, push script, screenshot |
+| `src/tv_indicator/model/` | Server-side stock/ETF/index forecast API client |
+| `src/tv_indicator/cli/` | `training-view` CLI (Typer + Rich) |
+| `src/tv_indicator/mcp/` | MCP servers exposing the same functions as the CLI |
+| `scripts/{indicators,strategies}/` | Your Pine source of truth (git-tracked) |
+| `docs/integration.html` | Local static visual guide showing how CLI, agents, MCP, data, browser automation, and Pine files connect |
+| `screenshots/` | Browser screenshots (gitignored except `screenshots/.gitkeep`) |
+| `Makefile` | All workflows: install, run, lint, skills, clean |
+| `conda-env-active.sh` / `conda-env-deactive.sh` | Standalone env scripts (sourced) |
+
+---
+
+## Install (conda + make)
+
+Prereq: [Miniforge](https://github.com/conda-forge/miniforge) (or Miniconda / Anaconda).
+
+```bash
+# The one command. Idempotent — safe to re-run anytime.
+# Creates the conda env if missing, installs deps, then opens an interactive
+# wizard for language, agent selection, TradingView login, and MCP config.
+make install
+
+# Verify everything:
+make doctor
+```
+
+> Edge cases: pass `FORCE_INSTALL=1` only when you need to force a re-pip-install
+> (corrupted env, manual `pyproject.toml` edits). Normal upgrades don't need it.
+
+Local development reinstall path:
+
+```bash
+make uninstall
+make install FORCE_INSTALL=1
+make agent-import PLATFORM=auto
+make check-skills
+```
+
+Published package install path for normal users:
+
+```bash
+npx @kuandotdev/indicator install
+npx @kuandotdev/indicator install --force
+```
+
+When run outside an existing checkout, the npm wrapper clones this repo into
+`~/.indicator` first. Override with `TV_INDICATOR_INSTALL_DIR=/path/to/indicator`.
+
+To use the `training-view` CLI directly in your shell (without `make` or `conda run`):
+
+```bash
+source conda-env-active.sh tv-indicator
+
+training-view status
+training-view data ohlcv NASDAQ:AAPL --bars 50
+```
+
+When done:
+
+```bash
+conda deactivate
+# Or to wipe the env entirely (mirrors skin_type_regonize_model's pattern):
+source conda-env-deactive.sh tv-indicator
+```
+
+### TradingView login / `.env`
+
+`make install` creates `.env` if needed, detects the preferred agent output language from the terminal locale (`LC_ALL`, `LC_MESSAGES`, `LANG`; fallback `en`), supports common codes such as `en`, `zhtw`, `zhcn`, `jp`, and `ko`, and skips optional API/session values unless you opt in with `TV_INSTALL_PROMPT_ENV=1`.
+
+Preferred login path: let Playwright capture a persistent browser profile during setup. You can rerun manually:
+
+```bash
+make login            # opens a visible Chromium window; log in once
+make session-check    # should now show signed_in: true
+```
+
+### Model forecast API
+
+The stock/ETF/index forecast model runs server-side. Configure the client with:
+
+```env
+TV_MODEL_API_URL=https://model.example/forecast
+TV_MODEL_API_KEY=optional-bearer-token
+```
+
+Then verify with `make model-status` and fetch with `make model-forecast SYMBOL=NASDAQ:TSLA MODEL_JSON=1`.
+
+---
+
+## Usage -- two equivalent paths
+
+Everything has both a **`make` shortcut** and the underlying **`training-view` CLI command**.
+
+### Via Make (no need to activate conda)
+
+```bash
+make status
+make doctor
+make agent-import PLATFORM=auto                 # detect/import supported tooling
+make agent-import PLATFORM=pi,claude-code       # configure specific agents
+
+# Data
+make ohlcv  SYMBOL=NASDAQ:AAPL INTERVAL=1D BARS=500
+make search Q=tesla
+make rating SYMBOL=NASDAQ:AAPL
+make screener MARKET=america FILTER='RSI < 30' LIMIT=30
+
+# Server-side model forecast (requires TV_MODEL_API_URL)
+make model-status
+make model-forecast SYMBOL=NASDAQ:TSLA MODEL_JSON=1
+
+# Pine scaffolding
+make pine-new KIND=indicator NAME=my_rsi
+make pine-new KIND=strategy  NAME=momentum_breakout
+make pine-new KIND=webhook   NAME=trend_follower
+make pine-list
+make pine-validate SCRIPT=scripts/indicators/my_rsi.pine
+
+# Browser
+make login                                          # one-time interactive login
+make session-check
+make push SCRIPT=scripts/indicators/my_rsi.pine APPLY=NASDAQ:AAPL SHOT=1
+make screenshot SYMBOL=NASDAQ:TSLA
+
+# MCP servers (foreground, for debugging)
+make mcp-data
+make mcp-browser
+make mcp-agent
+
+# Print config snippets to register with Claude Desktop / pi
+make agent-import PLATFORM=auto      # writes supported MCP configs automatically
+make mcp-config-claude               # print Claude Desktop snippet only
+make mcp-config-pi                   # print Pi snippet only
+```
+
+Run `make help` for the full list.
+
+### Via the `training-view` CLI directly
+
+After `source conda-env-active.sh tv-indicator`:
+
+```bash
+training-view status
+training-view version
+
+training-view data ohlcv NASDAQ:AAPL --interval 1D --bars 500
+training-view data ohlcv NASDAQ:AAPL -i 1H -n 200 --csv aapl.csv
+training-view data search "tesla"
+training-view data screener -m america -f "RSI < 30" -c name -c close -c RSI -n 30
+training-view data rating NASDAQ:AAPL
+
+training-view model status
+training-view model forecast NASDAQ:TSLA --json
+
+training-view pine new indicator my_rsi
+training-view pine validate scripts/indicators/my_rsi.pine
+training-view pine show scripts/indicators/my_rsi.pine
+
+training-view browser login
+training-view browser session-check
+training-view browser push scripts/indicators/my_rsi.pine --apply NASDAQ:AAPL --screenshot
+training-view browser screenshot --symbol NASDAQ:TSLA
+```
+
+---
+
+## MCP server setup
+
+The same functions are exposed as MCP servers. Register them in your agent's config.
+
+The easiest way is to let `make` generate the snippet with the correct absolute path
+to your conda-installed entry points:
+
+```bash
+make mcp-config-claude        # prints JSON for Claude Desktop
+make mcp-config-pi            # prints TOML for pi
+```
+
+### Claude Desktop (manual)
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "training-view-data": {
+      "command": "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-data",
+      "env": { "TV_SESSIONID": "paste-here", "TV_MODEL_API_URL": "https://model.example/forecast" }
+    },
+    "training-view-browser": {
+      "command": "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-browser",
+      "env": { "TV_SESSIONID": "paste-here", "TV_BROWSER_HEADLESS": "true" }
+    },
+    "training-view-agent": {
+      "command": "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-agent"
+    }
+  }
+}
+```
+
+Find the absolute path with:
+
+```bash
+conda run -n tv-indicator which training-view-mcp-data
+conda run -n tv-indicator which training-view-mcp-agent
+```
+
+### pi (manual)
+
+Add to `.pi/config.toml` or your global pi config:
+
+```toml
+[mcp_servers.training-view-data]
+command = "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-data"
+env = { TV_SESSIONID = "...", TV_MODEL_API_URL = "https://model.example/forecast" }
+
+[mcp_servers.training-view-browser]
+command = "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-browser"
+env = { TV_SESSIONID = "...", TV_BROWSER_HEADLESS = "true" }
+
+[mcp_servers.training-view-agent]
+command = "/abs/path/to/conda/envs/tv-indicator/bin/training-view-mcp-agent"
+```
+
+### MCP tools exposed
+
+| Server | Tool | Args |
+|---|---|---|
+| `training-view-data` | `get_ohlcv` | symbol, interval, n_bars, exchange, extended_session |
+| `training-view-data` | `search_symbol` | query, limit |
+| `training-view-data` | `screener` | market, columns, filters, order_by, limit |
+| `training-view-data` | `technical_rating` | symbol, interval |
+| `training-view-data` | `model_forecast` | symbol, refresh, period |
+| `training-view-browser` | `session_check` | -- |
+| `training-view-browser` | `push_script` | script_path, apply_to, screenshot, script_name |
+| `training-view-browser` | `screenshot_chart` | symbol, layout_url, out_path |
+| `training-view-agent` | `list_skills` | -- |
+| `training-view-agent` | `read_agent_docs` | -- |
+| `training-view-agent` | `read_install_docs` | -- |
+| `training-view-agent` | `get_prompt_status` | -- |
+| `training-view-agent` | `init_custom_stock_prompt` | local dev only, requires `TV_AGENT_ENABLE_PROMPT_WRITE=1` |
+| `training-view-agent` | `set_custom_stock_prompt` | local dev only, requires `TV_AGENT_ENABLE_PROMPT_WRITE=1` |
+| `training-view-agent` | `append_custom_stock_prompt` | local dev only, requires `TV_AGENT_ENABLE_PROMPT_WRITE=1` |
+| `training-view-agent` | `reset_custom_stock_prompt` | local dev only, requires `TV_AGENT_ENABLE_PROMPT_WRITE=1` |
+| `training-view-agent` | `apply_stock_prompt` | local dev only, requires `TV_AGENT_ENABLE_PROMPT_WRITE=1` |
+
+---
+
+## The Pine v6 skill
+
+`skills/pinescript-v6/SKILL.md` is the **canonical source of truth** — edit it
+there, and every agent's discovery point updates automatically.
+
+What it supplies:
+
+- Pine v6 language reference (`reference/v6-language.md`)
+- Built-in namespaces cheat sheet (`reference/built-ins.md`)
+- v5 -> v6 migration rules (`reference/v5-to-v6-migration.md`)
+- Validation checklist
+- Templates for indicators, strategies, and webhook-emitting strategies
+
+### One install, many agents
+
+The project ships with `tools/install_skills.sh` (wrapped by
+`make install-skills`) that wires the canonical skill into every supported
+agent's convention:
+
+| Agent / tool | Discovery path | Mechanism |
+|---|---|---|
+| **Claude Code** | `.claude/skills/pinescript-v6/SKILL.md` | symlink |
+| **pi** | `.pi/agent/skills/pinescript-v6/SKILL.md` | symlink |
+| **Cursor** | `.cursor/rules/pinescript-v6.mdc` | generated thin pointer (with `@`-include of SKILL.md) |
+| **Codex CLI / OpenCode / Aider** | `AGENTS.md` (project root) | generated, includes link + project conventions |
+| **Gemini CLI** | `GEMINI.md` (project root) | generated, same content |
+| **Claude Code (user-global)** | `~/.claude/skills/pinescript-v6/` | symlink, opt-in via `make install-skills-global` |
+
+First-time setup:
+
+```bash
+make install-skills            # project-local for all agents
+make install-skills-global     # also adds ~/.claude/skills/ symlink
+make check-skills              # verify everything is wired
+```
+
+Update cycle (after editing the canonical skill):
+
+```bash
+# 1. Edit the source
+$EDITOR skills/pinescript-v6/SKILL.md
+# 2. Refresh autogen files (symlinks were already live)
+make update-skills
+```
+
+Removal:
+
+```bash
+make uninstall-skills          # removes managed symlinks + autogen files
+```
+
+### How updates propagate
+
+- **Symlinked locations** (`.claude/skills/`, `.pi/agent/skills/`, user-global):
+  changes to `skills/pinescript-v6/` are visible **instantly** — no command
+  needed. The next time the agent reads the skill, it sees the new content.
+- **Generated files** (`.cursor/rules/*.mdc`, `AGENTS.md`, `GEMINI.md`):
+  these contain a static template that points at the canonical skill. They
+  rarely need to change after the first install. Run `make update-skills`
+  whenever you want to refresh them (e.g. after editing the script that
+  generates them or after a Pine skill rename).
+- **Respect for hand edits**: if you remove the `<!-- AUTOGENERATED BY ... -->`
+  marker from `AGENTS.md`, `GEMINI.md`, or the `.mdc` file, the installer
+  treats it as user-owned and never overwrites it. To re-auto-generate, simply
+  delete the file and re-run `make update-skills`.
+
+---
+
+## Project conventions (parity with skin_type_regonize_model)
+
+This project follows the same environment conventions as the
+`skin_type_regonize_model` repo in this workspace:
+
+- **Conda + Miniforge** for the Python env (no venv).
+- `conda-env-active.sh <env-name>` -- create + activate + install deps. Sourced.
+- `conda-env-deactive.sh <env-name>` -- deactivate + remove env. Sourced.
+- `Makefile` with `.DEFAULT_GOAL := help`, sectioned by feature.
+- All run commands flow through `conda run -n $(CONDA_ENV)` so users don't need to
+  pre-activate the env when using `make`.
+- Python version pinned via `TV_PYTHON_VERSION` env (default `3.11`).
+
+If you're already used to that repo, the workflow here is identical:
+`make install`, `source conda-env-active.sh ENV`, etc.
+
+---
+
+## Caveats / risks
+
+1. **`tvdatafeed` violates TradingView's ToS** in letter. Enforcement against personal
+   use is rare but not zero. Use at your own risk; for production, use a real data
+   provider (Polygon, Alpaca, IBKR).
+2. **Session cookies expire** (~2 weeks). Re-export from your browser.
+3. **Pine Editor DOM changes** can break Playwright selectors. Fix them in
+   `src/tv_indicator/browser/selectors.py` -- one place.
+4. **No PineScript upload API.** Browser automation is the only path; it's slower and
+   more brittle than a real API would be.
+5. **Premium features** (multiple alerts, fast data, custom timeframes) need a paid
+   TradingView plan -- Indicator doesn't grant them.
+6. **Don't auto-publish indicators publicly.** Drafts and chart application are fine;
+   public publishing is a manual decision.
+
+---
+
+## Roadmap / not yet built
+
+- [ ] Webhook receiver server (for Pro+ alert -> broker pipeline)
+- [ ] Backtester that runs Pine-equivalent logic in Python (vectorbt) for offline iteration
+- [ ] Auto-screenshot diff (compare before/after when editing an indicator)
+- [ ] Alerts-config sync (set up alert rules via Playwright)
+- [ ] Pine v6 LSP / proper syntax linter
+
+PRs / suggestions welcome.

package/project/conda-env-active.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Create (if needed), activate a conda environment, and install project dependencies.
+# Usage: source conda-env-active.sh <env-name>
+#
+# Must be sourced (not executed) so that `conda activate` affects the current shell.
+_CONDA_ACTIVE_OLDOPTS=$(set +o)   # snapshot current shell options
+set -eo pipefail
+
+# -------------------------------------------------------------------------
+# 1. Parameter handling
+# -------------------------------------------------------------------------
+ENV_NAME="${1:-}"
+if [[ -z "${ENV_NAME}" ]]; then
+    echo "ERROR: Environment name is required."
+    echo "Usage: source $0 <env-name>"
+    return 1 2>/dev/null || exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PYTHON_VERSION="${TV_PYTHON_VERSION:-3.11}"
+
+# -------------------------------------------------------------------------
+# 2. Prereq check
+# -------------------------------------------------------------------------
+if ! command -v conda &>/dev/null; then
+    echo "ERROR: conda not found. Install Miniforge / Miniconda first."
+    echo "  Recommended (macOS):  brew install miniforge"
+    echo "  Or download from:     https://github.com/conda-forge/miniforge"
+    return 1 2>/dev/null || exit 1
+fi
+
+# -------------------------------------------------------------------------
+# 3. Create env if it doesn't exist
+# -------------------------------------------------------------------------
+if conda env list | awk '{print $1}' | grep -qx "${ENV_NAME}"; then
+    echo "Conda env '${ENV_NAME}' already exists. Skipping creation."
+else
+    echo "Creating conda env '${ENV_NAME}' (python=${PYTHON_VERSION})..."
+    conda create -y -n "${ENV_NAME}" python="${PYTHON_VERSION}"
+fi
+
+# -------------------------------------------------------------------------
+# 4. Activate
+# -------------------------------------------------------------------------
+eval "$(conda shell.bash hook 2>/dev/null)"
+conda activate "${ENV_NAME}"
+hash -r 2>/dev/null || true
+echo "Activated conda env '${ENV_NAME}'."
+
+# -------------------------------------------------------------------------
+# 5. Install the project (editable) + optional extras
+#
+#    SKIP_INSTALL=1   skip pip install entirely
+#    EXTRAS=...       which extras to install (default: "data,dev")
+#                     valid: data | dev | model | data,dev | all
+#    SKIP_PLAYWRIGHT=1 skip `playwright install chromium`
+# -------------------------------------------------------------------------
+EXTRAS="${EXTRAS:-data,dev}"
+
+if [[ "${SKIP_INSTALL:-0}" != "1" ]]; then
+    echo "Installing tv-indicator (editable) with extras '[${EXTRAS}]'..."
+    python -m pip install --upgrade pip >/dev/null
+    python -m pip install -e "${SCRIPT_DIR}[${EXTRAS}]"
+else
+    echo "SKIP_INSTALL=1 set — skipping pip install."
+fi
+
+if [[ "${SKIP_PLAYWRIGHT:-0}" != "1" ]]; then
+    if python -c "import playwright" &>/dev/null; then
+        echo "Installing Playwright Chromium browser (if missing)..."
+        python -m playwright install chromium
+    else
+        echo "WARNING: playwright not installed yet — skipping browser download."
+    fi
+else
+    echo "SKIP_PLAYWRIGHT=1 set — skipping browser download."
+fi
+
+# -------------------------------------------------------------------------
+# 6. Summary
+# -------------------------------------------------------------------------
+PYTHON_VER="$(python --version 2>&1)"
+PKG_COUNT="$(python -m pip list --format=columns 2>/dev/null | tail -n +3 | wc -l | tr -d ' ')"
+
+echo ""
+echo "=== Environment Ready ==="
+echo "  Env name: ${ENV_NAME}"
+echo "  Python:   ${PYTHON_VER}"
+echo "  Packages: ${PKG_COUNT} installed"
+echo ""
+echo "Try:"
+echo "  training-view status"
+echo "  training-view data ohlcv NASDAQ:AAPL --bars 50"
+echo ""
+
+# Restore original shell options so set -e doesn't leak into interactive shell
+eval "${_CONDA_ACTIVE_OLDOPTS}"
+unset _CONDA_ACTIVE_OLDOPTS

package/project/conda-env-deactive.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Deactivate and remove a conda environment.
+# Usage: source conda-env-deactive.sh <env-name>
+#
+# Must be sourced (not executed) so that `conda deactivate` affects the current shell.
+_CONDA_DEACT_OLDOPTS=$(set +o)   # snapshot current shell options
+set -eo pipefail
+
+# -------------------------------------------------------------------------
+# 1. Parameter handling
+# -------------------------------------------------------------------------
+ENV_NAME="${1:-}"
+if [[ -z "${ENV_NAME}" ]]; then
+    echo "ERROR: Environment name is required."
+    echo "Usage: source $0 <env-name>"
+    return 1 2>/dev/null || exit 1
+fi
+
+# -------------------------------------------------------------------------
+# 2. Deactivate if currently active
+# -------------------------------------------------------------------------
+eval "$(conda shell.bash hook 2>/dev/null)"
+
+if [[ "${CONDA_DEFAULT_ENV:-}" == "${ENV_NAME}" ]]; then
+    echo "Deactivating conda env '${ENV_NAME}'..."
+    conda deactivate
+fi
+
+# -------------------------------------------------------------------------
+# 3. Remove environment
+# -------------------------------------------------------------------------
+if conda env list | awk '{print $1}' | grep -qx "${ENV_NAME}"; then
+    echo "Removing conda env '${ENV_NAME}'..."
+    conda env remove -y -n "${ENV_NAME}"
+    echo "Conda env '${ENV_NAME}' has been removed."
+else
+    echo "WARNING: Conda env '${ENV_NAME}' does not exist. Nothing to remove."
+fi
+
+# Restore original shell options
+eval "${_CONDA_DEACT_OLDOPTS}"
+unset _CONDA_DEACT_OLDOPTS