gsheets-speckit

Spec-kit slash command bridge for google-sheet-fetcher. Installs the /speckit.sheets-* commands into a Claude Code project so you can pull test cases from a Google Sheet, generate Playwright tests from them, and push the run results back to the sheet — all from inside Claude Code.

Zero Node dependencies. Bundles the Python workers under vendor/python/ and shells out via python3.

Installation

npm install gsheets-speckit
npx gsheets-speckit init

init copies three slash command files into .claude/commands/ and adds the necessary entries to .gitignore.

Prerequisites

| Tool | Required? | Why | |---|---|---| | Node.js ≥ 18 | yes | runs the CLI + slash command resolution | | python3 on PATH | yes | runs the bundled Python workers in vendor/python/ | | google-api-python-client + google-auth | optional | required only for private sheets and for the --write-back flow | | @playwright/test in the project | optional | required only for /speckit.sheets-report |

The installer prints a warning (but does not fail) if python3 is missing. You can check at any time with:

npx gsheets-speckit status

which shows both slash command install status and Python runtime availability.

To enable private-sheet access or results write-back:

pip install google-api-python-client google-auth

The three slash commands

/speckit.sheets-pull <sheet-url> [--credentials <path>] [--sheet-name <tab>]

Pulls test cases from a Google Sheet (public CSV export or private Sheets API) and writes structured JSON to .gsheets/pull/latest/. Public sheets need no credentials.

/speckit.sheets-generate [--input-dir <dir>] [--app-url <url>]

Reads .gsheets/pull/latest/test_suite.json and generates one Playwright .spec.ts file per test case under tests/gsheets-generated/. Also writes a traceability file mapping each sheet TC-ID to the generated test name — this is what the report step uses to write status back to the right row.

/speckit.sheets-report [--test-dir <dir>] [--app-url <url>] [--write-back] [--credentials <path>] [--sheet-url <url>]

Runs npx playwright test on the generated tests, captures the JSON report under .gsheets/report/<timestamp>/, and — when --write-back is supplied — invokes vendor/python/write_results.py to push pass/fail status back to the sheet.

Credentials

For private sheets and results write-back you need a Google service-account JSON.

• Recommended path: .argus/credentials/service-account.json. This path is already gitignored (argus-qa adds .argus/ to gitignore, and gsheets-speckit adds .argus/credentials/ if argus-qa is not installed).
• The service account must have Editor access on the target sheet if you intend to use --write-back. View-only access is sufficient for pull.
• Never commit the JSON file. Never paste its contents into chat. The slash command bodies tell Claude to never log credentials.

Public vs private behavior

| Sheet visibility | pull | report --write-back | |---|---|---| | Public (anyone with link can view) | uses the CSV export endpoint via urllib — no pip deps | requires google-api-python-client + a credential with Editor access on the sheet | | Private | requires google-api-python-client + service-account credentials with at least Viewer access | requires Editor access |

The scope requested is https://www.googleapis.com/auth/spreadsheets (read+write) so a single credential covers both read and write-back flows.

CLI reference

npx gsheets-speckit help        # usage
npx gsheets-speckit init        # install slash commands + update .gitignore
npx gsheets-speckit update      # re-install (overwrite existing)
npx gsheets-speckit status      # show install status + python availability
npx gsheets-speckit uninstall   # remove installed files
npx gsheets-speckit version     # print package version

Flags: --force, --dry-run, --yes.

Programmatic API

const gs = require('gsheets-speckit');

gs.install({ force: true });
const py = gs.checkPython();
const api = gs.checkGoogleApiClient();
const scriptPath = gs.vendorScript('fetch_tests.py');

See src/index.js for the full export list.

License

MIT © Manoj Tyagi