grove-setup

# Grove: Set Up Local Environment <!-- canary:56f422c8 --> 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: ```json { "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# (Driver + EF Core) | `code-example-tests/csharp/driver/` | | Mongosh | `code-example-tests/command-line/mongosh/` | EF Core examples and tests live under `Examples/EfCore/` and `Tests/EfCore/` in the C# driver directory — same setup as the driver suite. **Out of scope**: `java/driver-reactive/`, `go/atlas-sdk/`, and `openapi/` — see each project's README. ## 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 >= 24.4.1, Python >= 3.9, Go >= 1.24, Java >= 21, .NET >= 10.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 ```bash cd code-example-tests/javascript/driver && npm install ``` ### Python ```bash 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 ```bash cd code-example-tests/go/driver && go mod download ``` ### Java ```bash 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\# ```bash cd code-example-tests/csharp/driver && dotnet restore ``` ### Mongosh ```bash cd code-example-tests/command-line/mongosh && npm install ``` Report success or failure. If install fails, diagnose the error (version mismatch, network issue, etc.). ### Full pipeline script Each main suite includes `run-tests.js` (format → test → snip with connectivity preflight). After dependencies are installed, writers can verify the full workflow with: ```bash cd code-example-tests/{driver-dir} && node run-tests.js ``` Use `--no-snip` to skip snippet extraction. This is optional during setup — the smoke test in Step 7 uses lighter-weight test commands. ### Bluehawk (all suites) Bluehawk is required when **creating or modifying examples** — it extracts doc-ready snippets from example files. Check whether it is installed: ```bash which bluehawk ``` If not found, tell the user to install it globally: ```bash 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 / C# | `CONNECTION_STRING="<connection-string>"` | | Java | `CONNECTION_STRING` — export in the shell (`export CONNECTION_STRING="..."`) or place a `.env` file in `code-example-tests/java/driver-sync/` or `code-example-tests/java/` (loaded by `node run-tests.js`, not by raw `mvn test`) | | Mongosh | `CONNECTION_STRING="<connection-string>"`, `CONNECTION_PORT="<port>"` (port for local deployments; optional for Atlas SRV URIs) | 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): ```bash 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): ```bash 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~ExampleStubTest"` | | Mongosh | `cd code-example-tests/command-line/mongosh && npm test -- -t 'Should count all documents in the sample_mflix'` | 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`: ```markdown