taprivo 0.1.0b4__tar.gz

taprivo-0.1.0b4/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json,md}]
+indent_size = 2

taprivo-0.1.0b4/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @yorulmazsinan

taprivo-0.1.0b4/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,35 @@
+name: Bug report
+description: Report a reproducible Taprivo problem
+title: "[Bug]: "
+labels: [bug, needs-triage]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Taprivo version and installation method
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: macOS version, Mac chip, camera and agent version
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include a simulator reproduction if possible. Do not upload camera footage or secrets.
+    validations:
+      required: true
+  - type: textarea
+    id: result
+    attributes:
+      label: Expected and actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Redacted diagnostics
+      description: Output of `taprivo doctor --json`. Review it before sharing; remove tokens and private paths.

taprivo-0.1.0b4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and ideas
+    url: https://github.com/yorulmazsinan/taprivo/discussions
+    about: Ask usage questions or discuss ideas in Discussions.

taprivo-0.1.0b4/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest a change or addition
+title: "[Feature]: "
+labels: [enhancement, needs-triage]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What is hard or missing today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: dropdown
+    id: phase
+    attributes:
+      label: Related roadmap phase
+      options: ["0.1 MVP", "0.2 Game engine", "0.3 Stats", "0.4 Calibration / adapters", "Not sure"]

taprivo-0.1.0b4/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What changes for the user?
+
+Describe the problem and the resulting behavior. Link the issue if relevant.
+
+## Validation
+
+List the tests or manual checks you ran and their results.
+For detector or energy changes, include false-positive and missed-tap observations.
+For HUD changes, attach a screenshot.
+
+## Compatibility and data
+
+Note any MCP schema, config, dependency, privacy or migration impact.
+Write "none" if there is no impact.

taprivo-0.1.0b4/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

taprivo-0.1.0b4/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - name: Install Qt and MediaPipe runtime libraries (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libegl1 libgl1 libxkbcommon0 libdbus-1-3 libfontconfig1 libglib2.0-0 libgles2
+      - name: Report runner architecture
+        run: uname -m
+      - name: Sync
+        run: uv sync --dev --locked
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy
+      - name: Test
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: uv run pytest -q
+      - name: Build wheel
+        run: uv build

taprivo-0.1.0b4/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check that the tag matches the package version
+        run: |
+          version=$(uv run --no-sync python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$version" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} does not match version $version"; exit 1; }
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/taprivo/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

taprivo-0.1.0b4/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+.DS_Store
+.idea/
+.vscode/
+.build/

taprivo-0.1.0b4/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        pass_filenames: false

taprivo-0.1.0b4/.python-version

@@ -0,0 +1 @@
+3.12

taprivo-0.1.0b4/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+Keep a Changelog and the project uses Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0b4] - 2026-09-09
+
+Beta preview with a signed macOS app and a PyPI package.
+
+### Added
+- Signed and notarized macOS app bundle (DMG, Apple Silicon) built with `packaging/macos/build.sh`; Gatekeeper assessment now runs after stapling and dangling symlinks left by trimmed Qt frameworks are pruned before signing.
+- Releases publish to PyPI automatically through trusted publishing; install with `uv tool install taprivo`.
+
+### Added
+- macOS packaging script: `packaging/macos/build.sh` builds a standalone `Taprivo.app` with PyInstaller and can sign it with a Developer ID, notarize it and wrap it in a DMG (`build`, `sign`, `notarize`, `dmg`, `all`). Apple Silicon only; see `packaging/macos/README.md`.
+
+## [0.1.0b3] - 2026-09-09
+
+Beta preview with a Cursor adapter, persistent statistics and a rhythm bonus.
+
+### Added
+- Steady-beat bonus: taps that hold an even tempo between 60 and 240 BPM are worth 1.25× more energy (`rhythm.steady_multiplier`), stacked on the combo multiplier. The HUD rate line shows the tempo and highlights it while the beat holds, `taprivo stats` prints a `Rhythm:` line, and `get_stats` reports `bpm`, `rhythm_steady` and `rhythm_multiplier`.
+- Cursor adapter: `taprivo setup cursor` registers the MCP endpoint in `~/.cursor/mcp.json` (mode 0600, backup first), `--install-instructions` writes `~/.cursor/taprivo.md` and, with `--project`, a `.cursor/rules/taprivo.mdc` rule; `taprivo remove cursor` undoes it and `taprivo doctor` reports the Cursor registration and instruction checks.
+- Project `.cursor/mcp.json` entries reference `${env:TAPRIVO_TOKEN}` instead of the literal token.
+- `--json` output for the `setup` and `remove` commands of both agents, which now share one code path.
+- Global install instructions: `uv tool install` (or pipx) from the tagged repository, with upgrade and uninstall commands.
+- Persistent statistics: each session and its daily totals are stored in `~/.config/taprivo/stats.sqlite` (counters and timestamps only, no spend reasons and no camera data), with a new `stats` config section (`enabled`, `path`).
+- `taprivo stats --today` and `taprivo stats --history [--days N]` read that file directly, so they work while Taprivo is not running; both support `--json`.
+- Plain `taprivo stats` shows a `Today:` line with the day's sessions, taps and energy.
+- MCP `get_stats` gained an additive `today` object (`sessions`, `taps_total`, `generated`, `spent`, `active_seconds`), null when statistics are disabled or the day is empty.
+
+## [0.1.0b2] - 2026-09-09
+
+Beta preview with two-hand keyboard drumming.
+
+### Added
+- Keyboard drumming with two hands: the left hand taps `1` `2` `3` `4` (pinky to index) and the right hand `7` `8` `9` `0` (index to pinky), with a chip per key in the HUD and per-hand counts in `get_stats` and `taprivo stats`.
+- A sliding one-second tap cap shared by both hands (`simulator.max_taps_per_second`, default 12); taps above it are ignored, and key auto-repeat never counts.
+- Combo multiplier tiers (`combo.tiers`, by default 1.5× from 10 consecutive taps and 2× from 25), shown on the HUD combo line and reported as `combo_multiplier` by `get_stats`.
+
+### Changed
+- The combo energy multiplier is on by default (`combo.energy_multiplier_enabled: true`); each tap is worth `energy_per_tap` times the multiplier the combo has reached.
+- Keys `1`–`5` no longer tap thumb…pinky of a single hand; the two-hand mapping replaces them, and keys `5` and `6` do nothing.
+- The HUD window is wider so that four key chips fit a row per hand.
+
+## [0.1.0b1] - 2026-09-09
+
+Beta preview. Install from source with `uv sync`; there is no signed
+macOS package yet.
+
+### Added
+- Camera-based squeeze detection (open → fist → open) with MediaPipe hand landmarks; two hands tracked independently; one squeeze counts as five taps (50 energy).
+- Camera window: device probing with no-signal detection, live preview, per-hand openness meters, guided calibration with session levels and feature-only CSV export.
+- Redesigned HUD and Camera window with a dark/light theme; new `hud.theme` config key (`system`, `dark`, `light`).
+- CLI: `taprivo camera list`, `taprivo calibrate`; `status` shows camera fps and hand detection ratio; `doctor` checks the bundled model, mediapipe and camera devices, and `doctor --camera-probe` opens the camera to check permission and measure processed fps.
+- MCP `get_session` fields `camera_fps` and `detection_ratio`.
+
+### Changed
+- Pin mediapipe to 0.10.33; a test fails if the installed wheel contains telemetry code.
+- Product framing: the camera counts whole-hand squeezes rather than per-finger taps; finger tapping stays with the keyboard simulator.
+- The squeeze detector ignores hands that are partly outside the camera frame (extrapolated fingers caused false cycles when a hand slid out of view).
+
+### Known limitations
+- Good lighting and a fully visible hand are needed; typing with hands in view can occasionally register a squeeze.
+
+## [0.1.0a1] - 2026-09-08
+
+Developer preview. Install from source with `uv sync`; there is no signed
+macOS package yet.
+
+### Added
+- Keyboard simulator producing tap events for thumb to pinky.
+- Energy engine with a 10,000 cap, overflow accounting, atomic spending and
+  per-session idempotency.
+- PySide6 HUD with energy bar, per-finger counts, combo, rate, MCP status.
+- Loopback MCP server (Streamable HTTP) with `get_energy`, `spend_energy`,
+  `get_stats`, `get_session`; bearer token, Host/Origin checks, rate limit.
+- CLI: `simulate`, `status`, `stats`, `setup claude`, `remove claude`, `doctor`.
+
+### Known limitations
+- No camera support yet; the balance resets when the app quits.
+- Only Claude Code is tested as an MCP client.
+
+[Unreleased]: https://github.com/yorulmazsinan/taprivo/compare/v0.1.0b4...HEAD
+[0.1.0b4]: https://github.com/yorulmazsinan/taprivo/releases/tag/v0.1.0b4
+[0.1.0b3]: https://github.com/yorulmazsinan/taprivo/releases/tag/v0.1.0b3
+[0.1.0b2]: https://github.com/yorulmazsinan/taprivo/releases/tag/v0.1.0b2
+[0.1.0b1]: https://github.com/yorulmazsinan/taprivo/releases/tag/v0.1.0b1
+[0.1.0a1]: https://github.com/yorulmazsinan/taprivo/releases/tag/v0.1.0a1

taprivo-0.1.0b4/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at info@sinanyorulmaz.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

taprivo-0.1.0b4/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Taprivo
+
+Thanks for helping. You do not need a camera to contribute: the keyboard
+simulator drives the full tap → energy → HUD → MCP path.
+
+## Set up
+
+```bash
+uv sync --dev
+uv run taprivo simulate
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+## Workflow
+
+1. Start with the simulator and read `README.md`.
+2. Pick a small issue. For larger changes, open an issue first to discuss the design.
+3. Create a branch, change the behaviour, and run the related tests.
+4. HUD changes: attach a screenshot. Detector or energy changes: add a
+   synthetic fixture or a unit test that shows the before/after behaviour.
+5. Detector or calibration changes: run the manual protocol in
+   `tests/manual/camera-matrix.md` and paste the numbers into the PR.
+6. In the PR, describe the user-visible effect and how you verified it.
+
+## Ground rules
+
+- Keep camera frames, landmarks, tokens and private paths out of logs, tests
+  and issues. Raw camera recordings are never required for a contribution.
+- `core/` stays free of Qt and MCP imports.
+- `vision/` never imports Qt or `mcp/`; mediapipe is imported lazily inside
+  `vision/tracker.py` only. Detector or calibration changes must keep the
+  pinned fixtures in `tests/fixtures/landmarks/` (`*.csv` + `*.events.json`)
+  deliberately regenerated and reviewed.
+- `src/taprivo/ui/app.py` is the composition root and the only `ui/` module
+  allowed to import from `mcp/`; `mcp/` never imports `ui/`.
+- Public contract changes (CLI JSON, MCP schemas, config keys) need a note in
+  `CHANGELOG.md` and, for anything non-additive, an issue labelled `rfc`.
+- Contributions are accepted under the project's Apache-2.0 license. Tool-assisted
+  contributions are welcome; the contributor is responsible for verifying them.
+
+## Labels
+
+`bug`, `enhancement`, `documentation`, `good first issue`, `help wanted`,
+`needs-triage`, `area:vision`, `area:mcp`, `area:hud`, `area:cli`,
+`platform:macos`, `phase:1`, `phase:2`.
+
+## Releases
+
+A maintainer bumps the version, tags `vX.Y.Z` and publishes a GitHub release; the `Publish` workflow then builds the sdist and wheel and uploads them to PyPI through trusted publishing (no API tokens are stored in the repository).

taprivo-0.1.0b4/GOVERNANCE.md

@@ -0,0 +1,10 @@
+# Governance
+
+Taprivo is maintained by its founding maintainer, who has the final say on
+design and releases. Small changes go through pull requests; changes to the
+MCP contract, transports or privacy behaviour go through an issue labelled
+`rfc` before implementation.
+
+Additional maintainers are added based on sustained contribution and review
+history. Release permissions stay with a small group. There is no CLA;
+contributions are accepted under the project license.