spendctl 0.1.0__tar.gz

spendctl-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+<!-- A clear description of what the bug is -->
+
+## Steps to Reproduce
+1. Run command: `spendctl ...`
+2. See error: ...
+3. ...
+
+## Expected Behavior
+<!-- What you expected to happen -->
+
+## Actual Behavior
+<!-- What actually happened -->
+
+## Environment
+- macOS version:
+- Python version: (`python3 --version`)
+- spendctl version: (`spendctl --version`)
+
+## Error Messages
+```
+<!-- Paste any error messages or stack traces here -->
+```
+
+## Additional Context
+<!-- Any other relevant information -->

spendctl-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+<!-- Clear description of the feature you'd like to see -->
+
+## Why is this useful?
+<!-- Explain the use case and who would benefit -->
+
+## Example Usage
+<!-- Show how you envision using this feature -->
+```bash
+spendctl ...
+```
+
+## Alternatives Considered
+<!-- Are there workarounds or alternative approaches? -->
+
+## Additional Context
+<!-- Any other relevant information, mockups, or examples -->

spendctl-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Why is this needed?
+
+<!-- What problem does it solve? Link to related issue if applicable -->
+
+## How was this tested?
+
+- [ ] Existing tests pass (`pytest`)
+- [ ] New tests added (if applicable)
+- [ ] Manually tested (`spendctl ...`)
+
+## Checklist
+
+- [ ] Code follows existing patterns in the codebase
+- [ ] No unnecessary runtime dependencies added
+- [ ] Documentation updated (if user-facing change)
+- [ ] Lint passes (`ruff check src/ tests/`)

spendctl-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

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

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov --cov-report=term-missing

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

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          version="${GITHUB_REF#refs/tags/v}"
+          awk "/^## \\[${version}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md > /tmp/release-notes.md
+          echo "Release notes:"
+          cat /tmp/release-notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ steps.version.outputs.version }}
+          body_path: /tmp/release-notes.md
+          draft: false
+          prerelease: ${{ contains(github.ref, 'rc') || contains(github.ref, 'beta') }}
+
+      - name: Build package
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

spendctl-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# Database (personal financial data)
+*.db
+
+# Streamlit
+.streamlit/
+
+# macOS
+.DS_Store
+**/.DS_Store
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Local development
+CLAUDE.md
+uv.lock

spendctl-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

spendctl-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,155 @@
+# Architecture
+
+This document explains the high-level design of spendctl for contributors and maintainers.
+
+## Overview
+
+spendctl is a Python CLI that tracks personal finances using SQLite. It provides both a command-line interface and a 7-page Streamlit dashboard for visualization.
+
+```
+User ──► CLI (argparse) ──► Query Modules ──► SQLite Database
+User ──► Dashboard (Streamlit) ──► Query Modules ──► SQLite Database
+```
+
+All data operations flow through the query modules — neither the CLI nor the dashboard issue raw SQL directly (except for a few dashboard-specific aggregations in `helpers.py`).
+
+## Directory Structure
+
+```
+src/spendctl/
+├── __init__.py            # Version string
+├── __main__.py            # python -m spendctl entry point
+├── cli.py                 # Argparse CLI with 13 commands, --json on every command
+├── config.py              # Paths, accounts, categories, budgets, accessor functions
+├── db.py                  # Connection management, schema init, backup
+├── init_wizard.py         # Interactive setup wizard and config editing
+├── models.py              # Dataclasses (Transaction, CheckIn, Subscription)
+├── schema.sql             # DDL: 9 tables, 1 view, 9 indexes
+├── queries/
+│   ├── __init__.py        # Public API re-exports
+│   ├── _utils.py          # Shared date utilities (default_month, month_range)
+│   ├── budget.py          # budget_vs_actual, remaining_budget, total_income, cushion
+│   ├── check_ins.py       # add_check_in, get_latest, reconcile
+│   ├── dashboard.py       # account_balance, all_balances, net_worth, debt_progress
+│   ├── reports.py         # monthly_summary, cash_flow, spending_by_category
+│   ├── subscriptions.py   # CRUD for recurring subscriptions
+│   └── transactions.py    # CRUD, filtering, duplicate detection
+└── dashboard/
+    ├── app.py             # Streamlit entry point (page config + redirect)
+    ├── helpers.py         # Shared formatting utilities, month selector widget
+    └── pages/
+        ├── 1_dashboard.py     # Overview: sparklines, net worth gauge, budget summary
+        ├── 2_spending.py      # Category pie/bar charts, budget alerts
+        ├── 3_debt.py          # Progress bars, payoff projections, interest savings
+        ├── 4_transactions.py  # Filterable transaction table
+        ├── 5_subscriptions.py # Active/paused/canceled subscription list
+        ├── 6_loans.py         # Student loan payoff tracking
+        └── 7_report.py        # Printable monthly budget report
+```
+
+## Config System
+
+Config lives at `~/.config/spendctl/config.json` and is created by `spendctl init`. The file defines:
+
+- **accounts** — list of account objects with name, type, institution, APR
+- **categories** — list with name, group, and monthly budget amount
+- **income_sources** — expected monthly income by name and amount
+- **targets** — financial goals (target date, emergency fund target)
+- **min_payments** — minimum payments keyed by account name
+- **loans** — optional loan detail groups for student loan tracking
+
+`config.py` uses lazy loading: the first call to any accessor function reads and caches the JSON file. Subsequent calls return from cache. After `config edit`, `reload_config()` clears the cache and re-reads from disk.
+
+Account type is the config's single source of truth — accessor functions like `get_debt_accounts()` and `get_student_loan_accounts()` derive their results from account types rather than separate config keys.
+
+Data paths are derived from the config directory:
+
+```
+~/.config/spendctl/
+├── config.json            # User configuration
+└── data/
+    ├── spendctl.db        # Main database
+    └── backups/           # Timestamped database backups
+```
+
+## Database Schema
+
+The schema lives in `schema.sql` and is applied via `init_db()` on first connection to a new database.
+
+**Lookup tables** (seeded from config on first init):
+
+| Table | Purpose |
+|-------|---------|
+| `accounts` | Account name, type, institution, APR, starting balance |
+| `categories` | Category name, group, monthly budget amount |
+| `transaction_types` | Expense, Income, Transfer, Debt Payment, Interest, Reconciliation |
+| `budget_income` | Expected income sources and amounts |
+
+**Core tables:**
+
+| Table | Purpose |
+|-------|---------|
+| `transactions` | Every financial transaction with date, amount, type, accounts, category |
+| `check_ins` | Periodic balance snapshot headers (date, label, notes) |
+| `check_in_balances` | Normalized balance values per account per check-in |
+| `subscriptions` | Recurring charges with status tracking (Active/Canceled/Paused) |
+| `settings` | Key-value store for runtime settings (e.g., baseline date) |
+
+Check-ins use a normalized design: `check_ins` holds the snapshot header, and `check_in_balances` holds one row per account per check-in. This means new accounts can be added without a schema change.
+
+**Views:**
+
+| View | Purpose |
+|------|---------|
+| `v_monthly_expenses` | Pre-aggregated spending by month and category |
+
+**Indexes:** 9 indexes on transactions (date, category, type, from/to account, date+category) and check-ins (date, check-in ID, account name) for common query patterns.
+
+All queries use parameterized SQL (`?` placeholders) to prevent injection.
+
+## Query Layer
+
+The 6 query modules in `queries/` provide the data access API:
+
+| Module | Key Functions | Purpose |
+|--------|--------------|---------|
+| `transactions` | `add_transaction`, `list_transactions` | Transaction CRUD and filtering |
+| `budget` | `budget_vs_actual`, `remaining_budget`, `total_income` | Budget analysis |
+| `check_ins` | `add_check_in`, `get_latest_check_in` | Balance snapshots |
+| `dashboard` | `account_balance`, `all_balances`, `net_worth`, `debt_progress` | Live balance computation |
+| `reports` | `monthly_summary`, `spending_by_category`, `cash_flow` | Reporting and summaries |
+| `subscriptions` | `list_subscriptions`, `active_monthly_total` | Subscription tracking |
+
+All functions accept a `sqlite3.Connection` as the first argument and return plain dicts or lists of dicts. This keeps them easily testable with in-memory databases and JSON-serializable for `--json` output.
+
+## CLI
+
+`cli.py` uses argparse with a subcommand pattern. Each command has a handler function (`cmd_*`) that:
+
+1. Calls `_config_guard()` to verify config exists before doing any work
+2. Validates date/month arguments with regex + `date.fromisoformat()`
+3. Opens a DB connection via `ensure_db()`
+4. Calls the appropriate query function(s)
+5. Serializes output: JSON via `json.dumps()` if `--json` is set, otherwise formatted text
+
+The `--json` flag is present on every command. Consumers (AI assistants, shell scripts) can reliably pipe any command to `jq` or a parser without checking first.
+
+## Dashboard
+
+The Streamlit dashboard is a multi-page app launched via `spendctl dashboard`. It requires the optional `[dashboard]` extras (`streamlit`, `plotly`, `pandas`).
+
+- `app.py` sets page config and immediately redirects to the main dashboard page
+- Each page in `pages/` is an independent Streamlit script; Streamlit loads them alphabetically from the directory
+- `helpers.py` provides shared formatting utilities, a consistent color palette, and the month-selector widget used across pages
+- Database connections use `@st.cache_resource` for a single shared connection per server process
+
+All charts use Plotly. The dashboard reads account/category configuration from `config.py` to drive chart labels and budget targets, so adding a new account or category in the config is reflected in the dashboard without code changes.
+
+## Testing
+
+- **Framework:** pytest with in-memory SQLite fixtures
+- **Fixture:** `conftest.py` provides a fully seeded in-memory database with sample transactions, check-ins, and subscriptions — no disk I/O in tests
+- **Config isolation:** Tests monkeypatch `CONFIG_PATH` to a temp directory and reset `_config_cache` in `autouse` fixtures to prevent state leakage between tests
+- **Coverage:** All query modules, CLI argument validation, config loading, init wizard, and database layer
+- **Test files:** 10 test modules, 221 tests, all passing
+- **Config:** pytest settings and coverage in `pyproject.toml`, lint via ruff

spendctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-01
+
+### Added
+
+- Interactive setup wizard (`spendctl init`) for first-time configuration
+- Config management commands (`spendctl config show/edit/reset`)
+- 13 CLI commands with `--json` output on every command
+- Transaction tracking: add, list, filter, search, update, delete
+- Account balance computation (transaction-based with starting balance calibration)
+- Budget vs actual comparison with monthly breakdowns
+- Debt paydown progress tracking with per-account metrics
+- Net worth computation grouped by account type
+- Subscription management (active, canceled, paused)
+- Check-in system for periodic balance snapshots (normalized schema)
+- Monthly summary and cash flow reports
+- Spending breakdowns by category and account
+- CSV export
+- Database backup with timestamped copies
+- 7-page Streamlit dashboard (optional `[dashboard]` extra)
+  - Overview with sparklines and net worth gauge
+  - Spending analysis with category charts
+  - Debt progress with payoff projections
+  - Transaction browser
+  - Subscription tracker
+  - Loan detail page
+  - Printable monthly report
+- Full community standards: LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY
+- CI pipeline with lint + test matrix (Python 3.10-3.12)
+- 221 tests passing
+
+[0.1.0]: https://github.com/Jscoats/spendctl/releases/tag/v0.1.0

spendctl-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# 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, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting the project maintainer. All
+complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

spendctl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to spendctl
+
+Thanks for your interest in contributing!
+
+This project welcomes contributions from the community. Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.
+
+## Reporting Bugs
+
+Found a bug? Please [open an issue](https://github.com/Jscoats/spendctl/issues/new?template=bug_report.md) with:
+
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (macOS version, Python version, spendctl version)
+- Relevant error messages or logs
+
+**Note:** Please check existing issues first to avoid duplicates.
+
+## Requesting Features
+
+Have an idea? [Open a feature request](https://github.com/Jscoats/spendctl/issues/new?template=feature_request.md) with:
+
+- Clear description of the feature
+- Why it would be useful
+- Example usage (if applicable)
+
+## Contributing Code
+
+### Prerequisites
+
+- Python 3.10+
+- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
+
+### Before You Start
+
+1. **Check existing issues** - Someone might already be working on it
+2. **Discuss major changes** - Open an issue first for big features/refactors
+3. **Keep it focused** - One feature/fix per pull request
+
+### Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/Jscoats/spendctl.git
+cd spendctl
+
+# Install in editable mode (primary -- uses uv)
+uv tool install -e ".[dev]"          # Install with dev extras
+uv tool install -e ".[dev]" --force  # Reinstall after changes
+
+# Run tests
+pytest
+```
+
+**Fallback:** If you are not using `uv`, you can install with pip instead:
+```bash
+pip install -e ".[dev]"
+```
+
+### Code Guidelines
+
+**Follow existing patterns:**
+- Match the style of surrounding code
+- Keep functions focused and testable
+- Add docstrings to new functions
+
+**No unnecessary runtime dependencies:**
+- Keep the core package dependency-free (stdlib only)
+- Dashboard extras (`streamlit`, `plotly`, `pandas`) belong in the `[dashboard]` optional extra
+
+**Testing:**
+- Add tests for new features
+- Ensure existing tests pass: `pytest`
+- Test files live in `tests/`
+
+**Documentation:**
+- Update README.md if adding user-facing features
+- Add docstrings to new functions
+
+### Pull Request Process
+
+1. **Fork the repo** and create a feature branch
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make your changes**
+   - Write clean, readable code
+   - Add tests for new functionality
+   - Update documentation
+
+3. **Test thoroughly**
+   ```bash
+   pytest  # All tests must pass
+   ruff check src/ tests/  # Lint must pass
+   ```
+
+4. **Commit with clear messages**
+   ```bash
+   git commit -m "Add category budget alerts"
+   ```
+
+5. **Push and create a pull request**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+6. **Describe your changes** in the PR:
+   - What does it do?
+   - Why is it needed?
+   - How was it tested?
+
+### Code Review
+
+- PRs will be reviewed for code quality, test coverage, and alignment with project goals
+- Be patient - reviews may take a few days
+- Be open to feedback and iteration
+
+## Documentation
+
+Documentation improvements are always welcome! You can help by:
+
+- Fixing typos or unclear wording
+- Adding examples to the README
+- Improving code comments
+
+## Questions?
+
+Not sure about something? Open an issue with the `question` label.
+
+## Thank You!
+
+Every contribution, no matter how small, helps make this project better. Thank you for being part of the community!
+
+---
+
+**By contributing, you agree that your contributions will be licensed under the project's MIT License.**

spendctl-0.1.0/LICENSE

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