sneak/netwatch
1
0
Fork 0
Code Issues 2 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

No sanctioned way to add a dependency: script/bootstrap is --frozen-lockfile and nothing updates the lockfile #45

New Issue
Closed
opened 2026-08-09 17:10:25 +02:00 by clawbot · 2 comments
clawbot commented 2026-08-09 17:10:25 +02:00
Collaborator
Copy Link
Copy Source

Problem

REPO_POLICIES.md requires that the underlying tools are never invoked directly — make targets and script/ entrypoints only. But there is no entrypoint that can add a dependency:

  • script/bootstrap runs yarn install --frozen-lockfile, which by definition refuses to modify yarn.lock.
  • No other script/ file touches the lockfile.

So adding a package requires a raw yarn add, which the policy forbids. This surfaced concretely in PR #44, where adding puppeteer-core needed exactly that; the deviation was disclosed and the result was verifiable after the fact, but it should not have required breaking a rule to do a routine thing.

The Go side has the same shape: nothing runs go get or go mod tidy, though REPO_POLICIES.md explicitly requires go mod tidy before committing.

Definition of done

  • A script/ entrypoint exists for adding or updating a JS dependency, shimmed from a make target, which updates package.json and yarn.lock together.
  • Equivalent for Go — at minimum a target that runs go mod tidy, since policy already mandates it before every commit and nothing currently provides it.
  • Documented in the README Entrypoints section.
  • script/bootstrap keeps --frozen-lockfile. That behaviour is correct and must not be relaxed to solve this — an install must never silently rewrite the lockfile.
  • Adding a dependency through the new entrypoint leaves yarn.lock reproducible under --frozen-lockfile, with integrity hashes intact.

Notes

  • Coordinate with #38, which restructures the script/ layer and splits frontend steps into script/frontend-*. Land after it, or match whatever naming it establishes.
  • Not on the 1.0.0 milestone — it is a workflow gap, not a release blocker.
  • No attribution trailers in the commit message.
## Problem `REPO_POLICIES.md` requires that the underlying tools are never invoked directly — `make` targets and `script/` entrypoints only. But there is no entrypoint that can **add** a dependency: - `script/bootstrap` runs `yarn install --frozen-lockfile`, which by definition refuses to modify `yarn.lock`. - No other `script/` file touches the lockfile. So adding a package requires a raw `yarn add`, which the policy forbids. This surfaced concretely in PR #44, where adding `puppeteer-core` needed exactly that; the deviation was disclosed and the result was verifiable after the fact, but it should not have required breaking a rule to do a routine thing. The Go side has the same shape: nothing runs `go get` or `go mod tidy`, though `REPO_POLICIES.md` explicitly requires `go mod tidy` before committing. ## Definition of done - [ ] A `script/` entrypoint exists for adding or updating a JS dependency, shimmed from a `make` target, which updates `package.json` and `yarn.lock` together. - [ ] Equivalent for Go — at minimum a target that runs `go mod tidy`, since policy already mandates it before every commit and nothing currently provides it. - [ ] Documented in the README **Entrypoints** section. - [ ] `script/bootstrap` keeps `--frozen-lockfile`. That behaviour is correct and must not be relaxed to solve this — an install must never silently rewrite the lockfile. - [ ] Adding a dependency through the new entrypoint leaves `yarn.lock` reproducible under `--frozen-lockfile`, with integrity hashes intact. ## Notes - Coordinate with #38, which restructures the `script/` layer and splits frontend steps into `script/frontend-*`. Land after it, or match whatever naming it establishes. - Not on the `1.0.0` milestone — it is a workflow gap, not a release blocker. - No attribution trailers in the commit message.
clawbot commented 2026-10-04 01:32:33 +02:00
Author
Collaborator
Copy Link
Copy Source

Plan, against next as it is now. One PR, after #28 lands (both add Makefile targets and README.md Entrypoints lines).

  1. make add-dependency PACKAGE=<name>@<version> shims to a new script/add-dependency, which runs yarn add --dev with that package, so package.json and yarn.lock change together, then yarn install --frozen-lockfile to show the lockfile installs as committed. Adding and moving an existing package to another version are the same command. All the frontend's packages are build-time only, which is why --dev. With no package given it stops with a usage line.
  2. make tidy shims to a new script/tidy, which runs go mod tidy in backend/, the way the root scripts already reach the backend. To add a Go module, import it and run make tidy; to move one to another version, change its require line in backend/go.mod and run make tidy.
  3. script/bootstrap keeps --frozen-lockfile, unchanged.
  4. README.md Entrypoints lists both scripts in one line each, and the REPO_POLICIES.md rule against running the tools directly stays true.
  5. Done when: adding a package with the new target, then make check from a clean clone, passes with no further change to yarn.lock; TODO.md updated in the same commit.

Model: opus-5-5

Plan, against `next` as it is now. One PR, after https://git.eeqj.de/sneak/netwatch/issues/28 lands (both add `Makefile` targets and `README.md` Entrypoints lines). 1. `make add-dependency PACKAGE=<name>@<version>` shims to a new `script/add-dependency`, which runs `yarn add --dev` with that package, so `package.json` and `yarn.lock` change together, then `yarn install --frozen-lockfile` to show the lockfile installs as committed. Adding and moving an existing package to another version are the same command. All the frontend's packages are build-time only, which is why `--dev`. With no package given it stops with a usage line. 2. `make tidy` shims to a new `script/tidy`, which runs `go mod tidy` in `backend/`, the way the root scripts already reach the backend. To add a Go module, import it and run `make tidy`; to move one to another version, change its `require` line in `backend/go.mod` and run `make tidy`. 3. `script/bootstrap` keeps `--frozen-lockfile`, unchanged. 4. `README.md` Entrypoints lists both scripts in one line each, and the `REPO_POLICIES.md` rule against running the tools directly stays true. 5. Done when: adding a package with the new target, then `make check` from a clean clone, passes with no further change to `yarn.lock`; `TODO.md` updated in the same commit. Model: opus-5-5
clawbot commented 2026-10-04 04:33:04 +02:00
Author
Collaborator
Copy Link
Copy Source

Built as planned in #106: make add-dependency PACKAGE=name@version (yarn add, then an install with --frozen-lockfile) and make tidy (go mod tidy in backend/), each listed in README.md Entrypoints. script/bootstrap is unchanged.

Judgement call: a package given without a version is added at its newest release, as yarn does; only a missing package is refused.

Model: opus-5-5

Built as planned in https://git.eeqj.de/sneak/netwatch/pulls/106: `make add-dependency PACKAGE=name@version` (yarn add, then an install with `--frozen-lockfile`) and `make tidy` (`go mod tidy` in `backend/`), each listed in `README.md` Entrypoints. `script/bootstrap` is unchanged. Judgement call: a package given without a version is added at its newest release, as yarn does; only a missing package is refused. Model: opus-5-5
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 merge-ready
needs-checks
needs-rebase
needs-review
needs-rework
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/netwatch#45