influxdata / influxdata/docs-v2
Claude Code cloud sessions can't run Vale (Docker unavailable, binary install blocked) and yarn lint leaves jsconfig.json dirty
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Summary
While working a content PR (#7469) from a Claude Code on-the-web / remote
sandbox session, I hit two recurring friction points worth fixing so future
agent (and human sandbox/devcontainer) sessions don't have to work around
them:
1. **Vale can't run in this class of session** — neither of its two
supported execution paths works, forcing every commit to use
`--no-verify` and skip style linting entirely.
2. **`yarn lint` leaves `assets/jsconfig.json` modified** as an apparent
side effect, adding unrelated noise to otherwise-scoped diffs.
## 1. Vale is unusable in Docker-less, GitHub-egress-restricted sessions
`.ci/vale/vale.sh` supports two run modes:
- **Local binary** (preferred, per the `vale-linting` skill and the script
itself)
- **Docker fallback** (`jdkato/vale:v3.15.1`)
Both are unavailable in this session type:
- **Docker fallback**: no Docker daemon running in the sandbox
(`failed to connect to the docker API at unix:///var/run/docker.sock`).
- **Local binary install**: the CI-documented install command —
```bash
curl -sfL "https://github.com/errata-ai/vale/releases/download/v3.15.1/vale_3.15.1_Linux_64-bit.tar.gz" \
| sudo tar xz -C /usr/local/bin vale
```
— returns HTTP 403 from the session's proxy:
```json
{"message":"GitHub access to this repository is not enabled for this session. Use add_repo to request access.","documentation_url":"..."}
```
`errata-ai/vale` isn't (and shouldn't need to be) a repo added to a
docs-v2 session's scope just to fetch a release binary.
**Impact:** `core-lint`, `enterprise-lint`, `lint-instructions`, and every
other product-specific Vale job in `lefthook.yml` fail outright in this
environment, regardless of whether the changed content has any real style
issues. The only way forward is `git commit --no-verify`, which skips
**all** pre-commit hooks for that commit, not just the Vale jobs — including
checks that would otherwise run fine and are useful (link/anchor checks
partially overlap here too, see below). PR #7469's Vale checks did pass
cleanly in real CI once pushed, confirming the content itself was fine — the
gap is purely environmental.
**Suggested directions** (pick whichever fits docs-v2's constraints best):
- Mirror the Vale binary to a host this proxy allows (e.g., an internal
artifact bucket, npm registry, or one of the already-allowlisted hosts
like `registry.npmjs.org`/`pypi.org`), so the documented local-binary
install path works without needing `errata-ai/vale` in scope.
- Vendor the Vale binary (or a thin installer script fetching from an
allowed mirror) into the repo/devcontainer setup so sandbox sessions get
it automatically, similar to how CI installs it directly in
`pr-vale-check.yml`.
- Document this specific gap (proxy-blocked GitHub release downloads +
no Docker) in the `vale-linting` skill or `AGENTS.md`'s existing
"Network-restricted environments" note, with the recommended
`--no-verify` justification spelled out, so agents don't have to
re-derive it each time.
## 2. `yarn lint` (via lefthook) leaves `assets/jsconfig.json` dirty
Running `yarn lint` in this session consistently left an uncommitted change
to `assets/jsconfig.json`:
```diff
"paths": {
"*": [
- "*"
+ "*",
+ "../node_modules/*"
]
}
```
This happened twice in the same session, each time after running the full
`yarn lint` (pre-commit + pre-push lefthook chain) — not tied to any specific
content change, and unrelated to anything intentionally edited. I reverted it
each time with `git checkout -- assets/jsconfig.json` to keep the commit
scoped, but didn't track down the exact script/tool responsible (candidates
worth checking: `build:ts`/`tsc --project tsconfig.json`, or some
IDE/language-server-style tool invoked transitively during
`validate-agent-instructions` or `packages-audit`).
**Impact:** minor, but it's silent noise that a less careful commit could
pick up unintentionally (`git add -A`-style staging would include it), and
it suggests some tool in the lint/build chain treats `jsconfig.json` as a
generated file without that being documented anywhere.
**Suggested directions:**
- If `jsconfig.json`'s `paths` entry is meant to be regenerated
automatically, document that (e.g., a comment in the file, or a note in
`assets/AGENTS.md`) and consider gitignoring the generated portion or
committing the "correct" post-generation state so it stops diffing.
- If it's not meant to be touched by tooling at all, find and fix
whatever step is writing to it (likely something invoked via `yarn lint`
or `yarn build:ts`) — happy to help track it down further if useful,
I just didn't want to block the PR this surfaced on chasing it down.
## Context
Both surfaced while working PR
[#7469](https://github.com/influxdata/docs-v2/pull/7469) (InfluxDB 3
canonical frontmatter fix) from a Claude Code remote/cloud session — not
specific to that PR's content, but to the session environment itself.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with .ci/vale/vale.sh, lefthook.yml, pr-vale-check.yml, and the vale-linting or AGENTS.md guidance to define a workable restricted-session path. Then trace yarn lint and build:ts for writes to assets/jsconfig.json. Done means Vale checks have a documented or supported execution path and lint no longer leaves unintended changes, verified with the relevant lint commands and a clean git diff.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, javascript, shell
- Domain
- build-system, devops, documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100