quicksnap 0.2.0__tar.gz

quicksnap-0.2.0/LICENSE

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

quicksnap-0.2.0/PKG-INFO

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: quicksnap
+Version: 0.2.0
+Summary: Never forget the engineering stories behind your code
+Author: QuickSnap Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/quicksnap/quicksnap
+Project-URL: Repository, https://github.com/quicksnap/quicksnap
+Project-URL: Issues, https://github.com/quicksnap/quicksnap/issues
+Keywords: engineering,stories,interview,portfolio,git,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: ai
+Requires-Dist: httpx>=0.24.0; extra == "ai"
+Provides-Extra: export
+Requires-Dist: fpdf2>=2.7.0; extra == "export"
+Requires-Dist: python-docx>=1.0.0; extra == "export"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# QuickSnap
+
+> Git remembers what changed. QuickSnap remembers why.
+
+Your second brain for software engineering. Capture, search, and recall your engineering decisions for interviews, performance reviews, and knowledge sharing.
+
+---
+
+## What Is This?
+
+Every developer has solved hard problems. Race conditions. Performance bottlenecks. Authentication redesigns. System migrations.
+
+Six months later, you can't remember the details. The code is there. The commits are there. But the **reasoning** — why you chose Redis over PostgreSQL, what alternatives you rejected, what tradeoffs you accepted — that's gone.
+
+QuickSnap captures those details **right after you finish a task**, while your thinking is still fresh. It turns your daily coding into a searchable archive of interview-ready stories.
+
+---
+
+## How It Works
+
+```
+You finish coding
+       ↓
+git commit
+       ↓
+QuickSnap captures automatically
+       ↓
+Story saved to .snapshots/
+       ↓
+Months later → search and recall everything
+```
+
+**Without QuickSnap:**
+- You commit code
+- You forget the reasoning
+- Interview comes → blank mind
+
+**With QuickSnap:**
+- You commit code
+- Story auto-captured with git context
+- Interview comes → full story ready
+
+---
+
+## The Two Products
+
+QuickSnap has two interfaces that share the same core:
+
+### 1. CLI (Primary)
+
+A terminal tool. Install with pip, run from any project.
+
+```bash
+pip install -e .
+quicksnap capture        # Interactive — answers questions
+quicksnap capture -n     # Automatic — fills from git
+quicksnap list           # Browse all stories
+quicksnap search redis   # Search by keyword
+quicksnap search-natural caching  # Natural language search
+quicksnap star auth-fix  # STAR format for interviews
+quicksnap bullets auth-fix  # Resume bullet points
+quicksnap practice       # Random interview questions
+quicksnap interview      # Interview practice with self-scoring
+quicksnap generate auth-fix linkedin  # Generate LinkedIn post
+quicksnap generate auth-fix blog      # Generate blog draft
+quicksnap export-portfolio  # Full engineering portfolio
+quicksnap tag auth-fix Backend,Performance  # Add tags
+quicksnap untag auth-fix Backend  # Remove tags
+quicksnap tags-list      # List all tags
+quicksnap sync-export    # Export to zip for cross-device sync
+quicksnap sync-import    # Import from zip
+```
+
+## Tech Stack
+
+### CLI
+
+| Component | Technology | Why |
+|-----------|-----------|-----|
+| Language | Python 3.9+ | Widely available, fast to develop |
+| CLI framework | Typer | Modern, auto-generates help, type hints |
+| Terminal output | Rich | Beautiful tables, colors, markdown rendering |
+| Git integration | subprocess (git CLI) | No extra dependencies, works everywhere |
+| Storage format | Markdown + JSON | Human-readable + machine-parseable |
+| Config | YAML | Clean, readable configuration |
+| Local AI | Ollama HTTP API | No Python library needed, just HTTP |
+| Cloud AI | httpx (OpenAI/Anthropic/Gemini) | Lightweight HTTP client |
+
+### VS Code Extension
+
+| Component | Technology | Why |
+|-----------|-----------|-----|
+| Language | TypeScript | Type safety, VS Code API |
+| UI | VS Code TreeView + Webview | Native look and feel |
+| Git integration | Shell out to CLI | Reuses all CLI logic |
+| Build | tsc + vsce | Standard VS Code toolchain |
+
+---
+
+## Data Model
+
+Every snapshot stores:
+
+```json
+{
+  "title": "Auth Cache Optimization",
+  "date": "2026-07-15",
+  "repository": "payments-api",
+  "branch": "feature/auth-cache",
+  "problem": "Permission lookups caused high latency",
+  "context": "API receives ~4M requests/day",
+  "challenge": "Permission checks triggered multiple SQL queries",
+  "alternatives": ["Database joins", "Redis cache", "Denormalized table"],
+  "decision": "Used Redis cache with 10-minute TTL",
+  "tradeoffs": ["Permissions may remain stale for 10 minutes"],
+  "result": "Average latency reduced from 850ms to 180ms",
+  "lessons": "Event-driven invalidation would be better than TTL",
+  "surprises": "Redis was faster than expected",
+  "risks_taken": "Migrated production auth system",
+  "assumptions": "Assumed 90% cache hit rate",
+  "almost_failed": "Lost 1 hour of data during migration",
+  "advice": "Always test cache invalidation before deploying",
+  "tags": ["Performance", "Backend", "Caching", "Redis"],
+  "quality_score": 85,
+  "files_changed": ["api/auth.py", "db/cache.py"],
+  "functions_modified": ["check_permission", "get_cached_role"],
+  "commit_messages": ["feat: add redis permission cache"],
+  "diff_summary": "git diff output...",
+  "star": {
+    "situation": "...",
+    "task": "...",
+    "action": "...",
+    "result": "..."
+  },
+  "bullets": [
+    "Reduced API latency by 78% using Redis permission caching",
+    "Eliminated redundant SQL queries"
+  ],
+  "slug": "auth-cache-optimization",
+  "schema_version": 2
+}
+```
+
+---
+
+## AI Modes
+
+Three ways to generate stories:
+
+### Mode 1: Manual (Default, No AI)
+
+```bash
+quicksnap capture
+```
+
+Tool asks questions, you answer. Pure offline. No API keys.
+
+### Mode 2: Local AI (Ollama)
+
+```bash
+quicksnap capture --ai local
+```
+
+Reads your git diff, generates summary locally. No data leaves your machine.
+
+Requires Ollama running with a model (llama3, qwen, gemma, mistral).
+
+### Mode 3: Cloud AI (Optional)
+
+```bash
+# Set one of these:
+export OPENAI_API_KEY=sk-...
+# or
+export ANTHROPIC_API_KEY=sk-ant-...
+# or
+export GEMINI_API_KEY=...
+
+quicksnap capture --ai openai
+```
+
+Generates richer summaries using cloud LLMs.
+
+### Mode 4: Non-Interactive (Fully Automatic)
+
+```bash
+quicksnap capture -n
+# or
+quicksnap capture --non-interactive
+```
+
+No questions. No AI. Just fills everything from git context automatically.
+
+---
+
+## Commands Reference
+
+| Command | What It Does | Example |
+|---------|-------------|---------|
+| `capture` | Create a new story | `quicksnap capture` |
+| `capture -n` | Auto-capture from git | `quicksnap capture -n` |
+| `list` | Show all stories | `quicksnap list` |
+| `list --tag Backend` | Filter by tag | `quicksnap list --tag Performance` |
+| `show <slug>` | View a story | `quicksnap show auth-cache` |
+| `search <query>` | Search stories | `quicksnap search redis` |
+| `search-natural <query>` | Natural language search | `quicksnap search-natural caching` |
+| `star <slug>` | STAR format | `quicksnap star auth-cache` |
+| `bullets <slug>` | Resume bullets | `quicksnap bullets auth-cache` |
+| `practice` | Interview practice | `quicksnap practice` |
+| `interview` | Interview with self-scoring | `quicksnap interview --tag Backend` |
+| `generate <slug> <format>` | Generate content | `quicksnap generate auth-fix linkedin` |
+| `tag <slug> <tags>` | Add tags | `quicksnap tag auth-fix Backend,Redis` |
+| `untag <slug> <tags>` | Remove tags | `quicksnap untag auth-fix Backend` |
+| `tags-list` | List all tags | `quicksnap tags-list` |
+| `export-portfolio` | Full portfolio | `quicksnap export-portfolio` |
+| `sync-export` | Export to zip | `quicksnap sync-export` |
+| `sync-import` | Import from zip | `quicksnap sync-import` |
+| `delete-cmd <slug>` | Delete a story | `quicksnap delete-cmd auth-cache` |
+| `init` | Setup in a repo | `quicksnap init` |
+
+---
+
+## VS Code Extension Features
+
+| Feature | Trigger | What Happens |
+|---------|---------|--------------|
+| Capture Story | `Ctrl+Shift+P` → "QuickSnap: Capture" | Auto-captures from git, no input needed |
+| Browse Stories | Click history icon in sidebar | Tree view grouped by tags or timeline |
+| View Story | Click a story in sidebar | Opens as markdown in editor |
+| STAR Story | Right-click story → "Show STAR Story" | Generates STAR format |
+| Resume Bullets | Right-click story → "Generate Resume Bullets" | Generates bullet points |
+| Search | `Ctrl+Shift+P` → "QuickSnap: Search" | Filter stories by keyword |
+| Natural Search | `Ctrl+Shift+P` → "QuickSnap: Search (Natural)" | Search with synonyms |
+| Interview | `Ctrl+Shift+P` → "QuickSnap: Interview" | Practice with self-scoring |
+| Generate | `Ctrl+Shift+P` → "QuickSnap: Generate" | Create LinkedIn/blog/interview content |
+| Toggle View | Click calendar icon in sidebar | Switch tag/timeline view |
+| Export Portfolio | `Ctrl+Shift+P` → "QuickSnap: Export Portfolio" | Creates portfolio.md |
+| Auto-capture | After git commit (smart detection) | Only prompts for meaningful commits |
+
+---
+
+## Storage
+
+Each project gets a `.snapshots/` folder:
+
+```
+.snapshots/
+├── index.json           # Quick lookup index
+├── auth-cache.json      # Full snapshot data
+├── auth-cache.md        # Human-readable markdown
+├── db-optimization.json
+├── db-optimization.md
+└── ...
+```
+
+- **Markdown** — what you read and share
+- **JSON** — what the tool reads and indexes
+- **index.json** — fast listing without reading all files
+
+---
+
+## Configuration
+
+Create `.quicksnap.yaml` in your project root:
+
+```yaml
+version: "0.2.0"
+ai_mode: auto          # manual | auto | local | openai | anthropic | gemini
+```
+
+VS Code settings (in `settings.json`):
+
+```json
+{
+  "quicksnap.cliPath": "quicksnap",
+  "quicksnap.notifyAfterCommit": true
+}
+```
+
+---
+
+## Development
+
+### CLI
+
+```bash
+cd D:\quicksnap
+pip install -e .            # Install in dev mode
+quicksnap --help        # Test
+quicksnap capture -n    # Test auto-capture
+```
+
+### VS Code Extension
+
+```bash
+cd vscode-extension
+npm install
+npx tsc -p ./               # Compile TypeScript
+vsce package --allow-missing-repository  # Build .vsix
+code --install-extension quicksnap-0.1.0.vsix --force
+```
+
+### Testing
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## Why This Matters
+
+**For interviews:**
+- Have stories ready for "tell me about a challenging problem"
+- STAR format generated automatically
+- Resume bullets generated from real work
+- Interview practice with self-scoring
+
+**For performance reviews:**
+- Portfolio of everything you shipped
+- Quantified impact (latency reduced, bugs fixed)
+- Evidence of growth and learning
+
+**For knowledge sharing:**
+- Team members can read your reasoning
+- Onboarding becomes easier
+- Decisions are documented
+
+**For yourself:**
+- Remember why you made choices
+- Track your engineering growth
+- Never blank on "what did you work on?"
+
+---
+
+## Common Workflows
+
+### After Finishing a Feature
+
+```
+1. git commit -m "feat: add user caching"
+2. Ctrl+Shift+P → "QuickSnap: Capture"
+3. Done. Story saved with full git context.
+```
+
+### Before an Interview
+
+```
+1. quicksnap search performance
+2. Read your stories
+3. quicksnap interview --tag Backend
+4. Practice with self-scoring
+5. quicksnap star auth-cache
+6. Review STAR format
+```
+
+### Updating Resume
+
+```
+1. quicksnap bullets auth-cache
+2. Copy bullet points
+3. Paste into resume
+```
+
+### Generating LinkedIn Post
+
+```
+1. quicksnap generate auth-fix linkedin
+2. Copy the generated post
+3. Share on LinkedIn
+```
+
+### Team Knowledge Sharing
+
+```
+1. quicksnap export-portfolio
+2. Share portfolio.md with team
+3. Everyone learns from your decisions
+```
+
+### Cross-Device Sync
+
+```
+1. On laptop: quicksnap sync-export
+2. Copy quicksnap-sync.zip to cloud/USB
+3. On desktop: quicksnap sync-import quicksnap-sync.zip
+```