gfunk 0.1.0__tar.gz

gfunk-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,53 @@
+# gfunk
+
+CLI and MCP server for Google Workspace. Python 3.13+, uv, strict mypy.
+
+## Quick reference
+
+```bash
+uv sync                       # install
+uv run pytest tests/ -q       # run tests (uses -n 6 via xdist)
+uv run pre-commit run --all-files  # lint, format, type-check, test
+uv run gfunk --version        # smoke test
+```
+
+## Stack
+
+- **Runtime:** Python 3.13+, uv
+- **CLI framework:** argparse (src/gfunk/cli.py)
+- **TUI:** Textual (src/gfunk/vibe.py)
+- **MCP server:** mcp library, stdio transport (src/gfunk/mothership.py)
+- **Auth:** Google OAuth2 Desktop flow, token cached at ~/.config/gfunk/
+- **Cache:** SQLite at ~/.local/share/gfunk/cache.db
+- **Linting:** ruff (strict rule set in .ruff.toml), mypy strict
+- **Tests:** pytest + pytest-xdist (`-n 6`)
+
+## Layout
+
+- `src/gfunk/` — all source
+- `tests/` — one test file per module, named `test_<module>.py` or `test_cli_<command>.py`
+- `pyproject.toml` — deps, mypy config, commitizen config
+- `.ruff.toml` — linter/formatter rules
+- `.pre-commit-config.yaml` — full hook suite
+
+## Conventions
+
+- Every subcommand has exactly two names: one flavorful, one literal (e.g. `vibe` / `sheet`, `mothership` / `mcp`). No more, no less.
+- Commit messages follow Conventional Commits (commitizen enforced).
+- No comments unless the "why" is non-obvious.
+- Type hints on all function signatures (mypy strict).
+- Tests use synthetic fixtures only — never real customer data, names, or IDs.
+- `block-private-terms` pre-commit hook catches PII in fixtures.
+
+## Auth and scopes
+
+Scopes are declared in `src/gfunk/auth.py`. A test asserts the exact scope list — any
+change to scopes must update the test. Start read-only, widen deliberately.
+
+## Adding a subcommand
+
+1. Add the parser in `src/gfunk/cli.py` (with aliases).
+2. Add the handler function in cli.py or a new module.
+3. If it's an MCP tool too, register it in `src/gfunk/mothership.py`.
+4. Write tests: `tests/test_cli_<name>.py`.
+5. Update the vocabulary table in `README.md`.

gfunk-0.1.0/.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "gfunk": {
+      "command": "gfunk",
+      "args": [
+        "mothership"
+      ]
+    }
+  }
+}

gfunk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,53 @@
+version: 2
+
+updates:
+  # Runtime dependencies. Google's client libraries ship security fixes on
+  # their own cadence, so this is the update stream that actually matters.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      # One PR for the routine churn; anything major still arrives alone and
+      # gets read properly.
+      python-minor-and-patch:
+        patterns: ['*']
+        update-types: [minor, patch]
+    commit-message:
+      prefix: 'fix'
+      prefix-development: 'chore'
+    # Wait a week before proposing a newly-published version. The supply-chain
+    # attack this blocks is a malicious release that gets auto-merged within
+    # minutes of publication; a week is long enough that a compromised version
+    # is usually yanked before Dependabot ever opens the PR. Dependabot's
+    # *security* updates are a separate stream and are not delayed by this.
+    cooldown:
+      default-days: 7
+
+  # A compromised or abandoned action runs with the workflow's token. Keep
+  # these current and pinned to a major.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ['*']
+    commit-message:
+      prefix: 'ci'
+    cooldown:
+      default-days: 7
+
+  # pre-commit hook revs are pinned by rev: and go stale silently otherwise.
+  - package-ecosystem: pre-commit
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      hooks:
+        patterns: ['*']
+    commit-message:
+      prefix: 'ci'
+    cooldown:
+      default-days: 7

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

@@ -0,0 +1,159 @@
+# Lint, type-check, and test every push and PR.
+#
+# gfunk is public and holds a user's Workspace credentials at runtime, so the
+# security jobs are part of CI rather than a separate optional workflow.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege by default; a job that needs more asks for it itself.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.14'
+          enable-cache: true
+
+      - run: uv sync
+
+      - name: Lint
+        run: uv run --with ruff ruff check --config .ruff.toml src tests
+
+      - name: Format
+        run: uv run --with ruff ruff format --check --config .ruff.toml src tests
+
+      - name: Type-check
+        run: uv run --with mypy mypy
+
+      - name: Test
+        run: uv run pytest -q --cov --cov-report json
+
+      - name: Upload coverage
+        if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage
+          path: coverage.json
+
+      - name: Build
+        run: uv build
+
+      # `--version` must answer on a bare wheel with no dev group, no config,
+      # and no credentials -- that is the state a bug reporter is in.
+      - name: --version works from the built wheel alone
+        run: |
+          cd "$(mktemp -d)"
+          uv run --isolated --no-project \
+            --with "$GITHUB_WORKSPACE"/dist/*.whl gfunk --version
+
+  hooks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # gitleaks needs history to scan; a shallow clone scans one commit.
+          fetch-depth: 0
+          # No job here pushes, so leaving the token in .git/config only
+          # widens what a compromised step could walk off with.
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.14'
+          enable-cache: true
+
+      - run: uv sync
+
+      # The same suite the contributor's commit ran, so a bypassed local hook
+      # is caught here rather than in review.
+      - name: pre-commit
+        run: uv run --with pre-commit pre-commit run --all-files --show-diff-on-failure
+
+  screenshots:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.14'
+          enable-cache: true
+
+      - run: uv sync
+
+      - name: Regenerate screenshots
+        run: uv run python scripts/capture_screenshots.py
+
+      - name: Check for drift
+        run: |
+          if ! git diff --quiet docs/screenshots/; then
+            echo "::error::Screenshots are stale. Run: uv run python scripts/capture_screenshots.py"
+            git diff --stat docs/screenshots/
+            exit 1
+          fi
+
+  codeql:
+    runs-on: ubuntu-latest
+    permissions:
+      # Read the code to analyze it, and write the results to the Security tab.
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        with:
+          languages: python
+          queries: security-extended
+
+      - uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+
+  coverage-badge:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 # zizmor: ignore[artipacked]
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: coverage
+
+      - name: Generate badge
+        run: |
+          COV=$(python3 -c "import json; print(int(json.load(open('coverage.json'))['totals']['percent_covered']))")
+          if [ "$COV" -ge 90 ]; then COLOR="brightgreen";
+          elif [ "$COV" -ge 75 ]; then COLOR="green";
+          elif [ "$COV" -ge 60 ]; then COLOR="yellow";
+          else COLOR="red"; fi
+          mkdir -p badges
+          curl -sS "https://img.shields.io/badge/coverage-${COV}%25-${COLOR}" -o badges/coverage.svg
+
+      - uses: peaceiris/actions-gh-pages@1ef5a1b1df4c63fe21a2242edbee6cac921ece01 # v4.1.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./badges
+          destination_dir: badges
+          keep_files: true

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

@@ -0,0 +1,47 @@
+# Publish to PyPI when a version tag is pushed (trusted publisher / OIDC).
+# Use: scripts/release.py to bump, review, tag, and push.
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: '3.14'
+          enable-cache: false
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          print-hash: true

gfunk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+*credentials.json
+**.env
+token.json
+*token.json
+*.pem
+*.key
+build/
+**/build/**
+.venv/
+**/__pycache__
+**/*.egg-info
+.pytest_cache/
+.mypy_cache/
+.vscode/
+dist/

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

@@ -0,0 +1,73 @@
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit]
+
+repos:
+  # Fail a bad commit message in ~0.3s rather than after the whole suite.
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.12.0
+    hooks:
+      - id: commitizen-early
+        fail_fast: true
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.17.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  # Anything below that reaches `git commit` is in a public repo forever.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: [--maxkb=512]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: mixed-line-ending
+      # A stray credentials.json or token.json is gitignored, but -f defeats
+      # that; this refuses the file itself.
+      - id: forbid-new-submodules
+
+  # A workflow runs with a token; audit it like code.
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.12
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.29.0
+    hooks:
+      - id: zizmor
+
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.12.0
+    hooks:
+      - id: ruff-check
+        args: [--config, .ruff.toml]
+      - id: ruff-format
+        args: [--config, .ruff.toml]
+      - id: mypy
+      # A secret scanner cannot find a real customer name or sheet ID. This
+      # can. Public repo + Workspace data makes it the load-bearing one.
+      - id: block-private-terms
+      - id: embed-tree
+      - id: pytest
+        args: [tests/, -q]
+
+  - repo: local
+    hooks:
+      - id: screenshots
+        name: screenshots
+        language: system
+        entry: bash -c 'uv run python scripts/capture_screenshots.py && git add docs/screenshots/*.svg'
+        files: '(src/gfunk/(holla_tui|grind_tui|snoop_tui|dubs_tui|regulate_tui|vibe|demo_data)\.py|scripts/capture_screenshots\.py)$'
+        pass_filenames: false

gfunk-0.1.0/.ruff.toml

@@ -0,0 +1,80 @@
+line-length = 88
+show-fixes = true
+target-version = "py313"
+
+[lint]
+select = [
+  "A",
+  "ANN",
+  "ARG",
+  "ASYNC",
+  "B",
+  "BLE",
+  "C4",
+  "C90",
+  "COM",
+  "D200",
+  "D201",
+  "D202",
+  "D205",
+  "D212",
+  "E",
+  "EM",
+  "ERA",
+  "EXE",
+  "F",
+  "FBT",
+  "G",
+  "I",
+  "ICN",
+  "ISC",
+  "N",
+  "PGH",
+  "PIE",
+  "PL",
+  "PT",
+  "PTH",
+  "PYI",
+  "Q",
+  "RET",
+  "RSE",
+  "RUF",
+  "S",
+  "SIM",
+  "SLF",
+  "T20",
+  "TCH",
+  "TID",
+  "TRY",
+  "UP",
+  "W",
+  "YTT",
+]
+ignore = [
+  "COM812",
+  "I001",
+  "ISC001",
+  "PLC0415",
+  "PLR0913",
+  "S101",
+  # Python 3.14 evaluates annotations lazily (PEP 649), so hiding imports in a
+  # TYPE_CHECKING block buys nothing and costs readability.
+  "TRY003",
+]
+
+[lint.per-file-ignores]
+# The CLI is the one place printing to stdout is the product.
+"src/gfunk/cli.py" = ["T20", "ANN401"]
+# Browser-open fallback: only path when no browser is reachable, prints the link.
+"src/gfunk/browser.py" = ["T20"]
+# ANN401: JSON payloads and googleapiclient's `build()` results are genuinely
+# untyped; narrowing them would be a lie rather than a type.
+"src/gfunk/cache.py" = ["ANN401"]
+"src/gfunk/workspace.py" = ["ANN401"]
+"src/gfunk/mothership.py" = ["ANN401"]
+# Workspace is duck-typed here too, same as cli.py's snoop/regulate helpers.
+"src/gfunk/regulate_tui.py" = ["ANN401"]
+# PLR2004/EM101: a literal in an assertion is the assertion.
+# Screenshot capture script prints progress.
+"scripts/*" = ["T20"]
+"tests/*" = ["SLF001", "S105", "S106", "PLR2004", "EM101"]

gfunk-0.1.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+## v0.1.0 (2026-08-28)
+
+### Feat
+
+- snoop should color code by file type now
+- add recency and size sorting options to 'snoop' command
+- add gmail integration and a 'grind' command that shows agenda for next X days
+- expose gfunk vibe
+- default snoop command to opening a TUI with doc viewer
+- pdf attachments in holla archive works!
+- add a modal during archive processing (which can take a while for labels)
+- allow deletion of empty labels (warn for non-empty and reject)
+- holla command gets preview pane with scroll plus delete shortcut
+- continue expanding gfunk holla features
+- set up holla / emails command
+- gfunk dubs finds duplicates or suspected duplicates, TUI view
+- gfunk snoop now offers multi-selection with tab
+- gfunk regulate has a revoke option now
+- regulate prints a nice tui view
+- snoop gets limited live preview and a delete option (trash)
+- add dj push/pull
+- set up apps scripts api access, dj runs now prints recent runs
+- reorganize and give flavor names for each topic in the help menu
+- gfunk drop uploads a file
+- gfunk vibe gets a simple TUI viewer and replaces sample
+- add a (fairly weak) dj subcommand that opens google scripts pages
+- gfunk slide for moving items around drive with fzf and browsing
+- gfunk peep to view docs or sheets in the terminal, fzf selection
+- add gfunk dig/open, gfunk bounce/export
+- initial prototype ready
+
+### Fix
+
+- badge/readme update
+- handle some test warnings
+- trailing whitespace in readme
+- show enter instructions on snoop command
+- pre-commit + CI guard for regenerating screenshots when TUIs change
+- improve 'gfunk vibe' menu
+- blue->purple for clarity
+- TUI menu was duplicative, now it's not
+- pytext-xdist to cut test suite time in half, justfile with release script
+- publish.yml for PyPI
+- mothership/mcp should be tool-specific, details on cache in README
+- add license, gitignore terms
+- remove backlog
+- add lookback on grind command
+- improve grind tui
+- TUI descriptions in help
+- bug on vibe TUI, specifically label vibe TUI
+- visual bug when deleting holla items down from >1 to 1
+- when backing up attachments, create a directory and group renders + attachments in it
+- lint
+- cli options tweak; fix ruff toml issue driving me crazy in nvim
+- header with flavor
+- pre-commit passage
+- y/n casing
+- make revoke/delete easier in gfunk regulate
+- Greatly improve layout of TUI on regulate command
+- dj triggers label clarity
+- add scripts.projects scope
+- hanging tests, more flavor names
+- merge everything into snoop, too many similar commands
+- merged dig into peep, added a print action for snoop, update rules
+- merge snoop and slide commands into one
+- improve cli help
+- remove get-down, it was confusing overlap, just a single setup/login/mount-up command
+- downgrade to 3.13 for ruff lsp reasons
+- slight update to alias and description for gfunk sample
+- gfunk dig doesn't ask for ID if Ctrl+C out of fzf
+- mothership has install and serve sub commands now
+- narrow dig to just opening a file in your browser
+- alias sample, remove mix, alias mothership
+- pass linting
+- make mount-up do better bootstrapping

gfunk-0.1.0/Justfile

@@ -0,0 +1,21 @@
+# gfunk task runner
+
+default:
+    @echo "Usage: just <recipe>"
+    @echo ""
+    @echo "  release   Interactive version bump, review, and publish"
+    @echo "  install   Install dependencies"
+    @echo "  test      Run the test suite with coverage"
+    @echo "  lint      Run all pre-commit hooks"
+
+install:
+    uv sync
+
+release:
+    uv run python scripts/release.py
+
+test:
+    uv run pytest tests/ -q --cov=gfunk --cov-report=term-missing
+
+lint:
+    uv run pre-commit run --all-files

gfunk-0.1.0/LICENSE

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

gfunk-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: gfunk
+Version: 0.1.0
+Summary: MCP server and CLI for programmatic Google Workspace access
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: google-api-python-client>=2.198.0
+Requires-Dist: google-auth-httplib2>=0.4.1
+Requires-Dist: google-auth-oauthlib>=1.4.0
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: tabulate>=0.10.0
+Requires-Dist: textual>=3.0.0
+Requires-Dist: xhtml2pdf>=0.2.17