mt5cli 0.1.0__tar.gz

mt5cli-0.1.0/.agents/skills/local-qa/SKILL.md

@@ -0,0 +1,25 @@
+# local-qa
+
+Run local QA checks (format, lint, test) on the repository.
+
+## When to use
+
+After making changes to repository files, run `scripts/qa.sh` to validate formatting, linting, and tests.
+
+## Steps
+
+1. Execute `scripts/qa.sh` and capture the results.
+2. Report successes, failures, warnings, and any modified files.
+
+## If tools are missing
+
+Install them following this priority order:
+
+1. Project package managers (`uv`, `poetry`, npm scripts)
+2. System package managers (`brew`, `apt`)
+3. Language-specific installers (`pipx`, `pip`, `npm`, `go install`)
+
+## Constraints
+
+- Only execute QA and tool-installation commands.
+- If installation fails or requires unavailable privileges, report the attempt and exact failure, then stop.

mt5cli-0.1.0/.agents/skills/local-qa/scripts/qa.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+set -euox pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+# Python
+uv run ruff format .
+uv run ruff check --fix .
+uv run pyright .
+uv run pytest
+
+# Markdown
+npx -y prettier --write './**/*.md'
+
+# GitHub Actions
+zizmor --fix=safe .github/workflows
+git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
+git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
+checkov --framework=all --output=github_failed_only --directory=.

mt5cli-0.1.0/.agents/skills/mt5cli/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: mt5cli
+description: Use the `mt5cli` CLI to export MetaTrader 5 data (rates, ticks, account, symbols, orders, positions, history) to CSV, JSON, Parquet, or SQLite3. Invoke when the user asks to export, dump, download, or fetch MT5 market data or account data to a file.
+---
+
+# mt5cli
+
+Export MetaTrader 5 data to CSV, JSON, Parquet, or SQLite3 via the `mt5cli`
+command. Output format is auto-detected from the file extension (`.csv`,
+`.json`, `.parquet`/`.pq`, `.db`/`.sqlite`/`.sqlite3`) or overridden with
+`--format/-f`.
+
+## Requirements
+
+- Python 3.11+ on Windows with MetaTrader 5 installed (pdmt5 requires the
+  MT5 terminal).
+- Install: `pip install -U mt5cli MetaTrader5`.
+- In this repo, run via `uv run mt5cli ...` or `uv run python -m mt5cli ...`.
+
+## Invocation shape
+
+```
+mt5cli [GLOBAL OPTIONS] -o OUTPUT COMMAND [COMMAND OPTIONS]
+```
+
+Global options MUST precede the subcommand.
+
+### Global options (apply to every subcommand)
+
+| Option                | Purpose                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `-o, --output PATH`   | Output file path (required).                                  |
+| `-f, --format FORMAT` | `csv`, `json`, `parquet`, or `sqlite3` (auto from extension). |
+| `--table NAME`        | Table name for SQLite3 output (default: `data`).              |
+| `--login INT`         | MT5 trading account login.                                    |
+| `--password TEXT`     | MT5 trading account password.                                 |
+| `--server TEXT`       | MT5 trading server name.                                      |
+| `--path TEXT`         | Path to MetaTrader 5 terminal EXE.                            |
+| `--timeout INT`       | Connection timeout in milliseconds.                           |
+| `--log-level LEVEL`   | `DEBUG`, `INFO`, `WARNING` (default), `ERROR`.                |
+
+### Parameter value formats
+
+- **Datetimes** (`--date-from`, `--date-to`): ISO 8601 (`2024-01-01` or
+  `2024-01-01T12:00:00+00:00`). Naive values are treated as UTC.
+- **Timeframe** (`--timeframe`): `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M10`,
+  `M12`, `M15`, `M20`, `M30`, `H1`, `H2`, `H3`, `H4`, `H6`, `H8`, `H12`,
+  `D1`, `W1`, `MN1`, or the raw integer.
+- **Tick flags** (`--flags`): `ALL`, `INFO`, `TRADE`, or the raw integer.
+
+## Commands
+
+| Command          | Required options                                      | Optional options                                                            |
+| ---------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
+| `rates-from`     | `--symbol`, `--timeframe`, `--date-from`, `--count`   | —                                                                           |
+| `rates-from-pos` | `--symbol`, `--timeframe`, `--start-pos`, `--count`   | —                                                                           |
+| `rates-range`    | `--symbol`, `--timeframe`, `--date-from`, `--date-to` | —                                                                           |
+| `ticks-from`     | `--symbol`, `--date-from`, `--count`, `--flags`       | —                                                                           |
+| `ticks-range`    | `--symbol`, `--date-from`, `--date-to`, `--flags`     | —                                                                           |
+| `account-info`   | —                                                     | —                                                                           |
+| `terminal-info`  | —                                                     | —                                                                           |
+| `symbols`        | —                                                     | `--group` (e.g., `*USD*`)                                                   |
+| `symbol-info`    | `--symbol`                                            | —                                                                           |
+| `orders`         | —                                                     | `--symbol`, `--group`, `--ticket`                                           |
+| `positions`      | —                                                     | `--symbol`, `--group`, `--ticket`                                           |
+| `history-orders` | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position` |
+| `history-deals`  | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position` |
+
+## Examples
+
+```bash
+# Account snapshot as CSV.
+mt5cli -o account.csv account-info
+
+# EURUSD M1 bars (1000 rows) from a start date to Parquet.
+mt5cli -o rates.parquet rates-from \
+  --symbol EURUSD --timeframe M1 --date-from 2024-01-01 --count 1000
+
+# EURUSD tick stream for a date range to JSON.
+mt5cli -o ticks.json ticks-range \
+  --symbol EURUSD --date-from 2024-01-01 --date-to 2024-01-02 --flags ALL
+
+# USD symbols into a named table in SQLite3.
+mt5cli -o data.db --table symbols symbols --group "*USD*"
+
+# Historical deals filtered by symbol (using an already-logged-in MT5 terminal).
+mt5cli -o deals.csv history-deals --symbol EURUSD --date-from 2024-01-01
+```
+
+## Guidelines
+
+- Pick the output extension to avoid passing `--format`.
+- Use `--table` only with SQLite3 outputs; it is otherwise ignored.
+- `--count` is required for `rates-from`, `rates-from-pos`, and `ticks-from`.
+  Prefer `rates-range` / `ticks-range` when a fixed window is known.
+- Credentials (`--login`, `--password`, `--server`) are optional when the
+  local MT5 terminal is already logged in.
+- Avoid passing `--password` on the command line in shared or logged
+  environments — it is visible in `ps`, shell history, and CI logs. Prefer
+  logging in through the MT5 terminal first, then omit credentials here.
+- Reach for `--log-level DEBUG` when a command fails silently — MT5
+  connection errors surface there.
+- If the user asks to run from source in this repo, prefix with `uv run`
+  (e.g., `uv run mt5cli -o out.csv account-info`).

mt5cli-0.1.0/.claude/agents/codex.md

@@ -0,0 +1,46 @@
+# Codex Agent
+
+Specialized Claude agent for autonomous development work using OpenAI's Codex CLI.
+
+## Modes
+
+### Ask Mode
+
+Read-only code analysis: answer questions about implementation, architecture, and debugging with specific file references and code examples.
+
+### Exec Mode
+
+Generate and modify code: create new components, refactor existing code, fix bugs, and write tests while maintaining quality standards.
+
+### Review Mode
+
+Comprehensive code review: identify security vulnerabilities, bugs, performance issues, and quality improvements without making changes.
+
+### Search Mode
+
+Research current documentation, best practices, solutions, and technology comparisons using web resources.
+
+## Core Requirements
+
+- Prioritize Codex CLI as the primary execution engine.
+- Ask, Review, and Search modes are read-only; only Exec mode modifies code.
+- All answers require verification:
+  - Ask mode must confirm file paths exist.
+  - Exec mode requires test passage and linting.
+  - Review mode needs severity prioritization.
+  - Search mode demands sourced citations.
+
+## Workflow
+
+1. Understand the task.
+2. Gather context from the codebase.
+3. Execute via Codex CLI with specific parameters.
+4. Verify results.
+5. Communicate findings with appropriate structure and detail.
+
+## Constraints
+
+- No hardcoded secrets.
+- Thorough testing.
+- Specific file references.
+- Honest communication about limitations.

mt5cli-0.1.0/.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/skills/local-qa/scripts/qa.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "code-simplifier@claude-plugins-official": true
+  }
+}

mt5cli-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+---
+github:
+  - dceoy

mt5cli-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+---
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 10
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: daily
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 10

mt5cli-0.1.0/.github/renovate.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "minimumReleaseAge": "7 days",
+  "packageRules": [
+    {
+      "description": "Automatically merge minor and patch-level updates",
+      "matchUpdateTypes": ["minor", "patch", "digest"],
+      "automerge": true,
+      "automergeType": "branch"
+    }
+  ]
+}

mt5cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+---
+name: CI/CD
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+  workflow_dispatch:  # checkov:skip=CKV_GHA_7:workflow_dispatch inputs are required for manual runs
+    inputs:
+      workflow:
+        required: true
+        type: choice
+        options:
+          - lint-and-test
+          - docs-deploy
+        description: Choose the workflow to run
+        default: lint-and-test
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash -euo pipefail {0}
+    working-directory: .
+jobs:
+  python-lint-and-scan:
+    if: >
+      github.event_name == 'push'
+      || github.event_name == 'pull_request'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: read
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      runs-on: windows-latest
+  python-test:
+    if: >
+      github.event_name == 'push'
+      || github.event_name == 'pull_request'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: read
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-test.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      runs-on: windows-latest
+  python-docs-deploy:
+    if: >
+      github.event_name == 'push'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'docs-deploy')
+    permissions:
+      contents: write
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-mkdocs-gh-deploy.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      mkdocs-theme: material
+      runs-on: ubuntu-slim
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  python-package-release:
+    if: >
+      github.event_name == 'push'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: write
+      id-token: write
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      create-releases: false
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  dependabot-auto-merge:
+    if: >
+      github.event_name == 'pull_request' && github.actor == 'dependabot[bot]'
+    needs:
+      - python-lint-and-scan
+      - python-test
+    uses: dceoy/gh-actions-for-devops/.github/workflows/dependabot-auto-merge.yml@main  # zizmor: ignore[unpinned-uses]
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: read
+    with:
+      unconditional: true

mt5cli-0.1.0/.github/workflows/claude.yml

@@ -0,0 +1,57 @@
+---
+name: Claude Code review and mention bot
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - ready_for_review
+  issue_comment:
+    types:
+      - created
+  pull_request_review_comment:
+    types:
+      - created
+  issues:
+    types:
+      - opened
+      - assigned
+  pull_request_review:
+    types:
+      - submitted
+permissions:
+  contents: read
+jobs:
+  claude-code-review:
+    if: >
+      github.event_name == 'pull_request'
+      && (! github.event.pull_request.draft)
+      && (! startsWith(github.head_ref, 'dependabot/'))
+      && (! startsWith(github.head_ref, 'renovate/'))
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    uses: dceoy/gh-actions-for-devops/.github/workflows/claude-code-review.yml@main  # zizmor: ignore[unpinned-uses]
+    secrets:
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # zizmor: ignore[secrets-outside-env]
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  claude-code-bot:
+    if: >
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude'))
+      || (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
+      || (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
+      || (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    uses: dceoy/gh-actions-for-devops/.github/workflows/claude-code-bot.yml@main  # zizmor: ignore[unpinned-uses]
+    secrets:
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # zizmor: ignore[secrets-outside-env]
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mt5cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+---
+name: Release
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash -euo pipefail {0}
+    working-directory: .
+jobs:
+  build:
+    permissions:
+      contents: write
+      id-token: write
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      package-path: .
+      create-releases: false
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  github-release:
+    name: Sign the Python 🐍 distribution 📦 with Sigstore and upload them to GitHub Release
+    if: >
+      startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: ${{ needs.build.outputs.distribution-artifact-name }}
+          path: dist/
+      - name: Validate the version-tag consistency
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+          NEEDS_BUILD_OUTPUTS_PROJECT_NAME: ${{ needs.build.outputs.project-name }}
+        run: |
+          v="$( \
+            find dist -type f -name "${NEEDS_BUILD_OUTPUTS_PROJECT_NAME}-*" -exec basename {} \; \
+              | head -n 1 \
+              | cut -d '-' -f 2 \
+          )"
+          v="${v%.tar.gz}"
+          if [[ "${TAG_NAME}" != "${v}" ]] && [[ "${TAG_NAME}" != "v${v}" ]]; then
+            echo "The tag (${TAG_NAME}) is inconsistent with the version (${v})." && exit 1
+          fi
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@04cffa1d795717b140764e8b640de88853c92acc  # v3.3.0
+        with:
+          inputs: >-
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}  # zizmor: ignore[secrets-outside-env] caller-provided secret
+        run: |
+          gh release create "${GITHUB_REF_NAME}" --repo "${REPOSITORY}" --generate-notes --verify-tag
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}  # zizmor: ignore[secrets-outside-env] caller-provided secret
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: |
+          gh release upload "${GITHUB_REF_NAME}" dist/** --repo "${REPOSITORY}"
+  publish-to-pypi:
+    name: Publish the Python 🐍 distribution 📦 to PyPI
+    if: >
+      startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+      - github-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ needs.build.outputs.project-name }}
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: ${{ needs.build.outputs.distribution-artifact-name }}
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          verbose: true