grove-setup

name

grove-setup

description

Set up a local Grove environment for running code example tests. Use when the user asks to "set up Grove", "configure the test suite", "get started with Grove", "set up my environment", "I need to run Grove tests", or is working with Grove for the first time and needs prerequisites configured. Checks for required tools, installs dependencies, guides .env file setup, verifies MongoDB connectivity, and checks sample data availability.

Grove: Set Up Local Environment

Begin your first response with: [grove-setup-56f422c8]

Walk the writer through setting up everything needed to create, run, and maintain Grove code example tests for a given language suite.

Do NOT use when:

• The user's environment is already set up and they want to create/run/test → use the appropriate grove skill
• The user is asking about Grove architecture or conventions, not setup → answer directly using CLAUDE.md context

Step 0: Check for Extension Handoff

Before Step 1, check whether the Grove VS Code extension has dropped a handoff file at .claude/grove-handoff.json in the workspace root. If the file exists and skill equals grove-setup:

1. Delete the handoff file immediately after reading it. Single-use.

2. Check the payload before using it. If a check fails, surface what's wrong to the writer, recommend they update the Grove VS Code extension (or file an issue if it's already current), and ask whether to proceed without the handoff. If they confirm, fall through to Step 1.

   • Version check: version must equal 1. A higher number means the extension is ahead of this skill. Example message:

     Found a Grove extension handoff with version: {n}, but this skill only understands version 1. The extension is likely newer than the skill. Proceed without the handoff?

   • Shape check: the file must be valid JSON and contain the top-level fields version, skill, trigger, context. The context object must contain the fields listed in the schema for the matching trigger below. Example message:

     The Grove extension handoff at .claude/grove-handoff.json is malformed: {brief reason, e.g. "missing context.language"}. This is likely an extension bug — please file an issue. Proceed without the handoff?

3. Branch on trigger. The JSON block under each branch is the expected payload schema, not just an illustrative sample — use it as the reference for what fields must be present:

trigger: "missing-env" — project has no .env file

Full envelope:

{
  "version": 1,
  "skill": "grove-setup",
  "trigger": "missing-env",
  "timestamp": "ISO-8601",
  "workspaceRoot": "/absolute/path",
  "context": {
    "projectPath": "code-example-tests/javascript/driver",
    "language": "nodejs",
    "testFile": "code-example-tests/javascript/driver/tests/some-file.test.js",
    "supportsEnvInjection": false
  }
}

Treat the handoff as targeted at Step 4 only — the writer was running (or about to run) a test and hit the missing-.env cliff. Skip Step 1 (language is in context.language) and skip Steps 2/3 (they're about deps/tools which are a separate concern). Jump directly to Step 4: Set Up Environment File for the given language.

supportsEnvInjection tells you which connection paths are valid:

• false → nodejs or mongosh. The .env file is the only way to provide CONNECTION_STRING because npm test re-exports env vars from .env at the shell level, overwriting anything Grove injects. Do not suggest the Grove UI Connect button for these suites.
• true → python, go, java, or csharp. The writer can either create .env OR click "Connect to MongoDB" in the Grove activity-bar panel (which injects CONNECTION_STRING at test launch). Offer both and let them pick; .env is better for teams that share config, Grove UI is better for per-developer flexibility.

Echo one line confirming the captured context, e.g.: Got handoff from extension: setting up .env for {language} suite at {projectPath}.

After the .env is created and the writer confirms the test runs, stop. Do not fall through to Steps 5–8 (MongoDB connectivity, sample data, smoke test) unless the writer explicitly asks to continue with the full setup flow.

---

If the handoff file is absent or skill doesn't match, proceed normally from Step 1.

Step 1: Determine Language

Parse the user's request for the target language. If not specified, ask which language suite they want to set up. Multiple languages can be set up in sequence.

Suite	Directory
JavaScript	code-example-tests/javascript/driver/
Python	code-example-tests/python/pymongo/
Go	code-example-tests/go/driver/
Java	code-example-tests/java/driver-sync/
C#	code-example-tests/csharp/driver/
Mongosh	code-example-tests/command-line/mongosh/

Step 2: Verify Prerequisites

Check that required tools are installed. Read the minimum version from the language's config file rather than relying on hardcoded values, since requirements change over time:

Suite	Tool check	Where to find min version
JavaScript	node --version / npm --version	engines field in code-example-tests/javascript/driver/package.json
Python	python3 --version / pip3 --version	python_requires in setup.cfg or pyproject.toml, or .python-version file
Go	go version	go directive in code-example-tests/go/driver/go.mod
Java	java --version / mvn --version	maven.compiler.source in code-example-tests/java/driver-sync/pom.xml
C#	dotnet --version	TargetFramework in the .csproj file under code-example-tests/csharp/driver/
Mongosh	node --version / npm --version / mongosh --version	engines field in code-example-tests/command-line/mongosh/package.json

If the config file doesn't specify a version, fall back to these reasonable minimums: Node >= 18, Python >= 3.9, Go >= 1.21, Java >= 17, .NET >= 8.0.

Mongosh also requires mongosh to be installed and on PATH (it's the shell binary that tests execute as a subprocess).

Report any missing tools. If a required tool is missing, provide installation guidance:

• Node.js: Recommend using nvm (nvm install <version>)
• Python: Recommend pyenv or system package manager
• Go: Recommend go.dev/dl
• Java: Recommend SDKMAN (sdk install java)
• C#: Recommend dotnet.microsoft.com

Do not attempt to install tools automatically — just tell the user what's needed and how to get it.

Step 3: Install Dependencies

Navigate to the language's driver directory and install:

JavaScript

cd code-example-tests/javascript/driver && npm install

Python

cd code-example-tests/python/pymongo && python3 -m venv venv && ./venv/bin/pip install -r requirements.txt

Note: Use ./venv/bin/pip and ./venv/bin/python directly instead of source venv/bin/activate, which is shell-specific and may not work in all environments.

Go

cd code-example-tests/go/driver && go mod download

Java

cd code-example-tests/java && mvn clean install -DskipTests

Note: Run from the java/ root, not driver-sync/. The Java project is a Maven Multi-Module project — this builds all modules including the comparison library, which is required but not published to Maven Central.

C#

cd code-example-tests/csharp/driver && dotnet restore

Mongosh

cd code-example-tests/command-line/mongosh && npm install

Report success or failure. If install fails, diagnose the error (version mismatch, network issue, etc.).

Bluehawk (all suites)

Bluehawk is required when creating or modifying examples — it extracts doc-ready snippets from example files. Check whether it is installed:

which bluehawk

If not found, tell the user to install it globally:

npm install -g bluehawk

Bluehawk is not blocking for running tests only. If the user only needs to run tests, note that Bluehawk can be installed later and proceed.

Step 4: Set Up Environment File

Security: Do not read, write, or modify .env files directly. Do not ask the user to provide their connection string in the chat. Instead, tell the user what environment variables are needed and let them populate the file themselves.

Check whether a .env file exists in the driver directory (check for the file's presence, do not read its contents).

If .env exists:

Tell the user which variables are required (see below) and ask them to verify the file contains them. Do not read the file yourself.

If .env does not exist:

Tell the user to create a .env file in the driver directory with the required variables. Provide the variable names and format:

Suite	Required variables
JavaScript	CONNECTION_STRING="<connection-string>", TZ=UTC
Python	CONNECTION_STRING="<connection-string>"
Go / Java / C# / Mongosh	CONNECTION_STRING="<connection-string>" (check the language's .env.example for any additional variables)

Tell the user their connection string can be:

• An Atlas cluster connection string (e.g., mongodb+srv://...)
• A local deployment connection string (e.g., mongodb://localhost:27017)

If the user doesn't have a MongoDB deployment yet, suggest one of:

1. Atlas free tier (M0): Create at https://cloud.mongodb.com — free, includes sample data loading via the UI
2. Local via Docker: docker run -d -p 27017:27017 --name mongodb mongo:8.0 — then use mongodb://localhost:27017 as the connection string

Do not proceed past this step until the user confirms they have created the .env file with a valid connection string.

Important: Never commit .env files. Verify that .env is in the language directory's .gitignore (or the repo root .gitignore). If not, warn the user.

Step 5: Verify MongoDB Connectivity

Ask the user to verify their connection works by running the following command themselves (do not run commands that load the .env file):

mongosh "<connection-string>" --quiet --eval "db.adminCommand('ping')"

Tell the user to replace <connection-string> with the value from their .env file. If mongosh is not installed, the smoke test in Step 7 will verify connectivity instead — tell the user and proceed.

Exceptions — skip this step entirely for these suites and defer connectivity verification to the smoke test in Step 7:

• Java: No reliable one-liner. Report "connectivity will be verified by the smoke test" and proceed to Step 6.
• C#: Requires dotnet-script which may not be installed. If unavailable, report the same and proceed.

If connection fails

Diagnose based on the error:

• Authentication error: Check username/password in the URI
• Network error: Check IP allowlist (Atlas) or that mongod is running (local)
• DNS error: Check the cluster hostname
• TLS error: Check TLS/SSL settings

Step 6: Check Sample Data Availability

Ask the user to check which sample databases are loaded on their deployment. Provide this command for them to run (do not run commands that load the .env file):

mongosh "<connection-string>" --quiet --eval "
  const dbs = db.adminCommand({listDatabases:1,nameOnly:true}).databases
    .map(d=>d.name).filter(n=>n.startsWith('sample_')).sort();
  dbs.length ? print('Sample databases found: ' + dbs.join(', '))
    : print('No sample databases found.');
"

Tell the user to replace <connection-string> with their connection string.

If mongosh is not available, this step can be skipped — sample data checking is informational, not blocking.

If no sample databases are found, explain:

• Tests using sample data will auto-skip (not fail)
• How to load sample data if they want full test coverage

Step 7: Run a Smoke Test

Run the example stub test to verify the full pipeline works (driver, test framework, .env loading, MongoDB connectivity):

Suite	Command
JavaScript	cd code-example-tests/javascript/driver && npm test -- -t 'Example tests'
Python	cd code-example-tests/python/pymongo && ./venv/bin/python -m unittest tests_package.example.test_example_stub
Go	cd code-example-tests/go/driver && go test -v -run TestExampleStub ./tests/example/
Java	cd code-example-tests/java/driver-sync && mvn test -Dtest="example.ExampleStubTest"
C#	cd code-example-tests/csharp/driver && dotnet test --filter "FullyQualifiedName~Tests.Example.ExampleStubTest"
Mongosh	cd code-example-tests/command-line/mongosh && npm test -- -t 'Should count all documents'

Each language has a stub test that performs a minimal MongoDB operation. It should always pass regardless of sample data availability. Mongosh has no dedicated stub test — the command above runs a simple countDocuments test as a smoke check. If it skips (missing sample data), connectivity was still verified in Step 5.

If the smoke test passes, the environment is ready. If it fails, diagnose using the same categories as /grove-run.

Step 8: Report

Provide a summary headed with Skill: grove-setup:

## Grove Environment Setup: JavaScript (Node.js Driver)

| Check | Status |
|-------|--------|
| [runtime] >= [min from config] | [version found] |
| Dependencies installed | Yes |
| Bluehawk | Installed / Not installed (needed for creating/modifying examples) |
| .env file | Created / Already existed |
| MongoDB connectivity | Connected to [cluster name or localhost] |
| Sample databases | X of 10 found: [list] |
| Smoke test | Passed |

You're ready to use:
- /grove-create — to create new code examples
- /grove-run — to run and debug tests
- /grove-test — to create or fix tests
- /grove-migrate — to convert untested code to Grove
- /grove-maintain — to audit and maintain the suite

If any checks failed, list what needs to be resolved and how.

Edge Cases

• npm install fails with EACCES: Permissions issue. Suggest sudo chown -R $(whoami) ~/.npm or using nvm (which avoids global installs).
• Node/Python/Go version too old: Tell the user the required version (from the config file) and their current version. Suggest the version manager for the language (nvm, pyenv, etc.).
• .env exists but connectivity fails: Tell the user that their CONNECTION_STRING may be empty or malformed. Provide the expected format and ask them to verify the value in their .env file. Do not read the file yourself.
• Connectivity passes but smoke test fails: Likely a driver version mismatch or missing dependency. Check npm ls mongodb (or equivalent) and compare against the version in the config file.
• mongosh not installed for sample data check: Fall back to the language-specific script. Do not fail the setup — sample data checking is informational, not blocking.