leetvault 0.1.0__tar.gz

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

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy strict
+        run: mypy --strict

leetvault-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build sdist + wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Dry-run: every tag push publishes to TestPyPI first. Real PyPI only follows if this
+  # succeeds, so a broken release never reaches real users.
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/leetvault
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/leetvault
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

leetvault-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.db
+*.sqlite3
+.env
+.claude/

leetvault-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-11
+
+Initial release.
+
+- `login`/`logout`/`status`: keyring-backed LeetCode session storage, live session validation,
+  JWT expiry decoding, optional GitHub PAT storage.
+- `import`/`sync`: resumable full-history import and incremental sync of accepted submissions,
+  same-day dedup (`--keep-all` to disable), REST + GraphQL enrichment.
+- Git layer: batched commit + transient-PAT push per run, never persisted to `.git/config`.
+- Auto-generated README dashboard: progress, difficulty/language/topic breakdowns, streaks,
+  recent solves, full searchable solutions table.
+- `watch`: polling loop with graceful shutdown and session-expiry warnings.
+- `config`: get/set persistent settings.
+
+[Unreleased]: https://github.com/priyadip/LeetVault/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/priyadip/LeetVault/releases/tag/v0.1.0

leetvault-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md — leetvault
+
+Project memory for Claude Code (auto-loaded each session). This file is authoritative. Keep the **Phase checklist** at the bottom updated as work completes.
+
+## What this is
+`leetvault` — a cross-platform (Windows/Linux/macOS) Python CLI that mirrors *my* LeetCode account (accepted submissions + source code + metadata) into a normalized SQLite DB and a GitHub repo with an auto-generated README dashboard. Sync is **account-based** via my authenticated session — never browser-dependent. My LeetCode account is the single source of truth. Free/OSS only; the only external services are LeetCode and GitHub.
+
+## v1 scope
+Commands: `login`, `import` (full history), `sync` (incremental), `watch` (polling), `status`, `logout`, `config`. Plus SQLite persistence, GitHub commit/push, auto-generated README, PyPI packaging + CI.
+**NOT in v1** (leave `# FUTURE:` notes only, build nothing): browser extension, AI/weak-topic dashboard, standalone binaries, deep contest analytics.
+
+## Ground-truth API facts — do NOT re-derive; verify exact field shapes live in Phase 2
+LeetCode has no official API — every endpoint is reverse-engineered. Isolate all LeetCode access behind one client module.
+
+**Auth**
+- Cookies `LEETCODE_SESSION` (a JWT) + `csrftoken`; I paste them at `login`. No password flow.
+- Every authed request sends: both cookies + header `x-csrftoken: <csrftoken>` + `Referer: https://leetcode.com`.
+- Decode the JWT `exp` for `status` + expiry warnings; don't hardcode a lifetime (varies ~1 wk to several wks).
+- Store secrets (both cookies + GitHub PAT) via **`keyring`**, service name `leetvault`. Never in `.env`, `.git/config`, logs, or commits.
+
+**Fetching**
+- Full history → REST `https://leetcode.com/api/submissions/?offset=0&limit=20` (20/page; includes `code`, `id`, `question_id`, `title`, `title_slug`, `status_display`, `lang`, `runtime`, `memory`, `timestamp`, `url`; top-level `has_next`/`last_key`). Prefer for bulk — code + metadata in one pass.
+- Enrichment/fallback → GraphQL `https://leetcode.com/graphql`: `submissionList(offset,limit,questionSlug)` + `submissionDetails(submissionId)` (code, runtimePercentile, memoryPercentile). One extra call per submission — use only when REST `code` is missing or percentiles are needed.
+- Incremental/watch → `recentAcSubmissions` / `recentSubmissionList` (capped at 20; detection only, useless for history).
+
+**Rate limits (empirical, not published — design defensively)**
+- ~480 sequential requests → HTTP 403. Stay under 20 req / 10 s.
+- Bulk import: 300–500 ms between pages; exponential backoff 1→3→9→27 s on 403/429; honor `Retry-After`.
+- **Import MUST be resumable** — persist last offset / submission id after every page.
+- GitHub write API has a **separate** quota — batch/space commits; never one push per submission.
+- `--site com|cn` (default `com`); for `cn` swap base URL + stricter limiter (~1 req/10 s).
+
+**Honest limits (state in docs, never fake)**
+- `watch` = polling (60–120 s), not real-time (no LeetCode webhook/streaming exists).
+- Cloudflare may challenge HTTP clients — fail gracefully; `# FUTURE:` optional Playwright real-browser fetcher.
+- Stored-cookie automation may breach LeetCode ToS — neutral README disclaimer.
+
+## Stack (exact)
+Typer (+`rich`) · `httpx` + **`httpx-retries`** (NOT `httpx-retry`) + custom rate limiter · SQLAlchemy 2.0 declarative (`DeclarativeBase`/`Mapped`/`mapped_column`/`select`) on SQLite · Jinja2 (`PackageLoader`) · GitPython (PAT injected transiently at push time, never in remote URL / `.git/config`; fine-grained PAT scoped to one repo, Contents: write) · `keyring` · `pytest`+cov / `ruff` / `mypy --strict` · **hatchling** + `src/` layout + entry point `leetvault = "leetvault.cli:app"` · **PyPI Trusted Publishing (OIDC)**. All config in `pyproject.toml`.
+
+## Data model (SQLite)
+`problems`(question_id PK, frontend_id, title, title_slug, difficulty, paid_only, url) · `submissions`(submission_id PK, question_id FK, lang, status, runtime, memory, runtime_percentile, memory_percentile, timestamp, code_hash, is_accepted) · `submission_code`(submission_id PK/FK, code) · `topics` + `problem_topics` (M2M) · `sync_state`(id, site, last_offset, last_submission_id, last_synced_timestamp, last_full_import_completed_at).
+History: store every accepted submission. Disk layout per problem: `Problems/<slug>/{latest.<ext>, history/submission_<id>.<ext>, notes.md, metadata.json}`. Default dedup = same problem within same day (86400 s); `--keep-all` opts out.
+
+## Working protocol
+- **Run continuously.** Execute Phases 0 → 7 end-to-end without pausing for my approval between phases. Never ask "should I proceed / continue / go ahead?" — just proceed. Don't stop per-file.
+- Per phase, loop: state what/why in 1–2 lines → build (full type hints, DI, SOLID, clean architecture) → tests green → `ruff check` + `ruff format --check` + `mypy --strict` clean → Conventional Commit → one-line progress note → immediately start the next phase.
+- **Only stop to ask me when you need something ONLY I can provide.** In v1 that is exactly two moments: (1) **Phase 2** — my `LEETCODE_SESSION` + `csrftoken` (I paste them into the `login` flow); (2) **Phase 4** — a fine-grained GitHub PAT + target repo URL (for push). Ask once at each, then continue autonomously. Also stop before any irreversible action *outside this repo* (force-push, history rewrite, deleting files you didn't create).
+- **Decide, don't ask, for everything else.** For small choices (naming, layout, library minutiae, config defaults) pick the sensible option, record it in `PLAN.md`, and keep moving. Surface a decision only if it's a true one-way door.
+- **Verify, don't assume:** confirm real REST + `submissionDetails` fields live in Phase 2 before locking schema; adapt to reality; note any divergence in `PLAN.md`.
+- **Never fake functionality** — no stubbed "pretend it worked," no fabricated data, no swallowed errors. If genuinely blocked, say so and propose a real fallback rather than faking or silently skipping.
+- Commit after every phase so all work is recoverable via git. Never print or commit secrets. Keep `PLAN.md` + `docs/ARCHITECTURE.md` current as you go.
+
+## Phase checklist (update as completed)
+- [x] **0 Scaffold** — `src/` layout, `pyproject.toml` (hatchling + deps + entry + ruff/mypy/pytest), command stubs, CI skeleton, `PLAN.md`, `docs/`. ✔ `pip install -e .` + `leetvault --help` lists all commands.
+- [x] **1 Data layer** — models, engine/session factory, `create_all`, `SyncState` helpers, unit tests + temp-DB round-trip.
+- [x] **2 Auth + client** — keyring store, httpx client (headers/timeouts/retries/limiter), JWT `exp`, session validation; `login`/`logout`/`status`. Verify live API. ✔ real-account `status` reports validity/expiry.
+- [x] **3 Sync engine** — `import` (resumable, throttled, backoff) + `sync` (incremental, stop at last-known id); dedup; DB + `submission_code` + disk files; progress bars; mocked tests + opt-in live smoke. ✔ full import correct + re-run does no redundant work.
+- [x] **4 Git** — layout writer, commit-template rendering, transient-PAT batched push. ✔ real push with correct messages, no dupes on re-run.
+- [x] **5 README** — Jinja2 templates + stats aggregation (progress, difficulty, topics, langs, streaks, recent, searchable table w/ links, % bars), regenerate-after-sync, aggregation-math tests.
+- [x] **6 Watch** — polling loop (`--interval`, 60–120 s), reconcile `SyncState`, run sync→write→README→commit→push on new AC, graceful shutdown, expiry warning. ✔ picks up a fresh solve within one interval.
+- [x] **7 Packaging/CI/docs** — finalize `pyproject.toml`; Actions (pytest matrix ubuntu/windows/macos × py3.11–3.13, `fail-fast:false`; ruff + `mypy --strict` on ubuntu; tag-triggered Trusted Publishing `id-token: write`, TestPyPI dry-run first); README + Install + Architecture + Developer + Contribution + FAQ + Troubleshooting. Workflows built and locally verified (wheel build + install, YAML validity, pytest/ruff/mypy all clean); **not yet run on GitHub's own runners** — this local repo has no GitHub remote configured for leetvault's own source (only for the separate solutions-mirror repo used in the Phase 4 live test), and PyPI Trusted Publisher setup is an account-level action only the repo owner can do. See PLAN.md Phase 7 for the exact gap and what's needed to close it.

leetvault-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for considering a contribution to leetvault.
+
+## Before you start
+
+- For anything beyond a small fix, open an issue first to discuss the approach - especially
+  for anything touching `client.py` (LeetCode's API is entirely reverse-engineered; changes
+  there need live verification, see [docs/DEVELOPER.md](docs/DEVELOPER.md)).
+- This project is free/open-source and intentionally scoped to LeetCode + GitHub as its only
+  external services. PRs adding new third-party services are unlikely to be accepted.
+
+## Workflow
+
+1. Fork and branch from `main`.
+2. Install dev dependencies: `pip install -e ".[dev]"`.
+3. Make your change. Match the existing style: full type hints, no comments unless they
+   explain a non-obvious *why*, no speculative abstraction.
+4. Before opening a PR, all of these must be clean:
+   ```bash
+   pytest
+   ruff check .
+   ruff format --check .
+   mypy --strict
+   ```
+5. Write a [Conventional Commit](https://www.conventionalcommits.org/) message
+   (`feat: ...`, `fix: ...`, `docs: ...`, etc.).
+6. Open a PR against `main`. CI runs the full matrix (Ubuntu/Windows/macOS × Python 3.11-3.13)
+   plus lint/type-check on every PR.
+
+## Reporting bugs
+
+Open a GitHub issue with:
+
+- your OS and Python version
+- the command you ran and its full output (`leetvault --help` output plus the failing command)
+- **never include your `LEETCODE_SESSION`, `csrftoken`, or GitHub PAT** in an issue - those are
+  credentials, not debug info
+
+## Security
+
+leetvault stores your LeetCode session cookies and GitHub PAT via the OS keyring, never in
+plaintext files, `.env`, `.git/config`, logs, or commits. If you find a way those could leak,
+please report it privately rather than opening a public issue - see
+[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for how credentials are handled.

leetvault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leetvault contributors
+
+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.

leetvault-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: leetvault
+Version: 0.1.0
+Summary: Mirror your LeetCode account (accepted submissions + source + metadata) into a normalized SQLite DB and a GitHub repo with an auto-generated README dashboard.
+Project-URL: Homepage, https://github.com/priyadip/LeetVault
+Project-URL: Repository, https://github.com/priyadip/LeetVault
+Project-URL: Issues, https://github.com/priyadip/LeetVault/issues
+Project-URL: Changelog, https://github.com/priyadip/LeetVault/blob/main/CHANGELOG.md
+Author: leetvault
+License: MIT
+License-File: LICENSE
+Keywords: backup,cli,github,leetcode,sqlite,sync
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1
+Requires-Dist: httpx-retries>=0.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=25.0
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: rich>=13.7
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# leetvault
+
+Mirror your LeetCode account (accepted submissions + source code + metadata) into a normalized
+SQLite database and a GitHub repository with an auto-generated README dashboard.
+
+Sync is **account-based**, driven by your authenticated LeetCode session — not a browser
+extension. Your LeetCode account is the single source of truth. Free and open source; the only
+external services involved are LeetCode and GitHub.
+
+## Install
+
+```bash
+pip install leetvault
+```
+
+Requires Python 3.11+. See [docs/DEVELOPER.md](docs/DEVELOPER.md) for an editable/dev install.
+
+## Quickstart
+
+```bash
+leetvault login                                          # paste LEETCODE_SESSION + csrftoken
+leetvault config repo_url https://github.com/you/repo.git # optional: enable GitHub push
+leetvault import                                          # one-time full history
+leetvault sync                                             # incremental, run anytime
+leetvault watch                                             # or: poll automatically
+```
+
+## Commands
+
+- `leetvault login` — store your `LEETCODE_SESSION` + `csrftoken` (and optionally a GitHub PAT)
+  in the OS keyring.
+- `leetvault import` — full history import of every accepted submission (resumable, one-time
+  per site).
+- `leetvault sync` — incremental sync of new accepted submissions since the last run.
+- `leetvault watch` — poll LeetCode and sync automatically (`--interval`, default 90s).
+- `leetvault status` — show session validity/expiry and sync state.
+- `leetvault logout` — remove stored credentials.
+- `leetvault config` — get/set persistent configuration (repo URL, DB path, dedup window, ...).
+
+## What gets stored
+
+A normalized SQLite database (problems, submissions, source code, topics, sync state) plus a
+disk layout per problem:
+
+```
+Problems/<slug>/
+  latest.<ext>          the most recent accepted submission
+  history/submission_<id>.<ext>   every kept accepted submission
+  metadata.json          difficulty, topics, runtime/memory percentiles, ...
+  notes.md                yours - never overwritten once created
+README.md                 auto-generated dashboard: progress, streaks, full solutions table
+```
+
+By default, same-day accepted submissions for the same problem are deduplicated (only the
+newest is kept); pass `--keep-all` to `import`/`sync` to disable that.
+
+## Honest limits
+
+- `watch` is polling (default 90s, configurable), not a real-time push — LeetCode has no public
+  webhook/streaming API.
+- LeetCode may Cloudflare-challenge automated HTTP clients; leetvault fails gracefully rather
+  than faking success.
+- Storing session cookies for automated access may be against LeetCode's Terms of Service. Use
+  at your own risk, against your own account only.
+- LeetCode has no official API — every endpoint leetvault uses is reverse-engineered and could
+  change without notice.
+
+## Docs
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — data flow, module responsibilities, and every
+  place live API behavior diverged from initial assumptions.
+- [docs/DEVELOPER.md](docs/DEVELOPER.md) — dev setup, project layout, running checks.
+- [docs/FAQ.md](docs/FAQ.md)
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [PLAN.md](PLAN.md) — the running decision log from this project's initial build.
+
+## License
+
+MIT — see [LICENSE](LICENSE).