influxdata / influxdata/docs-v2

Claude Code cloud sessions can't run Vale (Docker unavailable, binary install blocked) and yarn lint leaves jsconfig.json dirty

Open
#7,470 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ci tooling
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.