tidy-gmail 0.1.0__tar.gz

tidy_gmail-0.1.0/.gitignore

@@ -0,0 +1,382 @@
+# ============================================================
+# .gitignore (CUSTOM)
+# ============================================================
+# Updated: 2026-11-13
+#
+# WHAT: A Git configuration file that identifies files and directories
+#       that should not be included in the repository's version history.
+#       Git uses this file to determine which untracked files to ignore.
+#
+# WHEN: Use in professional repositories managed with Git.
+#       Git automatically applies these rules when working with files.
+#
+# WHY: Version the files we create and maintain for this project.
+#      Avoid tracking downloaded dependencies, generated output,
+#      temporary files, local settings, and sensitive information.
+#      Other projects maintain the source code and version history
+#      of their own dependencies.
+#
+# HOW: List file and directory patterns below.
+#      Patterns work across different languages, tools, and project types.
+#      Sections are organized by purpose for easier maintenance.
+#
+#      In VS Code, open the 'Outline view' in the Explorer sidebar to
+#      see and navigate the different sections of this file.
+#      Requires the recommended 'Comment Section Outline' extension
+#      (see .vscode/extensions.json).
+#
+# TOOLS: Git tracks changes to project files and maintains version history.
+#        .gitignore controls which untracked files Git ignores.
+#
+# SKILLS: Git, version control, repository management,
+#         file patterns, dependency management, and project maintenance.
+#
+# REQ: All professional GitHub project repositories MUST include .gitignore.
+# REQ: Never commit secrets or private credentials.
+#
+# OBS: .gitignore does not remove files already tracked by Git.
+# OBS: Dependency manifests and lockfiles should generally be committed
+#      even when downloaded dependencies are ignored.
+# OBS: Patterns for unused tools or languages are generally harmless.
+#
+# ALT: Repositories may customize ignores while preserving safety rules.
+# CUSTOM: Delete sections that are not needed for the project.
+# CUSTOM: Add project-specific patterns when necessary.
+#
+# ============================================================
+# === INTRO: How .gitignore patterns work ===
+# ============================================================
+# NOTE: .gitignore uses glob-style patterns, not regular expressions.
+#
+# /name
+# WHY: A leading slash anchors the pattern to the directory containing this
+# .gitignore file. In a repository-root .gitignore, /name matches only name
+# at the repository root.
+# EXAMPLE: /pyproject.toml.ruff ignores only the root-level temporary fragment.
+#
+# name/
+# WHY: A trailing slash means the pattern matches directories, not files.
+# EXAMPLE: bin/ ignores directories named bin and their contents.
+#
+# *.ext
+# WHY: An asterisk (*) matches any number of characters within one path component.
+# EXAMPLE: *.log ignores files ending in .log.
+#
+# **
+# WHY: A double asterisk (**) can match across directory levels.
+# EXAMPLE: **/src/**/_version.py matches generated _version.py files inside
+# src trees regardless of repository depth or package name.
+#
+# ?
+# WHY: A question mark (?) matches exactly one character within a path component.
+# EXAMPLE: temp?.txt matches temp1.txt and tempa.txt, but not temp10.txt.
+#
+# [abc]
+# WHY: Square brackets match one character from the listed set or range.
+# EXAMPLE: file[0-9].txt matches file0.txt through file9.txt.
+#
+# !pattern
+# WHY: An exclamation point (!) negates an earlier ignore rule and re-includes
+# a matching file when its parent directory has not itself been excluded.
+# EXAMPLE: !.env.example keeps the safe example file even though .env.* is ignored.
+#
+# # text
+# WHY: A leading # makes the line a comment unless the # is escaped.
+#
+# NOTE: Prefer the narrowest pattern that expresses the intent.
+# Anchored patterns such as /name are safer when
+# only a repository-root file should be ignored.
+# ============================================================
+
+# ============================================================
+# === SECTION: CUSTOM ===
+# ============================================================
+
+# Private Gmail configuration and sender decisions
+/data/
+
+# Generated reports and cleanup logs
+/output/
+
+# OAuth credentials, tokens, and local state
+/.local/
+
+# ============================================================
+# === SECTION: UNIVERSAL ===
+# ============================================================
+
+# === Environment variables and secrets ===
+
+# WHY: Never commit credentials or environment-specific configuration.
+*.env
+.env
+.env.*
+
+# WHY: Commit .env.example as a safe template showing which variables to set.
+# NOTE: Copy .env.example to .env locally and customize the local copy.
+!.env.example
+
+
+# === Private notes and local-only files ===
+
+# WHY: Private working notes should remain local unless intentionally published.
+PRIVATE-NOTES.md
+PRIVATE_NOTES.md
+
+# WHY: The root-level refs directory holds local reference papers and source
+# materials that should be cited or linked to rather than committed.
+# NOTE: The leading slash limits this rule to the repository-root refs directory.
+# ALT: Commit only reference material that is intentionally redistributable and
+# appropriate to include in the repository.
+/refs/
+
+
+# === Operating-system files ===
+
+# WHY: OS-generated metadata files are machine-specific and should not be tracked.
+.AppleDouble
+.DS_Store
+.LSOverride
+.Spotlight-V100/
+.Trashes
+._*
+Icon\r
+Thumbs.db
+desktop.ini
+ehthumbs.db
+
+
+# === Editors and IDEs ===
+
+# WHY: IDE metadata is generally machine-local and should not be tracked.
+*.code-workspace
+.idea/
+
+
+# === VS Code ===
+
+# WHY: Ignore editor state by default while allowing shared project configuration.
+# NOTE: Use .vscode/* (contents), not .vscode/ (directory). Git will not
+# re-include a file whose parent directory is excluded.
+.vscode/*
+!.vscode/ABOUT_THIS_FOLDER.md
+!.vscode/extensions.json
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/*.code-snippets
+
+
+# === Temporary, lock, and swap files ===
+
+# WHY: Temporary and swap files are machine-local noise and create meaningless diffs.
+*.swo
+*.swp
+*.tmp
+*~
+
+# WHY: Microsoft Office creates temporary owner/lock files beside open documents.
+# NOTE: These patterns cover Word, Excel, and PowerPoint temporary files without
+# ignoring the actual Office documents.
+~$*.doc*
+~$*.xls*
+~$*.ppt*
+
+# WHY: LibreOffice and OpenOffice create temporary lock files beside open documents.
+.~lock.*#
+
+
+# === Logs and generated runtime output ===
+
+# WHY: Ignore logs and runtime output by default.
+# ALT: Explicitly re-include a specific log only when it is intentionally used
+# as project evidence.
+*.log
+logs/
+# !/project.log
+
+
+# === Generic caches ===
+
+# WHY: Generic caches are machine-local and should not be tracked.
+.cache/
+
+
+# === Generic bin (binary) folder ===
+
+# WHY: The root-level bin directory contains generated executable or build output.
+# NOTE: The leading slash limits this rule to the repository-root bin directory
+# and avoids ignoring a nested source directory that happens to be named bin.
+/bin/
+
+
+# ============================================================
+# === SECTION: PROJECT DOCS ===
+# ============================================================
+
+# WHY: Static site build output is generated from the documentation source.
+# NOTE: Zensical uses site/ as the generated site output directory.
+site/
+
+# ============================================================
+# === SECTION: PYTHON ===
+# ============================================================
+
+# === Python environments ===
+
+# WHY: Virtual environments are machine-local and reproducible from project files.
+.venv/
+venv/
+
+
+# === Python project state ===
+
+# REQ: Do NOT git ignore .python-version.
+# WHY: Commit .python-version to declare the Python version used by the project.
+
+# REQ: Do NOT git ignore uv.lock.
+# WHY: Commit uv.lock to preserve the resolved dependency environment and use it
+# in CI/CD pipelines.
+
+# WHY: Generated SCM version modules should not be tracked.
+# NOTE: This recursive pattern works regardless of repository depth or package name.
+**/src/**/_version.py
+
+
+# === Python bytecode ===
+
+# WHY: Python bytecode is generated automatically and is machine-specific.
+*.pyc
+*.pyd
+*.pyo
+__pycache__/
+
+
+# === Python build and packaging artifacts ===
+
+# WHY: Build and packaging artifacts are generated from project source.
+*.egg
+*.egg-info/
+*.whl
+.eggs/
+build/
+dist/
+
+
+# === Python testing and coverage output ===
+
+# WHY: Test and coverage reports are generated and can be reproduced.
+.coverage
+.coverage.*
+.pytest_cache/
+htmlcov/
+coverage.xml
+coverage.json
+coverage.lcov
+
+
+# === Python tooling caches ===
+
+# WHY: Tooling caches improve local performance but should not be tracked.
+.mypy_cache/
+.pytype/
+.ruff_cache/
+.tox/
+
+
+# === Python notebooks and marimo ===
+
+# WHY: Jupyter notebook checkpoint state is generated.
+.ipynb_checkpoints/
+
+# REQ: Do NOT git ignore layouts/ when using marimo custom layouts.
+# WHY: Marimo layout files are project source and should be version controlled.
+
+# REQ: Do NOT git ignore public/ when it contains source assets or data
+# used by marimo or WASM applications.
+# WHY: These files may be required to reproduce or publish the application.
+
+
+# ============================================================
+# === SECTION: NODE ===
+# ============================================================
+# Some tooling and projects require Node.js and its dependencies.
+
+# WHY: Node dependencies are restored from package-lock.json with npm ci.
+node_modules/
+
+# REQ: Do NOT git ignore package-lock.json.
+# WHY: Commit package-lock.json to preserve reproducible Node dependency
+# resolution and use it in CI/CD pipelines.
+
+
+# === Node package-manager caches ===
+
+# WHY: Package-manager caches are machine-local and should not be tracked.
+.npm/
+.pnpm-store/
+.yarn/cache/
+.yarn/unplugged/
+.yarn/build-state.yml
+.yarn/install-state.gz
+
+# ============================================================
+# === SECTION: TYPESCRIPT AND JAVASCRIPT ===
+# ============================================================
+
+# === TypeScript and JavaScript build output ===
+
+# WHY: Compiled JavaScript output is generated from TypeScript source.
+out/
+
+# WHY: TypeScript incremental build metadata is generated.
+*.tsbuildinfo
+
+
+# === TypeScript and JavaScript tooling caches ===
+
+# WHY: Tooling caches and generated coverage output should not be tracked.
+.eslintcache
+.nyc_output/
+coverage/
+
+
+# === VS Code extension test and package output ===
+
+# WHY: VS Code extension test-host files are generated by @vscode/test-electron.
+.vscode-test/
+
+# WHY: VSIX packages are generated release artifacts.
+*.vsix
+
+# ============================================================
+# === SECTION: COMPUTER-CHECKED MATHEMATICAL PROOFS (LEAN) ===
+# ============================================================
+
+# === Lean ===
+
+# WHAT: Lean is a programming language and proof assistant used to
+#       express mathematical definitions, theorems, and proofs.
+#       It can also verify properties of software and logical systems.
+#       Lean checks whether formal proofs satisfy their stated rules.
+#
+# WHY: Lake, Lean's project and build tool, generates build files
+#      and downloads dependencies that do not need to be committed.
+.lake/
+lake-packages/
+/docbuild/
+
+
+# ============================================================
+# === SECTION: CUSTOM GENERATED ARTIFACTS ===
+# ============================================================
+
+# === Generated files for supported repositories ===
+
+# WHY: Generated analytics and guide-context artifacts should be rebuilt rather
+# than committed.
+# NOTE: These entries are harmless in repositories that do not generate them.
+docs/assets/data/view-analytics.json
+docs/assets/data/guide-context.json
+# marimo WASM export; built at deploy time, not committed
+docs/app/

tidy_gmail-0.1.0/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+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)**.
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Automatic resumption of bounded Gmail scans across invocations.
+- Private SQLite checkpoints that commit metadata and cursor progress together.
+- Explicit scan restart with private archives of earlier results.
+- Partial/complete scan status and unavailable-message reports.
+- Query and account identity checks, bounded read retries, and invalid-token diagnostics.
+- Synthetic pagination, Ctrl+C, process-crash, deduplication, and large-inventory tests.
+
+### Changed
+
+- Scan inventory now accumulates unique records instead of replacing prior batches.
+- Reports can read committed scan metadata even after interrupted CSV export.
+- Sender discovery writes additions atomically while preserving existing decisions.
+
+### Added
+
+- Optional permanent sender approvals in `data/senders_always_delete.csv`.
+- Approval source reporting and explicit keep/review conflict reports.
+- Synthetic coverage for large lists, age boundaries, and final safety checks.
+
+### Changed
+
+- Refresh Gmail search exclusions before every Trash request.
+- Apply configured dry-run to CLI restoration as well as cleanup.
+
+### Fixed
+
+- Protected sender report labels now show protection reasons instead of
+  undecided or trash decisions, while preserving saved sender decisions.
+- Added synthetic regression coverage for workspace selection and protected
+  senders at candidate selection and the final pre-Trash check.
+
+### Changed
+
+- Separated published-user instructions in the README from source-checkout
+  and maintainer instructions in the development documentation.
+
+### Added
+
+- Permanent receipt protection with a default-enabled configuration setting.
+- Decoded Subject matching for transactional records across Gmail categories.
+- Receipt and invalid-metadata reports with separate sender summary counts.
+- Final per-message metadata protection checks after cleanup confirmation.
+- Offline tests for receipt formats, missing metadata, and changed candidates.
+
+- CSV header examples and troubleshooting for preserved empty configuration.
+- Explanation of successful local validation and the next OAuth setup step.
+
+---
+
+## [0.1.0] - 2026-11-14
+
+### Added
+
+- Local-first Gmail cleanup command-line application.
+- `uvx tidy-gmail` entry point and configurable `--workspace` path.
+- Windows and macOS workspace conventions.
+- Workspace initialization that preserves existing configuration.
+- Local configuration validation with `doctor`.
+- Gmail OAuth authorization and metadata-only inspection.
+- Persistent sender decisions and protected sender lists.
+- Configurable protection for Gmail label IDs, own addresses,
+  and subject keywords.
+- Sender discovery, inventory, and cleanup candidate reports.
+- Dry-run defaults, live eligibility checks, and explicit
+  confirmation before moving messages to Gmail Trash.
+- Durable audit logging and restoration of Inbox membership.
+- Recovery support for interrupted restoration operations.
+- Offline tests for classification, Gmail requests, cleanup,
+  and recovery.
+- Workflow and local privacy documentation.
+
+### Changed
+
+- Standardized the protected sender filename as
+  `senders_protected.csv`.
+- Separated authorization, inventory, classification, reporting,
+  cleanup, and restoration into dedicated modules.
+- Made packaged templates the source of starter configuration.
+
+### Fixed
+
+- Restoration retries after untrashing succeeds but restoring
+  Inbox membership fails.
+- Validation of an explicitly supplied zero cleanup limit.
+- Stale documentation and lint errors.
+
+---
+
+## Notes on Versioning and Releases
+
+- We use **SemVer**:
+  - **MAJOR** - breaking changes
+  - **MINOR** - backward-compatible
+  - **PATCH** - fixes, documentation, tooling
+- Versions are driven by git tags. Tag `vX.Y.Z` to release.
+- Docs are deployed per version tag and aliased to **latest**.
+
+## Release Procedure (Required)
+
+Follow these steps exactly when creating a new release.
+
+### Task 1. Update release metadata (manual edits)
+
+1. Update `CITATION.cff`: change `version` and `date-released`
+2. Update `CHANGELOG.md`: move from unreleased, add entry, update links
+3. Update `pyproject.toml`: update `[tool.hatch.version] fallback-version`
+
+### Task 2. Validate
+
+```shell
+.\sit.ps1
+
+# OR
+
+uv self update
+uv python install
+uv lock --upgrade
+uv sync
+uv audit
+
+# set up and run git hooks
+uvx prek install --force
+uvx prek update
+
+git add -A
+uvx prek run --all-files
+# repeat if changes were made
+uvx prek run --all-files
+
+# run common chores
+uv run ruff format .
+uv run ruff check . --fix
+uv run ty check
+uv run python -m pytest
+uv run python -m zensical build
+
+uv run python -c "import shutil; from pathlib import Path; shutil.rmtree(Path('dist'), ignore_errors=True)"
+
+uv build
+uvx twine check dist/*
+
+# update .github/workflows
+uvx gha-tools autoupdate --pin=all --write .github/workflows
+# check
+uvx zizmor@latest .github/ --fix  
+# 1 informational or suppressed are still okay
+
+uvx
+
+```
+
+### Task 3. Commit, push, tag
+
+```shell
+git add -A
+git commit -m "Prepare X.Y.Z"
+git push -u origin main
+```
+
+Verify actions run on GitHub. After success:
+
+```shell
+git tag vX.Y.Z -m "X.Y.Z"
+git push origin vX.Y.Z
+```
+
+## Only As Needed (delete a tag)
+
+```shell
+git tag -d vX.Z.Y
+git push origin :refs/tags/vX.Z.Y
+```
+
+## Links
+
+[Unreleased]: https://github.com/analytics-toolworks/tidy-gmail/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/analytics-toolworks/tidy-gmail/releases/tag/v0.1.0
+
+<!-- markdownlint-enable MD024 -->

tidy_gmail-0.1.0/CITATION.cff

@@ -0,0 +1,53 @@
+# ============================================================
+# CITATION.cff (How to cite this project)
+# ============================================================
+# REQ: Professional open projects SHOULD include this file.
+# USAGE: See https://citation-file-format.github.io/ for details.
+# check with:
+# uvx cffconvert --validate
+
+cff-version: "1.2.0"
+message: "If you use this project, please cite it using the information in CITATION.cff."
+type: software
+
+title: "tidy-gmail"
+version: "0.1.0"
+date-released: "2026-11-14"
+
+authors:
+  - family-names: Case
+    given-names: Denise M.
+    orcid: "https://orcid.org/0000-0001-6165-7389"
+    affiliation: "Northwest Missouri State University, USA"
+
+repository-code: "https://github.com/analytics-toolworks/tidy-gmail"
+url: "https://github.com/analytics-toolworks/tidy-gmail"
+license: MIT
+
+abstract: |
+  tidy-gmail is an open-source, local-first Python command-line
+  utility for inspecting and cleaning Gmail accounts using
+  user-maintained configuration and explicit cleanup rules.
+
+  The project separates mailbox inspection, classification,
+  cleanup decisions, and execution. It is designed to preserve
+  personal correspondence, financial records, charitable
+  contribution receipts, and other potentially valuable messages
+  while identifying disposable email.
+
+  Configuration, credentials, audit records, and reports remain
+  under the user's control. The intended interface supports
+  inspection, dry-run evaluation, controlled movement to Gmail
+  Trash, and restoration.
+
+keywords:
+  - gmail
+  - email
+  - email-cleanup
+  - email-organization
+  - automation
+  - privacy
+  - python
+  - command-line-tool
+  - uvx
+  - open-source

tidy_gmail-0.1.0/LICENSE

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