google-sheets-mcp-and-skill 0.4.0__tar.gz

google_sheets_mcp_and_skill-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,65 @@
+---
+name: Bug report
+about: Report something that is broken or behaves incorrectly
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+<!--
+Thanks for filing a bug. Before you submit:
+- Search existing issues to avoid duplicates.
+- NEVER paste real credentials, tokens, service-account keys, or a real spreadsheet ID.
+  Use <YOUR_SPREADSHEET_ID> as a placeholder and redact any personal data.
+-->
+
+## What happened
+
+A clear, concise description of the bug.
+
+## What you expected
+
+What you expected to happen instead.
+
+## Entrypoint
+
+Which adapter were you using? (the behavior should be identical from either)
+
+- [ ] CLI (`gsheets`)
+- [ ] MCP server (`google-sheets-mcp`)
+- [ ] Calling `gsheets.core` directly
+
+## Which tool / subcommand
+
+e.g. `inspect`, `read-conditional-formats`, `format`, `set-conditional-format`, …
+
+## Steps to reproduce
+
+A minimal reproduction. Redact real IDs.
+
+```sh
+# Example — replace <YOUR_SPREADSHEET_ID> with a placeholder, never a real id
+gsheets inspect <YOUR_SPREADSHEET_ID> 'Sheet1!A1:D20' --compact
+```
+
+## Actual output / error
+
+Paste the command output or error envelope. Redact any account email or real id.
+
+```text
+
+```
+
+## Environment
+
+- Package version (`gsheets --version` or the installed version):
+- Python version (`python --version`):
+- OS:
+- Auth mode (`GSHEETS_AUTH_MODE`): `service_account` / `oauth` / `adc` / `auto`
+- Installed via: `uv sync` from source / `uv tool install` / `uvx` / other
+
+## Additional context
+
+Anything else that helps — a redacted snippet of the sheet, related issues, a guess at
+the cause. If you can share a minimal redacted golden-master JSON that triggers it, that
+is ideal.

google_sheets_mcp_and_skill-0.4.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,13 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or usage help
+    url: https://github.com/colindmurray/google-sheets-mcp-and-skill/discussions
+    about: >
+      For "how do I…" questions, setup/auth help, or general discussion, please open a
+      Discussion instead of an issue. Never share real credentials or a real spreadsheet
+      ID — use <YOUR_SPREADSHEET_ID>.
+  - name: Security vulnerability
+    url: https://github.com/colindmurray/google-sheets-mcp-and-skill/security/advisories/new
+    about: >
+      Report security vulnerabilities privately via a GitHub security advisory, not a
+      public issue.

google_sheets_mcp_and_skill-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,54 @@
+---
+name: Feature request
+about: Propose a new capability or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+<!--
+Thanks for proposing an improvement. Before you submit:
+- Search existing issues to avoid duplicates.
+- NEVER include real credentials or a real spreadsheet ID. Use <YOUR_SPREADSHEET_ID>.
+- Skim docs/ARCHITECTURE.md and CONTRIBUTING.md — new behavior must fit the
+  pure-core / thin-adapter design and map 1:1 to BOTH adapters.
+-->
+
+## The problem / use case
+
+What are you trying to do with a spreadsheet that you can't (cleanly) do today? Describe
+the workflow, not just the API call.
+
+## Proposed solution
+
+What would you like to see? If it is a new tool, sketch it:
+
+- **Core function name** (and signature, if you have one in mind):
+- **What it reads or writes:**
+- **Return shape** (remember: anything writable should be readable back — CRUD symmetry):
+- **MCP tool name** (`sheets_…`) **and CLI subcommand** (`…`):
+
+## Read-side richness?
+
+This project's thesis is rich, token-efficient, round-trippable **reads**. Does this
+proposal improve a read (values/formulas/formatting/conditional-format/validation/
+structure)? If so, say how it stays token-efficient (tight `fields` mask, flattened
+output, optional compact mode).
+
+## Alternatives considered
+
+Including: can the existing `batch` escape hatch already do this? If so, why is a typed
+tool worth adding?
+
+## Design fit checklist
+
+- [ ] Fits the pure-core / thin-adapter boundary (logic in core, one-line adapter bodies)
+- [ ] Maps 1:1 to both the MCP tool and the CLI subcommand
+- [ ] Preserves CRUD symmetry (writable ⇒ readable back) where applicable
+- [ ] Token-efficient by default (no `includeGridData`; tight `fields` mask)
+- [ ] No real IDs / credentials / personal info anywhere in the proposal
+
+## Additional context
+
+Examples (using `<YOUR_SPREADSHEET_ID>`), references to the Google Sheets API surface,
+prior art in other tools, or anything else that helps.

google_sheets_mcp_and_skill-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,65 @@
+<!--
+Thanks for contributing! Please fill this out so reviewers can move quickly.
+Read CONTRIBUTING.md first if you haven't — especially the pure-core / thin-adapter rule.
+NEVER include real credentials, tokens, keys, or a real spreadsheet ID anywhere in this
+PR. Use <YOUR_SPREADSHEET_ID> in examples.
+-->
+
+## What & why
+
+What does this PR change, and why? Link any related issue (`Closes #123`).
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] New tool / capability (a core function + its model + MCP tool + CLI subcommand)
+- [ ] Improvement to an existing tool
+- [ ] Docs only
+- [ ] Refactor / internal (no behavior change)
+- [ ] Breaking change (changes a public core signature or output shape)
+
+## Architecture boundary (must hold)
+
+- [ ] No `fastmcp` / `mcp` / `argparse` / `pydantic` / `gsheets.models` import was added
+      to any `core/**` or `auth/**` module.
+- [ ] Sheets logic lives in core; adapter tool/subcommand bodies stay essentially
+      one-line (resolve services → call core → return/print).
+- [ ] `uv run pytest` passes, **including** the subprocess boundary-guard test.
+
+## If this adds or changes a tool
+
+Confirm the 1:1 mapping is complete across all entrypoints:
+
+- [ ] Core function implemented and re-exported from `gsheets/core/__init__.py`
+- [ ] Unit test added/updated (with a golden-master fixture if it serializes/parses)
+- [ ] Pydantic mirror model in `models.py` (same field names as the core dict)
+- [ ] MCP tool registered with correct `ToolAnnotations` + an example-rich docstring
+- [ ] CLI subcommand added (flags map 1:1 to core kwargs; supports `--json`)
+- [ ] Docs updated (`SKILL.md` command map, `skill/references/*`, `docs/ARCHITECTURE.md`)
+- [ ] CRUD symmetry preserved where applicable (writable ⇒ readable back)
+
+## Security & privacy (this repo is public)
+
+- [ ] No credentials, tokens, keys, real spreadsheet IDs, or personal info added to the
+      committed tree (`src/`, `tests/`, `docs/`, `README`, `SKILL.md`, `examples/`).
+- [ ] Examples use the `<YOUR_SPREADSHEET_ID>` placeholder.
+- [ ] No new error message leaks the operator's account email by default.
+
+## Changelog
+
+- [ ] Added an entry under `## [Unreleased]` in `CHANGELOG.md`.
+
+## How I tested
+
+Describe what you ran (e.g. `uv run pytest`, a specific subcommand against a throwaway
+sheet via the env-gated live tests). Redact any real ids.
+
+```text
+
+```
+
+## Breaking changes / notes for reviewers
+
+If you changed a public core signature, list every caller you updated (core fn, model,
+MCP tool, CLI subcommand, tests, docs) and why the change was necessary. Otherwise,
+delete this section.

google_sheets_mcp_and_skill-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync
+      - name: Test (mocked suite, includes the boundary-guard test)
+        run: uv run pytest

google_sheets_mcp_and_skill-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release to PyPI
+
+# Publishes the package to PyPI via Trusted Publishing (OIDC) — NO stored API token.
+#
+# Triggers:
+#   - pushing a version tag (v*), e.g. `git tag -a v0.4.1 && git push origin v0.4.1`
+#   - manual `workflow_dispatch` (used for the very first release of an already-cut tag)
+#
+# PyPI side (one-time): register a Trusted Publisher for project
+# `google-sheets-mcp-and-skill` with owner `colindmurray`, repository
+# `google-sheets-mcp-and-skill`, workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build & test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Run the test suite (gate the release on green tests)
+        run: uv run --frozen pytest -q
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The Trusted Publisher is scoped to this environment on PyPI; it also lets you add
+    # an optional required-reviewer protection rule in the repo's Settings → Environments.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/google-sheets-mcp-and-skill
+    permissions:
+      id-token: write # OIDC: mint the short-lived token PyPI exchanges for upload rights
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

google_sheets_mcp_and_skill-0.4.0/.gitignore

@@ -0,0 +1,53 @@
+# Internal build brief / design / research — gitignored (contains real IDs)
+internal/
+
+# Local stress-test issue log + resolutions — contains real spreadsheet IDs (keep out of this public repo)
+ISSUES.md
+
+# Local maintainer planning/working docs — for the maintainer's own use, never part of the public package
+ENHANCEMENTS.md
+SPEC.md
+
+# Agent-instruction files — kept locally for AI-assisted dev, intentionally NOT in the public repo
+CLAUDE.md
+AGENTS.md
+GEMINI.md
+.cursorrules
+
+# Python build & packaging
+build/
+dist/
+*.egg-info/
+*.egg
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test & tooling caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.cache/
+
+# Credentials — NEVER commit (real creds live outside the repo at runtime)
+gcp-oauth.keys.json
+token.json
+service-account*.json
+credentials.json
+*.pem
+.env
+.env.*
+
+# Editor / OS cruft
+.DS_Store
+*.swp
+.idea/
+.vscode/