Compare commits
1 Commits
1e290a63cf
...
feature/mo
| Author | SHA1 | Date | |
|---|---|---|---|
|
4ecdd8027b |
@@ -1,6 +1,5 @@
|
||||
node_modules
|
||||
dist
|
||||
tmp
|
||||
.DS_Store
|
||||
*.log
|
||||
.claude
|
||||
|
||||
@@ -6,5 +6,5 @@ jobs:
|
||||
steps:
|
||||
# actions/checkout v4.2.2, 2026-02-22
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
|
||||
- run: script/cibuild
|
||||
- run: docker build .
|
||||
- run: docker build -f Dockerfile.backend .
|
||||
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,5 +1,4 @@
|
||||
node_modules/
|
||||
dist/
|
||||
tmp/
|
||||
.DS_Store
|
||||
*.log
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
backend/
|
||||
dist/
|
||||
node_modules/
|
||||
tmp/
|
||||
yarn.lock
|
||||
.claude/
|
||||
|
||||
@@ -3,12 +3,9 @@ FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e3
|
||||
WORKDIR /app
|
||||
COPY package.json yarn.lock ./
|
||||
RUN yarn install --frozen-lockfile
|
||||
RUN apk add --no-cache git make
|
||||
RUN apk add --no-cache git
|
||||
COPY . .
|
||||
# make check runs script/check (test + lint + fmt-check); its test step
|
||||
# is the production yarn build, so this both produces dist/ and gates the
|
||||
# image on lint/fmt-check/test regressions, not merely a broken build.
|
||||
RUN make check
|
||||
RUN yarn build
|
||||
|
||||
# nginx:stable-alpine as of 2026-02-22
|
||||
FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab
|
||||
|
||||
35
Makefile
35
Makefile
@@ -1,42 +1,21 @@
|
||||
.PHONY: bootstrap setup dev test lint fmt fmt-check check \
|
||||
frontend-viewport-test docker hooks
|
||||
|
||||
# Standard targets are thin shims; the implementations live in script/
|
||||
# per the scripts-to-rule-them-all pattern (see the Entrypoints section
|
||||
# of README.md).
|
||||
|
||||
bootstrap:
|
||||
@script/bootstrap
|
||||
|
||||
setup:
|
||||
@script/setup
|
||||
.PHONY: dev test lint fmt fmt-check check docker
|
||||
|
||||
dev:
|
||||
yarn dev
|
||||
|
||||
test:
|
||||
@script/test
|
||||
timeout 30 yarn build
|
||||
|
||||
lint:
|
||||
@script/lint
|
||||
yarn prettier --check .
|
||||
|
||||
fmt:
|
||||
@script/fmt
|
||||
yarn prettier --write .
|
||||
|
||||
fmt-check:
|
||||
@script/fmt-check
|
||||
yarn prettier --check .
|
||||
|
||||
check:
|
||||
@script/check
|
||||
|
||||
# Responsive-layout verification in a containerised browser. Kept out of
|
||||
# check: it needs Docker and takes minutes, where make test has to stay
|
||||
# under 20 seconds.
|
||||
frontend-viewport-test:
|
||||
@script/frontend-viewport-test
|
||||
check: test lint fmt-check
|
||||
|
||||
docker:
|
||||
@script/docker
|
||||
|
||||
hooks:
|
||||
@script/install-precommit
|
||||
timeout 300 docker build -t netwatch .
|
||||
|
||||
37
README.md
37
README.md
@@ -23,43 +23,6 @@ docker build -t netwatch .
|
||||
docker run -p 8080:8080 netwatch
|
||||
```
|
||||
|
||||
## Entrypoints
|
||||
|
||||
This repository adheres to the
|
||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
||||
standard: normalized scripts in `script/` are the entrypoints for the
|
||||
development workflow, and the Makefile targets are thin shims that call them. We
|
||||
provide:
|
||||
|
||||
- `script/bootstrap` — install all dependencies (pinned node via nvm if needed,
|
||||
yarn via corepack, `yarn install --frozen-lockfile`)
|
||||
- `script/setup` — make a fresh clone ready for development: bootstrap plus the
|
||||
git pre-commit hook
|
||||
- `script/projectname` — print the project name (used for the Docker image tag)
|
||||
- `script/test` — run the production build as the test (no unit tests yet)
|
||||
- `script/lint` — run prettier in check mode
|
||||
- `script/fmt` — format all files (writes)
|
||||
- `script/fmt-check` — check formatting (read-only)
|
||||
- `script/check` — run test, lint, and fmt-check
|
||||
- `script/frontend-viewport-test` — responsive-layout verification of the built
|
||||
frontend in a containerised headless Chrome (see
|
||||
[test/viewport/README.md](test/viewport/README.md)). Not part of
|
||||
`script/check`: it needs Docker and takes minutes.
|
||||
- `script/docker` — build the Docker image tagged via `script/projectname`
|
||||
- `script/cibuild` — CI entrypoint: plain `docker build .`
|
||||
- `script/precommit` — run by the git pre-commit hook; runs `script/check`
|
||||
- `script/install-precommit` — install the git pre-commit hook
|
||||
|
||||
## Responsive layout
|
||||
|
||||
The narrow-viewport layout lives in the `max-width: 768px` media block in
|
||||
`src/styles.css`. It is verified automatically by `make frontend-viewport-test`,
|
||||
which drives a digest-pinned headless Chrome against the built `dist/` and
|
||||
asserts on computed layout at widths derived from that CSS — one pixel either
|
||||
side of every breakpoint it declares, plus a 320px floor, a desktop baseline and
|
||||
two landscape sizes. See [test/viewport/README.md](test/viewport/README.md) for
|
||||
what it covers and what it genuinely cannot.
|
||||
|
||||
## Rationale
|
||||
|
||||
When debugging network issues, it's useful to have a persistent at-a-glance view
|
||||
|
||||
468
REPO_POLICIES.md
468
REPO_POLICIES.md
@@ -1,408 +1,108 @@
|
||||
---
|
||||
title: Repository Policies
|
||||
last_modified: 2026-07-06
|
||||
---
|
||||
# Development Policies
|
||||
|
||||
This document covers repository structure, tooling, and workflow standards. Code
|
||||
style conventions are in separate documents:
|
||||
- Docker image references by tag are server-mutable, therefore using them is an
|
||||
RCE vulnerability. All docker image references must use cryptographic hashes
|
||||
to securely specify the exact image that is expected.
|
||||
|
||||
- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
|
||||
(general, bash, Docker)
|
||||
- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
|
||||
- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
|
||||
- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
|
||||
- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
|
||||
- Correspondingly, `go install` commands using things like '@latest' are also
|
||||
dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go install
|
||||
targets using commit hashes which are cryptographically secure.
|
||||
|
||||
---
|
||||
- Every repo with software in it must have a Makefile in the root. Each such
|
||||
Makefile should support `make test` (runs the project-specific tests),
|
||||
`make lint`, `make fmt` (writes), `make fmt-check` (readonly), and
|
||||
`make check` (has `test`, `lint`, and `fmt-check` as prereqs), `make docker`
|
||||
(builds docker image).
|
||||
|
||||
- Cross-project documentation (such as this file) must include
|
||||
`last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
|
||||
with the authoritative source as policies evolve.
|
||||
- Every repo should have a Dockerfile. If the repo contains non-server software,
|
||||
the Dockerfile should bring up a development environment and `make check`
|
||||
(i.e. the docker build should fail if the branch is not green).
|
||||
|
||||
- **ALL external references must be pinned by cryptographic hash.** This
|
||||
includes Docker base images, Go modules, npm packages, GitHub Actions, and
|
||||
anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
|
||||
`:3.21`, etc.) are server-mutable and therefore remote code execution
|
||||
vulnerabilities. The ONLY acceptable way to reference an external dependency
|
||||
is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
|
||||
integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
|
||||
This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
|
||||
etc. Instead, download a specific release archive from GitHub, verify its hash
|
||||
(hardcoded in the Dockerfile or script), and only then install. Unverified
|
||||
install scripts are arbitrary remote code execution. This is the single most
|
||||
important rule in this document. Double-check every external reference in
|
||||
every file before committing. There are zero exceptions to this rule.
|
||||
- Platform-specific standard formatting should be used. `black` for python,
|
||||
`prettier` for js/css/etc, `go fmt` for go. The only changes to default
|
||||
settings should be to specify four-space indents where applicable (i.e.
|
||||
everything except `go fmt`).
|
||||
|
||||
- Every repo with software must have a root `Makefile` with these targets:
|
||||
`make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
|
||||
`make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
|
||||
`make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
|
||||
is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
|
||||
- If local testing is possible (it is not always), `make check` should be a
|
||||
pre-commit hook. If it is not possible, `make lint && make fmt-check` should
|
||||
be a pre-commit hook.
|
||||
|
||||
- Repos follow the
|
||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
||||
pattern: the implementation of each Makefile target lives in an executable
|
||||
script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
|
||||
`script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
|
||||
`script/docker`), and the Makefile targets are thin shims that call them. The
|
||||
scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
|
||||
minimal containers (e.g. alpine images have no bash); locate the repo root
|
||||
with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
|
||||
the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
|
||||
for development after a fresh clone: runs `bootstrap`, then
|
||||
`install-precommit`, plus any repo-specific initialization), `test`, and
|
||||
`cibuild`. `script/bootstrap` installs all dependencies idempotently and
|
||||
assumes nothing is present: base tools come from nix, apt, brew, or apk
|
||||
(detected in that order; apt runs noninteractive). For node it uses the
|
||||
installed node if present; otherwise it installs a PINNED node version via
|
||||
nvm, first installing nvm itself if missing — from a hash-verified GitHub
|
||||
release archive (never `curl | sh`), with bash installed as an explicit
|
||||
prerequisite since nvm requires bash. yarn is then pinned via
|
||||
`corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
|
||||
always exact versions. `script/cibuild` runs the CI build: it changes to the
|
||||
repo root and runs `docker build .`; the Gitea workflow calls it. Four further
|
||||
scripts are our own extensions to the standard: `script/check` runs
|
||||
`script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
|
||||
what the git pre-commit hook runs, and it calls `script/check`;
|
||||
`script/install-precommit` installs the git pre-commit hook (the `make hooks`
|
||||
target shims to it); and `script/projectname` (literally that filename) simply
|
||||
outputs the project's name. Scripts that need the name call
|
||||
`script/projectname` — e.g. `script/docker` assembles its image tag from it —
|
||||
so those scripts stay byte-identical across all repos. Repo-type-specific
|
||||
pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
|
||||
`script/precommit`, not in the hook itself. Model scripts are at
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
|
||||
must document the provided scripts in an **Entrypoints** section (see the
|
||||
README requirements below).
|
||||
- If a working `make test` takes more than 20 seconds, that's a bug that needs
|
||||
fixing. In fact, there should be a timeout specified in the `Makefile` that
|
||||
fails it automatically if it takes >30s.
|
||||
|
||||
- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
|
||||
instead of invoking the underlying tools directly. The Makefile is the single
|
||||
source of truth for how these operations are run.
|
||||
|
||||
- The Makefile is authoritative documentation for how the repo is used. Beyond
|
||||
the required targets above, it should have targets for every common operation:
|
||||
running a local development server (`make run`, `make dev`), re-initializing
|
||||
or migrating the database (`make db-reset`, `make migrate`), building
|
||||
artifacts (`make build`), generating code, seeding data, or anything else a
|
||||
developer would do regularly. If someone checks out the repo and types
|
||||
`make<tab>`, they should see every meaningful operation available. A new
|
||||
contributor should be able to understand the entire development workflow by
|
||||
reading the Makefile.
|
||||
|
||||
- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
|
||||
as a build step so the build fails if the branch is not green. For non-server
|
||||
repos, the Dockerfile should bring up a development environment and run
|
||||
`make check`. For server repos, `make check` should run as an early build
|
||||
stage before the final image is assembled. Dockerfiles install development
|
||||
prerequisites by running `script/bootstrap` rather than duplicating installs
|
||||
inline; COPY `script/` and the dependency manifests (`package.json` +
|
||||
`yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
|
||||
layer stays cached until dependencies change.
|
||||
|
||||
- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
|
||||
repos use a multistage build where linting runs in an independent stage based
|
||||
on the `golangci/golangci-lint` image (pinned by hash). This stage runs
|
||||
`make fmt-check` and `make lint` before the full build begins. The build stage
|
||||
then declares an explicit dependency on the lint stage via
|
||||
`COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
|
||||
linting before proceeding to compilation and tests. This ensures lint failures
|
||||
surface in seconds rather than minutes, without blocking on dependency
|
||||
download or compilation in the build stage.
|
||||
|
||||
The standard pattern for a Go repo Dockerfile is:
|
||||
|
||||
```dockerfile
|
||||
# Lint stage — fast feedback on formatting and lint issues
|
||||
# golangci/golangci-lint:v2.x.x, YYYY-MM-DD
|
||||
FROM golangci/golangci-lint@sha256:... AS lint
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN make fmt-check
|
||||
RUN make lint
|
||||
|
||||
# Build stage
|
||||
# golang:1.x-alpine, YYYY-MM-DD
|
||||
FROM golang@sha256:... AS builder
|
||||
WORKDIR /src
|
||||
|
||||
# Force BuildKit to run the lint stage before proceeding
|
||||
COPY --from=lint /src/go.sum /dev/null
|
||||
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN make test
|
||||
|
||||
ARG VERSION=dev
|
||||
RUN CGO_ENABLED=0 go build -trimpath \
|
||||
-ldflags="-s -w -X main.Version=${VERSION}" \
|
||||
-o /app ./cmd/app/
|
||||
|
||||
# Runtime stage
|
||||
FROM alpine@sha256:...
|
||||
COPY --from=builder /app /usr/local/bin/app
|
||||
ENTRYPOINT ["app"]
|
||||
```
|
||||
|
||||
Key points:
|
||||
- The lint stage uses the `golangci/golangci-lint` image directly (it
|
||||
includes both Go and the linter), so there is no need to install the
|
||||
linter separately.
|
||||
- `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
|
||||
a stage dependency. BuildKit runs stages in parallel by default; without
|
||||
this line, the build stage would not wait for lint to finish and a lint
|
||||
failure might not fail the overall build.
|
||||
- If the project uses `//go:embed` directives that reference build artifacts
|
||||
(e.g. a web frontend compiled in a separate stage), the lint stage must
|
||||
create placeholder files so the embed directives resolve. Example:
|
||||
`RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
|
||||
The lint stage should not depend on the actual build output — it exists to
|
||||
fail fast.
|
||||
- If the project requires CGO or system libraries for linting (e.g.
|
||||
`vips-dev`), install them in the lint stage with `apk add`.
|
||||
- The build stage runs `make test` after compilation setup. Tests run in the
|
||||
build stage, not the lint stage, because they may require compiled
|
||||
artifacts or heavier dependencies.
|
||||
|
||||
- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
|
||||
runs `script/cibuild` (which runs `docker build .`) on push. Since the
|
||||
Dockerfile already runs `make check`, a successful build implies all checks
|
||||
pass.
|
||||
|
||||
- Use platform-standard formatters: `black` for Python, `prettier` for
|
||||
JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
|
||||
two exceptions: four-space indents (except Go), and `proseWrap: always` for
|
||||
Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
|
||||
HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
|
||||
|
||||
- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
|
||||
testing is not possible in the repo, `script/precommit` may skip `script/test`
|
||||
and run only `script/lint` and `script/fmt-check`. The hook is installed by
|
||||
`script/install-precommit`; the Makefile must provide a `make hooks` target
|
||||
that shims to it.
|
||||
|
||||
- All repos with software must have tests that run via the platform-standard
|
||||
test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
|
||||
tests exist yet, add the most minimal test possible — e.g. importing the
|
||||
module under test to verify it compiles/parses. There is no excuse for
|
||||
`make test` to be a no-op.
|
||||
|
||||
- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
|
||||
Makefile.
|
||||
|
||||
- **`make test` should use the conditional verbose rerun pattern.** Run tests
|
||||
without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
|
||||
show full output. This keeps CI logs and `docker build` output clean on
|
||||
success (just package/suite summaries) while providing full diagnostic detail
|
||||
on failure (every test case, every assertion). The general shell pattern:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@<test-command> || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
<test-command-with-v>; exit 1; }
|
||||
```
|
||||
|
||||
Go example:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@go test -timeout 30s -race -cover ./... || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
go test -timeout 30s -race -v ./...; exit 1; }
|
||||
```
|
||||
|
||||
Python example:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@python -m pytest || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
python -m pytest -v; exit 1; }
|
||||
```
|
||||
|
||||
The `exit 1` ensures the target always fails after a rerun — the first run
|
||||
already proved the tests are broken, so the build must not pass even if a
|
||||
flaky test happens to succeed on the second attempt. The rerun exists solely
|
||||
for diagnostic output.
|
||||
|
||||
- Docker builds must complete in under 5 minutes.
|
||||
|
||||
- `make check` must not modify any files in the repo. Tests may use temporary
|
||||
directories.
|
||||
- Docker builds should time out in 5 minutes or less.
|
||||
|
||||
- `main` must always pass `make check`, no exceptions.
|
||||
|
||||
- Never commit secrets. `.env` files, credentials, API keys, and private keys
|
||||
must be in `.gitignore`. No exceptions.
|
||||
- Do all changes on a feature branch. You can do whatever you want on a feature
|
||||
branch.
|
||||
|
||||
- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
|
||||
editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
|
||||
Fetch the standard `.gitignore` from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
|
||||
a new repo.
|
||||
- We have a standardized `.golangci.yml` which we reuse and is _NEVER_ to be
|
||||
modified by an agent, only manually by the user. It can be copied from
|
||||
`~/dev/upaas/.golangci.yml` if it exists at that location.
|
||||
|
||||
- **No build artifacts in version control.** Code-derived data (compiled
|
||||
bundles, minified output, generated assets) must never be committed to the
|
||||
repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
|
||||
should generate these at build time. Notable exception: Go protobuf generated
|
||||
files (`.pb.go`) ARE committed because repos need to work with `go get`, which
|
||||
downloads code but does not execute code generation.
|
||||
- When specifying images or packages by hash in Dockerfiles or
|
||||
`docker-compose.yml`, put a comment above the line and show the version and
|
||||
date at which it was current.
|
||||
|
||||
- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
|
||||
- For javascript, always use `yarn` over `npm`.
|
||||
|
||||
- Never force-push to `main`.
|
||||
- Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601).
|
||||
|
||||
- Make all changes on a feature branch. You can do whatever you want on a
|
||||
feature branch.
|
||||
- Simple projects should be configured with environment variables, as is
|
||||
standard for Dockerized applications.
|
||||
|
||||
- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
|
||||
manually by the user. Fetch from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
|
||||
- Dockerized web services should listen on the default HTTP port of 8080 unless
|
||||
overridden with the `PORT` environment variable.
|
||||
|
||||
- When pinning images or packages by hash, add a comment above the reference
|
||||
with the version and date (YYYY-MM-DD).
|
||||
- The `README.md` is a project's primary documentation. It should contain at a
|
||||
minimum the following sections:
|
||||
- Description
|
||||
- Include a short and complete description of the functionality and
|
||||
purpose of the software as the first line in the readme. It must
|
||||
include:
|
||||
- the name
|
||||
- the purpose
|
||||
- the category (web server, SPA, command line tool, etc)
|
||||
- the license
|
||||
- the author
|
||||
- eg: "µPaaS is an MIT-licensed Go web application by @sneak that
|
||||
receives git-frontend webhooks and interacts with a Docker server
|
||||
to build and deploy applications in realtime as certain branches
|
||||
are updated."
|
||||
- Getting Started
|
||||
- a code block with copy-pasteable installation/use sections
|
||||
- Rationale
|
||||
- why does this exist?
|
||||
- Design
|
||||
- how is the program structured?
|
||||
- TODO
|
||||
- This is your TODO list for the project - update it meticulously, even
|
||||
in between commits. Whenever planning, put your todo list in the
|
||||
README so that a separate agent with new context can pick up where you
|
||||
left off.
|
||||
- License
|
||||
- GPL or MIT or WTFPL - ask the user when beginning a new project and
|
||||
include a LICENSE file in the root and in a section in the README.
|
||||
- Author
|
||||
- @sneak (link `@sneak` to `https://sneak.berlin`).
|
||||
|
||||
- Use `yarn`, not `npm`.
|
||||
- When beginning a new project, initialize a git repo and make the first commit
|
||||
simply the first version of the README.md in the root of the repo.
|
||||
|
||||
- Write all dates as YYYY-MM-DD (ISO 8601).
|
||||
- For Go packages, the module root is `sneak.berlin/go/...`, such as
|
||||
`sneak.berlin/go/dnswatcher`.
|
||||
|
||||
- Simple projects should be configured with environment variables.
|
||||
- We use SemVer always.
|
||||
|
||||
- Dockerized web services listen on port 8080 by default, overridable with
|
||||
`PORT`.
|
||||
- If no tag `1.0.0` or greater exists in the repository, modify the existing
|
||||
migrations and assume no installed base or existing databases. If `>=1.0.0`,
|
||||
database changes add new migration files.
|
||||
|
||||
- **HTTP/web services must be hardened for production internet exposure before
|
||||
tagging 1.0.** This means full compliance with security best practices
|
||||
including, without limitation, all of the following:
|
||||
- **Security headers** on every response:
|
||||
- `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
|
||||
and `includeSubDomains`.
|
||||
- `Content-Security-Policy` (CSP) with a restrictive default policy
|
||||
(`default-src 'self'` as a baseline, tightened per-resource as
|
||||
needed). Never use `unsafe-inline` or `unsafe-eval` unless
|
||||
unavoidable, and document the reason.
|
||||
- `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
|
||||
Prefer the `frame-ancestors` CSP directive as the primary control.
|
||||
- `X-Content-Type-Options: nosniff`.
|
||||
- `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
|
||||
- `Permissions-Policy` restricting access to browser features the
|
||||
application does not use (camera, microphone, geolocation, etc.).
|
||||
- **Request and response limits:**
|
||||
- Maximum request body size enforced on all endpoints (e.g. Go
|
||||
`http.MaxBytesReader`). Choose a sane default per-route; never accept
|
||||
unbounded input.
|
||||
- Maximum response body size where applicable (e.g. paginated APIs).
|
||||
- `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
|
||||
against slowloris attacks.
|
||||
- `WriteTimeout` on the `http.Server`.
|
||||
- `IdleTimeout` on the `http.Server`.
|
||||
- Per-handler execution time limits via `context.WithTimeout` or
|
||||
chi/stdlib `middleware.Timeout`.
|
||||
- **Authentication and session security:**
|
||||
- Rate limiting on password-based authentication endpoints. API keys are
|
||||
high-entropy and not susceptible to brute force, so they are exempt.
|
||||
- CSRF tokens on all state-mutating HTML forms. API endpoints
|
||||
authenticated via `Authorization` header (Bearer token, API key) are
|
||||
exempt because the browser does not attach these automatically.
|
||||
- Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
|
||||
MD5, or SHA.
|
||||
- Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
|
||||
`Strict`) attributes.
|
||||
- **Reverse proxy awareness:**
|
||||
- True client IP detection when behind a reverse proxy
|
||||
(`X-Forwarded-For`, `X-Real-IP`). The application must accept
|
||||
forwarded headers only from a configured set of trusted proxy
|
||||
addresses — never trust `X-Forwarded-For` unconditionally.
|
||||
- **CORS:**
|
||||
- Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
|
||||
an explicit allowlist of known origins. Wildcard (`*`) is acceptable
|
||||
only for public, unauthenticated read-only APIs.
|
||||
- **Error handling:**
|
||||
- Internal errors must never leak stack traces, SQL queries, file paths,
|
||||
or other implementation details to the client. Return generic error
|
||||
messages in production; detailed errors only when `DEBUG` is enabled.
|
||||
- **TLS:**
|
||||
- Services never terminate TLS directly. They are always deployed behind
|
||||
a TLS-terminating reverse proxy. The service itself listens on plain
|
||||
HTTP. However, HSTS headers and `Secure` cookie flags must still be
|
||||
set by the application so that the browser enforces HTTPS end-to-end.
|
||||
|
||||
This list is non-exhaustive. Apply defense-in-depth: if a standard security
|
||||
hardening measure exists for HTTP services and is not listed here, it is
|
||||
still expected. When in doubt, harden.
|
||||
|
||||
- `README.md` is the primary documentation. Required sections:
|
||||
- **Description**: First line must include the project name, purpose,
|
||||
category (web server, SPA, CLI tool, etc.), license, and author. Example:
|
||||
"µPaaS is an MIT-licensed Go web application by @sneak that receives
|
||||
git-frontend webhooks and deploys applications via Docker in realtime."
|
||||
- **Getting Started**: Copy-pasteable install/usage code block.
|
||||
- **Entrypoints**: Opens by stating that the repo adheres to the
|
||||
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
|
||||
standard (with that link), then documents each provided `script/`
|
||||
entrypoint and its purpose.
|
||||
- **Rationale**: Why does this exist?
|
||||
- **Design**: How is the program structured?
|
||||
- **TODO**: Update meticulously, even between commits. When planning, put
|
||||
the todo list in the README so a new agent can pick up where the last one
|
||||
left off.
|
||||
- **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
|
||||
`LICENSE` file in the repo root and a License section in the README.
|
||||
- **Author**: [@sneak](https://sneak.berlin).
|
||||
|
||||
- First commit of a new repo should contain only `README.md`.
|
||||
|
||||
- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
|
||||
committing.
|
||||
|
||||
- Use SemVer.
|
||||
|
||||
- Database migrations live in `internal/db/migrations/` and must be embedded in
|
||||
the binary.
|
||||
- `000_migration.sql` — contains ONLY the creation of the migrations
|
||||
tracking table itself. Nothing else.
|
||||
- `001_schema.sql` — the full application schema.
|
||||
- **Pre-1.0.0:** never add additional migration files (002, 003, etc.).
|
||||
There is no installed base to migrate. Edit `001_schema.sql` directly.
|
||||
- **Post-1.0.0:** add new numbered migration files for each schema change.
|
||||
Never edit existing migrations after release.
|
||||
|
||||
- All repos should have an `.editorconfig` enforcing the project's indentation
|
||||
settings.
|
||||
|
||||
- Avoid putting files in the repo root unless necessary. Root should contain
|
||||
only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
|
||||
`LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
|
||||
language-specific config). Everything else goes in a subdirectory. Canonical
|
||||
subdirectory names:
|
||||
- `bin/` — executable scripts and tools
|
||||
- `cmd/` — Go command entrypoints
|
||||
- `configs/` — configuration templates and examples
|
||||
- `deploy/` — deployment manifests (k8s, compose, terraform)
|
||||
- `docs/` — documentation and markdown (README.md stays in root)
|
||||
- `internal/` — Go internal packages
|
||||
- `internal/db/migrations/` — database migrations
|
||||
- `pkg/` — Go library packages
|
||||
- `share/` — systemd units, data files
|
||||
- `static/` — static assets (images, fonts, etc.)
|
||||
- `web/` — web frontend source
|
||||
|
||||
- When setting up a new repo, files from the `prompts` repo may be used as
|
||||
templates. Fetch them from
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
|
||||
|
||||
- New repos must contain at minimum:
|
||||
- `README.md`, `.git`, `.gitignore`, `.editorconfig`
|
||||
- `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
|
||||
- `Makefile`
|
||||
- `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
|
||||
`lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
|
||||
`install-precommit`)
|
||||
- New repos must have at a minimum the following files:
|
||||
- `README.md`, `.git`, `.gitignore`
|
||||
- `POLICIES.md` (copy from `~/Documents/_PROMPTS/POLICIES.md`)
|
||||
- `Dockerfile`, `.dockerignore`
|
||||
- `.gitea/workflows/check.yml`
|
||||
- Go: `go.mod`, `go.sum`, `.golangci.yml`
|
||||
- JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
|
||||
- Python: `pyproject.toml`
|
||||
- for go: `go.mod`, `go.sum`, `.golangci.yml`
|
||||
- for js: `package.json`
|
||||
|
||||
54
TODO.md
54
TODO.md
@@ -1,54 +0,0 @@
|
||||
# Workflow
|
||||
|
||||
- branch (from `main`)
|
||||
- do the work in Next Step
|
||||
- move Next Step to the top of Completed Steps
|
||||
- move the top item of Future Steps into Next Step
|
||||
- commit (`TODO.md` changes in the same commit as the work)
|
||||
- merge to `main` if the branch is not protected, otherwise open a PR
|
||||
- push
|
||||
|
||||
# Status
|
||||
|
||||
pre-1.0. No git tags. Backend work in flight on feat/reportbuf-storage (dirty:
|
||||
src/main.js). Frontend is functional; backend is new and unmerged.
|
||||
|
||||
# Next Step
|
||||
|
||||
Land feat/reportbuf-storage: finish the in-progress src/main.js change, get make
|
||||
check green, and merge the branch to main. The branch adds the backend (buffered
|
||||
zstd-compressed report storage), the CI workflow, and backend repo standard
|
||||
files, so merging it also closes most compliance gaps.
|
||||
|
||||
# Completed Steps
|
||||
|
||||
- 2026-08-09: automated responsive-layout harness
|
||||
(`make frontend-viewport-test`): digest-pinned headless Chrome driven over CDP
|
||||
against the built `dist/`, viewport widths derived from the breakpoints in
|
||||
`src/styles.css` (#13). Found two real layout defects, filed as #42 and #43
|
||||
- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
|
||||
shims, README Entrypoints section
|
||||
- 2026-02-27: backend with buffered zstd-compressed report storage; CI workflow
|
||||
and backend repo standard files; backend Dockerfile fixed (Go 1.25,
|
||||
golangci-lint) and moved to repo root (feat/reportbuf-storage, unmerged)
|
||||
- 2026-02-26: host row layout redesigned with CSS grid; overflow and spacing
|
||||
fixes; nginx config extracted; port hardcoded to 8080
|
||||
- 2026-02-26: debug log panel, median stats, recovery probe, Docker build fix,
|
||||
S3 Singapore endpoint added
|
||||
- 2026-02-23: summary box redesign, host pinning, local and UTC clocks, checks
|
||||
counter
|
||||
- 2026-02-23: hosts sorted by latency; GET instead of HEAD for latency; timeout
|
||||
derived from interval; Hetzner regional endpoints; 3s interval
|
||||
- 2026-01-29: initial NetWatch network latency monitor
|
||||
|
||||
# Future Steps
|
||||
|
||||
- Fix the two layout defects the viewport harness found (#42 horizontal overflow
|
||||
at 320px, #43 tap targets below 44x44), then wire
|
||||
`script/frontend-viewport-test` into CI as its own step
|
||||
- Compliance top-up as one small commit: add .editorconfig and add the hooks
|
||||
target to the Makefile
|
||||
- After merge, confirm .gitea/workflows/check.yml is on main and CI is green
|
||||
(main always green policy)
|
||||
- Decide what to do with untracked resume.sh: commit it, gitignore it, or delete
|
||||
it
|
||||
@@ -14,7 +14,6 @@
|
||||
"autoprefixer": "^10.4.23",
|
||||
"postcss": "^8.5.6",
|
||||
"prettier": "^3.8.1",
|
||||
"puppeteer-core": "25.5.0",
|
||||
"tailwindcss": "^4.1.18",
|
||||
"vite": "^7.3.1"
|
||||
}
|
||||
|
||||
143
script/bootstrap
143
script/bootstrap
@@ -1,143 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/bootstrap: install all dependencies needed to build and develop
|
||||
# this repo. Idempotent: every install is guarded by a check so already
|
||||
# installed tools are skipped. Base tooling comes from nix, apt, brew,
|
||||
# or apk (detected in that order); assumes nothing is present. Node is
|
||||
# used directly if installed; otherwise it is installed at a pinned
|
||||
# version via nvm (installing nvm itself first, from a hash-verified
|
||||
# release archive, never curl | sh).
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
# Pinned versions, 2026-07-07
|
||||
NODE_VERSION="22.17.0"
|
||||
NVM_VERSION="0.40.3"
|
||||
# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
|
||||
NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
|
||||
YARN_VERSION="1.22.22"
|
||||
|
||||
PKGMGR=""
|
||||
SUDO=""
|
||||
APT_UPDATED=""
|
||||
|
||||
detect_pkgmgr() {
|
||||
[ -n "$PKGMGR" ] && return 0
|
||||
if command -v nix-env >/dev/null 2>&1; then
|
||||
PKGMGR="nix"
|
||||
elif command -v apt-get >/dev/null 2>&1; then
|
||||
PKGMGR="apt"
|
||||
elif command -v brew >/dev/null 2>&1; then
|
||||
PKGMGR="brew"
|
||||
elif command -v apk >/dev/null 2>&1; then
|
||||
PKGMGR="apk"
|
||||
else
|
||||
echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [ "$PKGMGR" = "apt" ]; then
|
||||
export DEBIAN_FRONTEND=noninteractive
|
||||
if [ "$(id -u)" != "0" ]; then
|
||||
SUDO="sudo"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
|
||||
pkg_install() {
|
||||
detect_pkgmgr
|
||||
case "$PKGMGR" in
|
||||
nix) nix-env -iA "nixpkgs.$1" ;;
|
||||
apt)
|
||||
if [ -z "$APT_UPDATED" ]; then
|
||||
$SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
|
||||
APT_UPDATED=1
|
||||
fi
|
||||
$SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
|
||||
;;
|
||||
brew) brew install "$3" ;;
|
||||
apk) apk add --no-cache "$4" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
missing() {
|
||||
! command -v "$1" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
# verify_sha256 <file> <expected-hash>
|
||||
verify_sha256() {
|
||||
if command -v sha256sum >/dev/null 2>&1; then
|
||||
actual="$(sha256sum "$1" | cut -d' ' -f1)"
|
||||
else
|
||||
actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
|
||||
fi
|
||||
if [ "$actual" != "$2" ]; then
|
||||
echo "bootstrap: sha256 mismatch for $1" >&2
|
||||
echo " expected: $2" >&2
|
||||
echo " actual: $actual" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# nvm is a bash script; run a command in a bash with nvm loaded
|
||||
nvm_sh() {
|
||||
bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
|
||||
}
|
||||
|
||||
ensure_nvm() {
|
||||
[ -s "$HOME/.nvm/nvm.sh" ] && return 0
|
||||
# nvm prerequisites; nvm itself requires bash
|
||||
if missing bash; then pkg_install bash bash bash bash; fi
|
||||
if missing curl; then pkg_install curl curl curl curl; fi
|
||||
if missing git; then pkg_install git git git git; fi
|
||||
tmp="$(mktemp -d)"
|
||||
curl -fsSL -o "$tmp/nvm.tar.gz" \
|
||||
"https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
|
||||
verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
|
||||
mkdir -p "$HOME/.nvm"
|
||||
tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
|
||||
rm -rf "$tmp"
|
||||
}
|
||||
|
||||
ensure_node() {
|
||||
if ! missing node; then return 0; fi
|
||||
ensure_nvm
|
||||
nvm_sh "nvm install $NODE_VERSION"
|
||||
}
|
||||
|
||||
ensure_yarn() {
|
||||
if ! missing yarn; then return 0; fi
|
||||
if ! missing corepack; then
|
||||
corepack enable
|
||||
corepack prepare "yarn@$YARN_VERSION" --activate
|
||||
elif [ -s "$HOME/.nvm/nvm.sh" ]; then
|
||||
nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
|
||||
corepack prepare yarn@$YARN_VERSION --activate"
|
||||
else
|
||||
npm install -g "yarn@$YARN_VERSION"
|
||||
fi
|
||||
}
|
||||
|
||||
install_js_deps() {
|
||||
if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
|
||||
nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
|
||||
yarn install --frozen-lockfile"
|
||||
else
|
||||
yarn install --frozen-lockfile
|
||||
fi
|
||||
}
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
|
||||
if missing make; then pkg_install gnumake make make make; fi
|
||||
if missing git; then pkg_install git git git git; fi
|
||||
|
||||
ensure_node
|
||||
ensure_yarn
|
||||
install_js_deps
|
||||
|
||||
echo "bootstrap complete"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
14
script/check
14
script/check
@@ -1,14 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/check: run all checks (test, lint, fmt-check). Our own
|
||||
# extension to scripts-to-rule-them-all. Must not modify any files.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
|
||||
main() {
|
||||
"$SCRIPT_DIR/test"
|
||||
"$SCRIPT_DIR/lint"
|
||||
"$SCRIPT_DIR/fmt-check"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/cibuild: run the CI build. The Dockerfile runs make check, so
|
||||
# a successful build implies all checks pass.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
docker build .
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,14 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/docker: build the Docker image tagged with the project name.
|
||||
# The tag comes from script/projectname.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
timeout 300 docker build -t "$("$SCRIPT_DIR/projectname")" .
|
||||
}
|
||||
|
||||
main "$@"
|
||||
12
script/fmt
12
script/fmt
@@ -1,12 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/fmt: format all files (writes).
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
yarn prettier --write .
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/fmt-check: check formatting (read-only). Same scope as
|
||||
# script/fmt, but fails instead of writing.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
yarn prettier --check .
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,95 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/frontend-viewport-test: verify the responsive layout of the built
|
||||
# frontend in a real browser engine.
|
||||
#
|
||||
# Builds dist/, serves it with the same nginx image and the same nginx.conf
|
||||
# the shipping container uses, points a containerised headless Chrome at it
|
||||
# over CDP, and asserts on computed layout at every viewport width derived
|
||||
# from the app's own CSS. See test/viewport/README.md for what this covers
|
||||
# and what it cannot.
|
||||
#
|
||||
# Deliberately not part of script/check: it needs Docker and takes far
|
||||
# longer than the 20s budget make test has to stay inside.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
# chromedp/headless-shell 151.0.7922.109, 2026-08-09
|
||||
BROWSER_IMAGE="chromedp/headless-shell@sha256:2d349b544a1ea6b5b5fd7c0fe99215ff662339c57407ee2e8c0a11af93516b04"
|
||||
# nginx:stable-alpine, 2026-02-22 (the digest Dockerfile ships)
|
||||
SERVER_IMAGE="nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab"
|
||||
# node:22-alpine, 2026-02-22 (the digest Dockerfile builds with)
|
||||
NODE_IMAGE="node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34"
|
||||
|
||||
RUN_ID="$$-$(date +%s)"
|
||||
NETWORK="netwatch-viewport-$RUN_ID"
|
||||
SERVER="netwatch-viewport-server-$RUN_ID"
|
||||
BROWSER="netwatch-viewport-browser-$RUN_ID"
|
||||
ARTIFACT_DIR="$ROOT/tmp/viewport"
|
||||
|
||||
cleanup() {
|
||||
docker rm -f "$BROWSER" > /dev/null 2>&1 || true
|
||||
docker rm -f "$SERVER" > /dev/null 2>&1 || true
|
||||
docker network rm "$NETWORK" > /dev/null 2>&1 || true
|
||||
}
|
||||
trap cleanup EXIT INT TERM
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
|
||||
# Test what ships: the production build, not a dev server.
|
||||
"$ROOT/script/test"
|
||||
if [ ! -f "$ROOT/dist/index.html" ]; then
|
||||
echo "frontend-viewport-test: dist/index.html missing after build" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p "$ARTIFACT_DIR"
|
||||
|
||||
# An --internal network has no route off the host, so the browser
|
||||
# cannot reach the real internet no matter what the page asks for.
|
||||
# Latency probes are answered by the harness instead. This also means
|
||||
# no port can be published from it, which is why the harness itself
|
||||
# runs as a third container on the same network rather than on the
|
||||
# host.
|
||||
docker network create --internal "$NETWORK" > /dev/null
|
||||
|
||||
docker run -d --rm --name "$SERVER" \
|
||||
--network "$NETWORK" --network-alias netwatch \
|
||||
-v "$ROOT/dist:/usr/share/nginx/html:ro" \
|
||||
-v "$ROOT/nginx.conf:/etc/nginx/conf.d/default.conf:ro" \
|
||||
"$SERVER_IMAGE" > /dev/null
|
||||
|
||||
# The image's own entrypoint already exposes CDP on 9222 and passes
|
||||
# --no-sandbox, so only extra flags belong here; re-specifying the
|
||||
# debugging port collides with it and leaves the endpoint bound to
|
||||
# loopback only. --hide-scrollbars keeps innerWidth equal to
|
||||
# clientWidth, so the overflow assertion has no scrollbar-sized slack
|
||||
# to hide behind, and matches the overlay scrollbars phones use.
|
||||
docker run -d --rm --name "$BROWSER" --init --shm-size=1g \
|
||||
--network "$NETWORK" \
|
||||
"$BROWSER_IMAGE" \
|
||||
--hide-scrollbars \
|
||||
> /dev/null
|
||||
|
||||
# Chrome refuses DevTools requests whose Host header is neither
|
||||
# localhost nor an IP address, so dial the container by address rather
|
||||
# than by its network alias.
|
||||
browser_ip="$(docker inspect \
|
||||
-f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \
|
||||
"$BROWSER")"
|
||||
|
||||
timeout 900 docker run --rm --init \
|
||||
--network "$NETWORK" \
|
||||
--user "$(id -u):$(id -g)" \
|
||||
-v "$ROOT:/app" \
|
||||
-w /app \
|
||||
-e NETWATCH_ROOT=/app \
|
||||
-e NETWATCH_BASE_URL=http://netwatch:8080 \
|
||||
-e "NETWATCH_CDP_URL=http://$browser_ip:9222" \
|
||||
-e NETWATCH_ARTIFACT_DIR=/app/tmp/viewport \
|
||||
"$NODE_IMAGE" \
|
||||
node test/viewport/harness.js
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,16 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/install-precommit: install the git pre-commit hook that runs
|
||||
# script/precommit. Our own extension to scripts-to-rule-them-all.
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
hook=".git/hooks/pre-commit"
|
||||
printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
|
||||
chmod +x "$hook"
|
||||
echo "pre-commit hook installed: runs script/precommit"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
12
script/lint
12
script/lint
@@ -1,12 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/lint: run the linter (prettier in check mode).
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
yarn prettier --check .
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,12 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/precommit: run by the git pre-commit hook; fails the commit if
|
||||
# checks fail. Our own extension to scripts-to-rule-them-all.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
|
||||
main() {
|
||||
"$SCRIPT_DIR/check"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,12 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/projectname: output the name of this project. Our own
|
||||
# extension to scripts-to-rule-them-all. Other scripts that need the
|
||||
# name (e.g. script/docker) call this, so they can stay identical
|
||||
# across all repos.
|
||||
set -eu
|
||||
|
||||
main() {
|
||||
echo "netwatch"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
13
script/setup
13
script/setup
@@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/setup: set up the repo for development after a fresh clone:
|
||||
# installs dependencies and the git pre-commit hook.
|
||||
set -eu
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||
|
||||
main() {
|
||||
"$SCRIPT_DIR/bootstrap"
|
||||
"$SCRIPT_DIR/install-precommit"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
13
script/test
13
script/test
@@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
# script/test: run the test suite. This repo has no unit tests; the
|
||||
# production build serves as the test (fails on broken code).
|
||||
set -eu
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
||||
|
||||
main() {
|
||||
cd "$ROOT"
|
||||
timeout 30 yarn build
|
||||
}
|
||||
|
||||
main "$@"
|
||||
19
src/main.js
19
src/main.js
@@ -1131,6 +1131,25 @@ function handleResize(state) {
|
||||
async function init() {
|
||||
log.info("NetWatch starting");
|
||||
|
||||
// Mobile detection — show a friendly message and bail out early
|
||||
if (window.innerWidth < 768) {
|
||||
const app = document.getElementById("app");
|
||||
app.innerHTML = `
|
||||
<div class="mx-auto px-[5%] py-8">
|
||||
<header class="mb-8">
|
||||
<h1 class="text-3xl font-bold text-white"><a href="https://git.eeqj.de/sneak/netwatch" target="_blank" rel="noopener" class="underline decoration-dashed decoration-gray-500 underline-offset-4">NetWatch</a> by <a href="https://sneak.berlin" target="_blank" rel="noopener" class="text-blue-400 underline hover:text-blue-300">@sneak</a></h1>
|
||||
<p class="text-gray-400 mt-2">Real-time network connectivity monitor</p>
|
||||
</header>
|
||||
<div style="display:flex;align-items:center;justify-content:center;min-height:50vh;">
|
||||
<div style="background:#1f2937;border:1px solid #374151;border-radius:12px;padding:2rem 1.5rem;text-align:center;max-width:90vw;">
|
||||
<p style="font-size:1.25rem;color:#e5e7eb;margin:0;">Not yet available on mobile.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>`;
|
||||
log.info("Mobile viewport detected — skipping monitor startup");
|
||||
return;
|
||||
}
|
||||
|
||||
// Probe common gateway IPs to find the local router
|
||||
const gateway = await detectGateway();
|
||||
const localHosts = [LOCAL_CPE];
|
||||
|
||||
@@ -21,96 +21,3 @@ body {
|
||||
rgba(255, 255, 255, 0) 100%
|
||||
);
|
||||
}
|
||||
|
||||
/* ---- Mobile responsive layout (portrait / narrow viewports) ---- */
|
||||
@media (max-width: 768px) {
|
||||
/* Header: stack title and controls vertically */
|
||||
header .flex.items-center.justify-between {
|
||||
flex-direction: column;
|
||||
align-items: flex-start !important;
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
header .flex.flex-col.items-end {
|
||||
align-items: flex-start !important;
|
||||
flex-direction: row;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.75rem;
|
||||
}
|
||||
|
||||
/* Pause button: smaller on mobile */
|
||||
#pause-btn {
|
||||
padding: 0.5rem 1rem;
|
||||
}
|
||||
|
||||
#pause-btn svg {
|
||||
width: 1.25rem;
|
||||
height: 1.25rem;
|
||||
}
|
||||
|
||||
#pause-text {
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
|
||||
/* Summary box: wrap into a grid for readability */
|
||||
#summary {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.25rem 0.5rem;
|
||||
justify-content: center;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
/* Hide the pipe separators on mobile */
|
||||
#summary .text-gray-600.mx-3 {
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Host row: stack vertically */
|
||||
.host-row .flex.items-center.gap-4 {
|
||||
flex-direction: column;
|
||||
align-items: stretch !important;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
/* Info section: full width, remove fixed width */
|
||||
.host-row .w-\[420px\] {
|
||||
width: 100% !important;
|
||||
display: grid;
|
||||
grid-template-columns: 1fr auto;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
/* Host name row with dot */
|
||||
.host-row .flex.items-center.gap-2.min-w-\[200px\] {
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
/* Latency value: slightly smaller on mobile */
|
||||
.host-row .latency-value {
|
||||
font-size: 1.875rem;
|
||||
line-height: 2.25rem;
|
||||
}
|
||||
|
||||
/* Sparkline: full width below the info */
|
||||
.host-row .sparkline-container {
|
||||
width: 100%;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
/* Pin button: inline with the host info */
|
||||
.host-row .pin-btn {
|
||||
position: absolute;
|
||||
right: 0.5rem;
|
||||
top: 0.5rem;
|
||||
}
|
||||
|
||||
.host-row {
|
||||
position: relative;
|
||||
}
|
||||
|
||||
/* Footer legend: wrap nicely */
|
||||
footer p {
|
||||
line-height: 1.8;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,105 +0,0 @@
|
||||
# Responsive-layout harness
|
||||
|
||||
Automated verification of the responsive layout that landed in #5. Run it with:
|
||||
|
||||
```bash
|
||||
make frontend-viewport-test
|
||||
```
|
||||
|
||||
It builds `dist/`, serves it from the same digest-pinned `nginx` image and the
|
||||
same `nginx.conf` the shipping container uses, drives a digest-pinned headless
|
||||
Chrome against it over CDP, and asserts on computed layout at every viewport
|
||||
width derived from the app's own CSS. Screenshots land in `tmp/viewport/`
|
||||
alongside a `results.json`; they are artifacts for a human to look at when
|
||||
something fails, not the evidence. The assertions are the evidence.
|
||||
|
||||
The target is deliberately outside `make check`: it needs Docker and takes
|
||||
minutes, and `make test` has to stay under 20 seconds.
|
||||
|
||||
## How the widths are chosen
|
||||
|
||||
Not from a list of phone models. `viewports.js` parses the `@media` conditions
|
||||
out of `src/styles.css` and scans `src/main.js` and `index.html` for Tailwind
|
||||
responsive prefixes, then tests every breakpoint it finds at one pixel below it,
|
||||
exactly on it, and one pixel above it. A generic 375px "phone" test sails
|
||||
straight past an off-by-one at a media query boundary; `max-width: 768px`
|
||||
matches _at_ 768, and the sweep pins down which side of that line each layout is
|
||||
on.
|
||||
|
||||
Nothing hardcodes 768. Add a second media block or start using `md:` classes and
|
||||
the new breakpoint is covered without this directory being touched. Four further
|
||||
viewports are fixed anchors, each with a stated reason: a 320px floor, a 1280px
|
||||
desktop baseline, and two phone-landscape sizes straddling the breakpoint for
|
||||
the rotation case.
|
||||
|
||||
## What it asserts
|
||||
|
||||
- **app-rendered** — enough host rows exist and enough of them show a numeric
|
||||
latency. This one exists so the rest cannot pass vacuously against a blank
|
||||
page.
|
||||
- **no-horizontal-overflow** — `documentElement.scrollWidth` fits the layout
|
||||
viewport, with the widest offending element named.
|
||||
- **nothing-past-viewport-edge** — no visible element's box extends past the
|
||||
viewport edge.
|
||||
- **no-clipped-text** — nothing hides text behind `overflow: hidden`. Deliberate
|
||||
ellipsis truncation (Tailwind's `truncate`, used on host names and URLs) is
|
||||
excluded: it is a design choice, not breakage.
|
||||
- **tap-targets-44px** — every interactive control is at least 44x44 CSS px on
|
||||
touch viewports. See below.
|
||||
- **host-rows-stacked / host-rows-side-by-side** — the rows genuinely reflow.
|
||||
Computed `flex-direction` _and_ the actual geometry are checked, and in the
|
||||
narrow layout the info block and the sparkline must each occupy essentially
|
||||
the full row width. A row that merely shrank its 420px column would fail.
|
||||
- **probing-still-runs / gateway-detection-still-runs** — narrow viewports keep
|
||||
probing and keep detecting the gateway. The mobile early-return path proposed
|
||||
in #8 was rejected; this is what would catch it coming back.
|
||||
|
||||
### The tap-target threshold
|
||||
|
||||
44x44 CSS px. That is the figure in Apple's Human Interface Guidelines and in
|
||||
WCAG 2.2 SC 2.5.5 "Target Size (Enhanced)". WCAG 2.2 SC 2.5.8 (level AA) sets a
|
||||
lower 24x24 floor, but that floor comes with a spacing exception these controls
|
||||
do not qualify for — the pin buttons sit directly against the host name they
|
||||
belong to.
|
||||
|
||||
## Determinism
|
||||
|
||||
The browser container runs on an `--internal` docker network and has no route to
|
||||
the internet, so the app's latency probes cannot reach anything real. The
|
||||
harness answers them itself from a fixed delay table, with a deterministic
|
||||
fraction failed outright, so the rows render a realistic spread of one-, two-
|
||||
and three-digit latencies plus some unreachable rows. That spread is what the
|
||||
layout has to survive; 24 identical `---` placeholders would not exercise it.
|
||||
|
||||
## What this cannot verify
|
||||
|
||||
Real limits, so nobody re-parks this issue as needing hardware:
|
||||
|
||||
- **Non-Chromium engines.** This is Chrome. iOS Safari is WebKit and cannot be
|
||||
emulated by it; Safari-specific bugs (viewport units under a collapsing URL
|
||||
bar, `-webkit-fill-available`, form control metrics) will not show up here.
|
||||
- **Real touch input.** `hasTouch` emulation changes what the page is told, not
|
||||
how a finger behaves. Gesture handling, scroll momentum, double-tap zoom and
|
||||
hover-state fallbacks on touch are out of scope.
|
||||
- **Physical pixel density and rendering.** `deviceScaleFactor` is set, but
|
||||
subpixel antialiasing, OLED colour rendering and actual legibility at a given
|
||||
physical size are not measurable here.
|
||||
- **Fonts.** The container has DejaVu, not the platform's own UI monospace. Text
|
||||
metrics are therefore close to, but not identical to, a real device — a layout
|
||||
that fits here by a few pixels might not there.
|
||||
- **On-device performance.** Canvas sparkline redraw cost, battery, and
|
||||
behaviour on a slow radio are not measured.
|
||||
- **Browser chrome.** The address bar, safe-area insets and notch cutouts are
|
||||
not simulated.
|
||||
|
||||
Everything else this issue was actually about — does the layout reflow, does
|
||||
anything overflow, is content clipped, are the controls big enough — is a
|
||||
function of viewport width and CSS, and is covered above.
|
||||
|
||||
## Relation to the unit test framework (#21)
|
||||
|
||||
Complementary layers, not two stacks. `vitest` (#21) will exercise module-level
|
||||
logic in-process with no browser. This harness exercises rendered layout in a
|
||||
real engine and is the only thing here that can see a media query. Neither
|
||||
replaces the other; assertions about computed styles and element geometry belong
|
||||
here, assertions about functions belong in `vitest`.
|
||||
@@ -1,203 +0,0 @@
|
||||
// Pass/fail decisions for the responsive-layout harness.
|
||||
//
|
||||
// Kept in node rather than in the page so that a failure can be reported
|
||||
// with the measurements that produced it. Every check runs at every
|
||||
// viewport; none of them short-circuits, so one failure does not hide the
|
||||
// rest.
|
||||
|
||||
// Minimum tap target, in CSS pixels. 44x44 is the figure in Apple's Human
|
||||
// Interface Guidelines and in WCAG 2.2 SC 2.5.5 "Target Size (Enhanced)".
|
||||
// WCAG 2.2 SC 2.5.8 (level AA) sets a lower 24x24 floor, but that floor
|
||||
// comes with a spacing exception these controls do not qualify for: the
|
||||
// pin buttons sit directly against the host name they belong to. Held at
|
||||
// 44 deliberately.
|
||||
export const MIN_TAP_TARGET_PX = 44;
|
||||
|
||||
// The controls named in the definition of done, plus the pause button.
|
||||
export const INTERACTIVE_SELECTORS = [
|
||||
"#pause-btn",
|
||||
"#interval-select",
|
||||
".pin-btn",
|
||||
"#debug-toggle",
|
||||
];
|
||||
|
||||
// A host row is only "reflowed" if it stacked *and* went full width.
|
||||
// A row that merely shrank its 420px info column would keep
|
||||
// flex-direction: row, and a row that stacked but left the info column at
|
||||
// its fixed width would fail the width test.
|
||||
const FULL_WIDTH_FRACTION = 0.9;
|
||||
|
||||
function summarise(items, format, limit = 3) {
|
||||
const shown = items.slice(0, limit).map(format).join("; ");
|
||||
const rest = items.length > limit ? ` (+${items.length - limit} more)` : "";
|
||||
return shown + rest;
|
||||
}
|
||||
|
||||
// Collapse an overflow report to the elements actually responsible.
|
||||
// Identical elements (24 host rows all doing the same thing) are counted
|
||||
// rather than listed, and the deepest ones come first, since every
|
||||
// ancestor of an overflowing element also reports as overflowing.
|
||||
function deepestOffenders(entries) {
|
||||
const byElement = new Map();
|
||||
for (const entry of entries) {
|
||||
const reach = entry.reach ?? entry.right;
|
||||
const existing = byElement.get(entry.el);
|
||||
if (existing) {
|
||||
existing.count += 1;
|
||||
existing.reach = Math.max(existing.reach, reach);
|
||||
} else {
|
||||
byElement.set(entry.el, { ...entry, reach, count: 1 });
|
||||
}
|
||||
}
|
||||
return [...byElement.values()].sort(
|
||||
(a, b) => b.depth - a.depth || b.reach - a.reach,
|
||||
);
|
||||
}
|
||||
|
||||
function checkRowLayout(row, expectStacked) {
|
||||
if (expectStacked) {
|
||||
if (row.flexDirection !== "column") {
|
||||
return `row ${row.index}: flex-direction is ${row.flexDirection}, expected column`;
|
||||
}
|
||||
if (row.sparkline.top < row.info.bottom - 1) {
|
||||
return `row ${row.index}: sparkline top ${row.sparkline.top} is above info bottom ${row.info.bottom} — still side by side`;
|
||||
}
|
||||
const minWidth = row.containerWidth * FULL_WIDTH_FRACTION;
|
||||
if (row.info.width < minWidth) {
|
||||
return `row ${row.index}: info block is ${row.info.width}px of ${row.containerWidth}px — shrunk, not reflowed`;
|
||||
}
|
||||
if (row.sparkline.width < minWidth) {
|
||||
return `row ${row.index}: sparkline is ${row.sparkline.width}px of ${row.containerWidth}px — shrunk, not reflowed`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
if (row.flexDirection !== "row") {
|
||||
return `row ${row.index}: flex-direction is ${row.flexDirection}, expected row`;
|
||||
}
|
||||
if (row.sparkline.left < row.info.right - 1) {
|
||||
return `row ${row.index}: sparkline left ${row.sparkline.left} overlaps info right ${row.info.right} — not side by side`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function evaluateChecks(facts, viewport, probes) {
|
||||
const checks = [];
|
||||
const check = (name, ok, detail) => checks.push({ name, ok, detail });
|
||||
|
||||
// Guard against the whole harness passing vacuously because the page
|
||||
// never rendered. Everything below is only meaningful if this holds.
|
||||
check(
|
||||
"app-rendered",
|
||||
facts.rowCount >= 10 && facts.numericLatencies >= 5,
|
||||
`${facts.rowCount} host rows, ${facts.numericLatencies} showing a numeric latency`,
|
||||
);
|
||||
|
||||
const viewportWidth = Math.min(facts.innerWidth, facts.documentClientWidth);
|
||||
const culprits = deepestOffenders([
|
||||
...facts.overflowing,
|
||||
...facts.contentOverflowing,
|
||||
]);
|
||||
check(
|
||||
"no-horizontal-overflow",
|
||||
facts.documentScrollWidth <= viewportWidth,
|
||||
`documentElement.scrollWidth ${facts.documentScrollWidth} vs viewport ${viewportWidth}` +
|
||||
(culprits.length === 0
|
||||
? ""
|
||||
: "; widest content: " +
|
||||
summarise(
|
||||
culprits,
|
||||
(c) =>
|
||||
`${c.el} reaches ${Math.round(c.reach)}px${c.count > 1 ? ` (x${c.count})` : ""}`,
|
||||
)),
|
||||
);
|
||||
|
||||
check(
|
||||
"nothing-past-viewport-edge",
|
||||
facts.overflowing.length === 0,
|
||||
facts.overflowing.length === 0
|
||||
? "no element extends past the viewport"
|
||||
: `${facts.overflowing.length} element(s) past the edge: ` +
|
||||
summarise(
|
||||
facts.overflowing,
|
||||
(o) => `${o.el} spans ${o.left}..${o.right}`,
|
||||
),
|
||||
);
|
||||
|
||||
check(
|
||||
"no-clipped-text",
|
||||
facts.clipped.length === 0,
|
||||
facts.clipped.length === 0
|
||||
? "no element hides text behind overflow (deliberate ellipsis excluded)"
|
||||
: `${facts.clipped.length} element(s) clipping text: ` +
|
||||
summarise(
|
||||
facts.clipped,
|
||||
(c) =>
|
||||
`${c.el} scrollWidth ${c.scrollWidth} > clientWidth ${c.clientWidth}`,
|
||||
),
|
||||
);
|
||||
|
||||
if (viewport.touch) {
|
||||
const undersized = facts.tapTargets.filter(
|
||||
(t) => t.width < MIN_TAP_TARGET_PX || t.height < MIN_TAP_TARGET_PX,
|
||||
);
|
||||
const bySelector = new Map();
|
||||
for (const target of undersized) {
|
||||
const existing = bySelector.get(target.selector);
|
||||
if (!existing || target.width * target.height < existing.area) {
|
||||
bySelector.set(target.selector, {
|
||||
...target,
|
||||
area: target.width * target.height,
|
||||
count: (existing?.count ?? 0) + 1,
|
||||
});
|
||||
} else {
|
||||
existing.count += 1;
|
||||
}
|
||||
}
|
||||
check(
|
||||
`tap-targets-${MIN_TAP_TARGET_PX}px`,
|
||||
undersized.length === 0,
|
||||
undersized.length === 0
|
||||
? `all ${facts.tapTargets.length} controls are at least ${MIN_TAP_TARGET_PX}x${MIN_TAP_TARGET_PX}`
|
||||
: `${undersized.length} of ${facts.tapTargets.length} controls below ${MIN_TAP_TARGET_PX}x${MIN_TAP_TARGET_PX}: ` +
|
||||
summarise(
|
||||
[...bySelector.values()],
|
||||
(t) =>
|
||||
`${t.selector} ${t.width}x${t.height}${t.count > 1 ? ` (x${t.count})` : ""}`,
|
||||
4,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
const badRows = facts.rows
|
||||
.map((row) => checkRowLayout(row, viewport.expectStacked))
|
||||
.filter(Boolean);
|
||||
check(
|
||||
viewport.expectStacked ? "host-rows-stacked" : "host-rows-side-by-side",
|
||||
facts.rows.length > 0 && badRows.length === 0,
|
||||
facts.rows.length === 0
|
||||
? "no host rows were measured"
|
||||
: badRows.length === 0
|
||||
? `all ${facts.rows.length} rows laid out as expected`
|
||||
: `${badRows.length} of ${facts.rows.length} rows wrong: ` +
|
||||
summarise(badRows, (r) => r),
|
||||
);
|
||||
|
||||
// The mobile early-return path proposed in #8 was rejected: narrow
|
||||
// viewports must keep probing and keep detecting the gateway, not
|
||||
// quietly skip work.
|
||||
check(
|
||||
"probing-still-runs",
|
||||
probes.attempted > 0,
|
||||
`${probes.attempted} outbound probe requests issued`,
|
||||
);
|
||||
check(
|
||||
"gateway-detection-still-runs",
|
||||
facts.gatewayDetected,
|
||||
facts.gatewayDetected
|
||||
? "Local Gateway row present"
|
||||
: "no Local Gateway row — gateway detection did not run or did not complete",
|
||||
);
|
||||
|
||||
return checks;
|
||||
}
|
||||
@@ -1,184 +0,0 @@
|
||||
// Layout facts collected from inside the page.
|
||||
//
|
||||
// This function is serialised and evaluated in the browser, so it must be
|
||||
// entirely self-contained: no imports, no closures over module scope. It
|
||||
// only *measures*; every pass/fail decision is made back in node by
|
||||
// checks.js, so failures can be reported with real numbers attached.
|
||||
|
||||
export function collectLayoutFacts(options) {
|
||||
const describe = (el) => {
|
||||
const id = el.id ? "#" + el.id : "";
|
||||
const classes =
|
||||
typeof el.className === "string" && el.className.trim()
|
||||
? "." + el.className.trim().split(/\s+/).slice(0, 3).join(".")
|
||||
: "";
|
||||
return el.tagName.toLowerCase() + id + classes;
|
||||
};
|
||||
|
||||
const round = (n) => Math.round(n * 10) / 10;
|
||||
|
||||
// Overflow propagates up every ancestor, so a single wide element
|
||||
// reports as body, #app, the row, and so on. Depth lets the report
|
||||
// name the deepest — that is, the actual — offender.
|
||||
const depthOf = (el) => {
|
||||
let depth = 0;
|
||||
for (let node = el.parentElement; node; node = node.parentElement) {
|
||||
depth++;
|
||||
}
|
||||
return depth;
|
||||
};
|
||||
|
||||
const isVisible = (el) => {
|
||||
const style = getComputedStyle(el);
|
||||
if (style.display === "none") return false;
|
||||
if (style.visibility === "hidden") return false;
|
||||
const rect = el.getBoundingClientRect();
|
||||
return rect.width > 0 && rect.height > 0;
|
||||
};
|
||||
|
||||
const innerWidth = window.innerWidth;
|
||||
const clientWidth = document.documentElement.clientWidth;
|
||||
// Under mobile emulation Chrome lets window.innerWidth *grow* to the
|
||||
// width of overflowing content, exactly as a phone zooms out to fit a
|
||||
// too-wide page. Measuring against it would therefore hide the
|
||||
// overflow it is supposed to expose: at a 320px device width a page
|
||||
// that spills to 350 reports innerWidth 350 and looks clean. Every
|
||||
// comparison below is against the layout viewport instead.
|
||||
const viewportWidth = Math.min(innerWidth, clientWidth);
|
||||
const elements = Array.from(document.querySelectorAll("body *"));
|
||||
|
||||
// Elements sticking out past the right (or left) edge of the viewport.
|
||||
// The document-level scrollWidth check says *that* the page overflows;
|
||||
// this says *what* is doing it.
|
||||
const overflowing = [];
|
||||
// Elements clipping their own text. Deliberate ellipsis truncation
|
||||
// (Tailwind's `truncate`) is opt-in and excluded: it is a design
|
||||
// choice, not breakage.
|
||||
const clipped = [];
|
||||
// Elements whose content spills out of their own box without being
|
||||
// clipped, past the right edge of the viewport. A block element is
|
||||
// only ever as wide as its container, so text overflowing it has no
|
||||
// element rect of its own to catch — but it is exactly what drags
|
||||
// documentElement.scrollWidth past the viewport width, so without
|
||||
// this the page-level overflow failure has nothing to point at.
|
||||
const contentOverflowing = [];
|
||||
|
||||
for (const el of elements) {
|
||||
if (!isVisible(el)) continue;
|
||||
const rect = el.getBoundingClientRect();
|
||||
if (rect.right > viewportWidth + 1 || rect.left < -1) {
|
||||
overflowing.push({
|
||||
el: describe(el),
|
||||
depth: depthOf(el),
|
||||
left: round(rect.left),
|
||||
right: round(rect.right),
|
||||
});
|
||||
}
|
||||
const style = getComputedStyle(el);
|
||||
const clips =
|
||||
style.overflowX === "hidden" || style.overflowX === "clip";
|
||||
const ellipsis = style.textOverflow === "ellipsis";
|
||||
const hasText = el.textContent.trim().length > 0;
|
||||
const spills =
|
||||
el.clientWidth > 0 && el.scrollWidth > el.clientWidth + 1;
|
||||
if (clips && !ellipsis && hasText && spills) {
|
||||
clipped.push({
|
||||
el: describe(el),
|
||||
scrollWidth: el.scrollWidth,
|
||||
clientWidth: el.clientWidth,
|
||||
});
|
||||
}
|
||||
if (
|
||||
!clips &&
|
||||
spills &&
|
||||
rect.left + el.scrollWidth > viewportWidth + 1
|
||||
) {
|
||||
contentOverflowing.push({
|
||||
el: describe(el),
|
||||
depth: depthOf(el),
|
||||
scrollWidth: el.scrollWidth,
|
||||
clientWidth: el.clientWidth,
|
||||
reach: round(rect.left + el.scrollWidth),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Interactive controls. The measured target is the nearest thing that
|
||||
// is genuinely tappable — for a checkbox that is the <label> wrapping
|
||||
// it, which is larger than the box itself and is what a finger hits.
|
||||
const tapTargets = [];
|
||||
for (const selector of options.interactiveSelectors) {
|
||||
for (const el of document.querySelectorAll(selector)) {
|
||||
if (!isVisible(el)) continue;
|
||||
const target = el.closest("button, a, label, select") || el;
|
||||
const rect = target.getBoundingClientRect();
|
||||
tapTargets.push({
|
||||
selector,
|
||||
el: describe(target),
|
||||
width: round(rect.width),
|
||||
height: round(rect.height),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Host rows. The question is not "did it get narrower" but "did it
|
||||
// reflow": the info block and the sparkline must end up stacked
|
||||
// vertically and full width in the narrow layout, and side by side in
|
||||
// the wide one. Both the computed flex-direction and the actual
|
||||
// geometry are recorded so a row that claims to be a column but is
|
||||
// still laid out side by side cannot slip through.
|
||||
const rows = [];
|
||||
for (const row of document.querySelectorAll(".host-row")) {
|
||||
const inner = row.firstElementChild;
|
||||
if (!inner) continue;
|
||||
const sparkline = inner.querySelector(".sparkline-container");
|
||||
const info = sparkline ? sparkline.previousElementSibling : null;
|
||||
if (!sparkline || !info) continue;
|
||||
const innerStyle = getComputedStyle(inner);
|
||||
const innerRect = inner.getBoundingClientRect();
|
||||
const infoRect = info.getBoundingClientRect();
|
||||
const sparkRect = sparkline.getBoundingClientRect();
|
||||
rows.push({
|
||||
index: row.dataset.index,
|
||||
flexDirection: innerStyle.flexDirection,
|
||||
containerWidth: round(innerRect.width),
|
||||
info: {
|
||||
left: round(infoRect.left),
|
||||
right: round(infoRect.right),
|
||||
bottom: round(infoRect.bottom),
|
||||
width: round(infoRect.width),
|
||||
},
|
||||
sparkline: {
|
||||
left: round(sparkRect.left),
|
||||
top: round(sparkRect.top),
|
||||
width: round(sparkRect.width),
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
const localRows = Array.from(
|
||||
document.querySelectorAll("#local-hosts .host-row"),
|
||||
);
|
||||
|
||||
return {
|
||||
innerWidth,
|
||||
// innerWidth includes any classic scrollbar, clientWidth does not.
|
||||
// Reported separately so the overflow check can hold itself to the
|
||||
// narrower of the two rather than to whichever one is more
|
||||
// forgiving.
|
||||
documentClientWidth: document.documentElement.clientWidth,
|
||||
documentScrollWidth: document.documentElement.scrollWidth,
|
||||
overflowing,
|
||||
contentOverflowing,
|
||||
clipped,
|
||||
tapTargets,
|
||||
rows,
|
||||
rowCount: document.querySelectorAll(".host-row").length,
|
||||
numericLatencies: Array.from(
|
||||
document.querySelectorAll(".latency-value"),
|
||||
).filter((el) => /\d/.test(el.textContent)).length,
|
||||
gatewayDetected: localRows.some((row) =>
|
||||
row.textContent.includes("Local Gateway"),
|
||||
),
|
||||
};
|
||||
}
|
||||
@@ -1,258 +0,0 @@
|
||||
// Responsive-layout harness.
|
||||
//
|
||||
// Drives the built frontend in a real, containerised, digest-pinned Chrome
|
||||
// over CDP and asserts on computed layout at every viewport width derived
|
||||
// from the app's own CSS. Screenshots are written alongside as artifacts;
|
||||
// they are not the evidence, the assertions are.
|
||||
//
|
||||
// This is not meant to be run by hand. `make frontend-viewport-test` brings
|
||||
// up the browser and the web server and then runs this; every input it
|
||||
// needs arrives in the environment.
|
||||
|
||||
import { mkdirSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import puppeteer from "puppeteer-core";
|
||||
import { collectLayoutFacts } from "./facts.js";
|
||||
import { evaluateChecks, INTERACTIVE_SELECTORS } from "./checks.js";
|
||||
import { deriveViewports } from "./viewports.js";
|
||||
|
||||
function required(name) {
|
||||
const value = process.env[name];
|
||||
if (!value) {
|
||||
throw new Error(
|
||||
`${name} is not set; run this via script/frontend-viewport-test`,
|
||||
);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
const ROOT = required("NETWATCH_ROOT");
|
||||
const BASE_URL = required("NETWATCH_BASE_URL");
|
||||
const CDP_URL = required("NETWATCH_CDP_URL");
|
||||
const ARTIFACT_DIR = required("NETWATCH_ARTIFACT_DIR");
|
||||
|
||||
const BROWSER_TIMEOUT_MS = 60000;
|
||||
const PAGE_TIMEOUT_MS = 30000;
|
||||
|
||||
// Canned responses for the app's outbound latency probes. The browser
|
||||
// container sits on an --internal docker network and physically cannot
|
||||
// reach the internet, so nothing here is about blocking traffic; it is
|
||||
// about determinism. Real probes would render 24 rows of whatever the
|
||||
// network happened to be doing. These delays make the rows show a
|
||||
// realistic spread of value widths — one, two and three digit latencies,
|
||||
// plus some unreachable rows — because that spread is what the layout has
|
||||
// to survive.
|
||||
const PROBE_DELAYS_MS = [2, 45, 123, 456, 780];
|
||||
// One in every UNREACHABLE_MODULUS probes is failed outright so that the
|
||||
// offline row rendering is exercised too.
|
||||
const UNREACHABLE_MODULUS = 7;
|
||||
// The gateway candidate that "answers", so gateway detection succeeds and
|
||||
// the Local Gateway row renders. Matches GATEWAY_CANDIDATES in src/main.js.
|
||||
const RESPONSIVE_GATEWAY = "http://192.168.1.1";
|
||||
|
||||
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
||||
|
||||
function stableHash(text) {
|
||||
let hash = 0;
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
hash = (hash * 31 + text.charCodeAt(i)) | 0;
|
||||
}
|
||||
return Math.abs(hash);
|
||||
}
|
||||
|
||||
async function connectBrowser() {
|
||||
const deadline = Date.now() + BROWSER_TIMEOUT_MS;
|
||||
let lastError;
|
||||
for (;;) {
|
||||
try {
|
||||
const response = await fetch(`${CDP_URL}/json/version`);
|
||||
const info = await response.json();
|
||||
// The endpoint advertises whatever Host it was reached on;
|
||||
// pin it back to the address we actually dialled.
|
||||
const endpoint = new URL(info.webSocketDebuggerUrl);
|
||||
endpoint.host = new URL(CDP_URL).host;
|
||||
const browser = await puppeteer.connect({
|
||||
browserWSEndpoint: endpoint.toString(),
|
||||
protocolTimeout: BROWSER_TIMEOUT_MS,
|
||||
});
|
||||
return { browser, version: info.Browser };
|
||||
} catch (error) {
|
||||
lastError = error;
|
||||
if (Date.now() > deadline) {
|
||||
throw new Error(`browser never came up: ${lastError}`);
|
||||
}
|
||||
await sleep(250);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function installProbeResponder(page, probes) {
|
||||
const respond = (request, delayMs) =>
|
||||
sleep(delayMs).then(() =>
|
||||
request.respond({
|
||||
status: 200,
|
||||
contentType: "text/plain",
|
||||
body: "",
|
||||
}),
|
||||
);
|
||||
|
||||
page.on("request", (request) => {
|
||||
const url = request.url();
|
||||
const settle = async () => {
|
||||
if (url.startsWith(BASE_URL) || url.startsWith("data:")) {
|
||||
return request.continue();
|
||||
}
|
||||
probes.attempted++;
|
||||
if (url.startsWith(RESPONSIVE_GATEWAY)) {
|
||||
probes.fulfilled++;
|
||||
return respond(request, 5);
|
||||
}
|
||||
const hash = stableHash(url);
|
||||
if (hash % UNREACHABLE_MODULUS === 0) {
|
||||
probes.failed++;
|
||||
return request.abort("connectionfailed");
|
||||
}
|
||||
probes.fulfilled++;
|
||||
return respond(
|
||||
request,
|
||||
PROBE_DELAYS_MS[hash % PROBE_DELAYS_MS.length],
|
||||
);
|
||||
};
|
||||
// The page may be torn down while a delayed response is pending;
|
||||
// that is not a harness failure.
|
||||
settle().catch(() => {});
|
||||
});
|
||||
}
|
||||
|
||||
async function runViewport(browser, viewport) {
|
||||
const page = await browser.newPage();
|
||||
const probes = { attempted: 0, fulfilled: 0, failed: 0 };
|
||||
try {
|
||||
page.setDefaultTimeout(PAGE_TIMEOUT_MS);
|
||||
await page.setRequestInterception(true);
|
||||
installProbeResponder(page, probes);
|
||||
await page.setViewport({
|
||||
width: viewport.width,
|
||||
height: viewport.height,
|
||||
deviceScaleFactor: viewport.deviceScaleFactor,
|
||||
isMobile: viewport.touch,
|
||||
hasTouch: viewport.touch,
|
||||
isLandscape: viewport.width > viewport.height,
|
||||
});
|
||||
|
||||
await page.goto(BASE_URL, { waitUntil: "load" });
|
||||
await page.waitForSelector(".host-row");
|
||||
|
||||
// The app discards its first tick as a cold start, so rows only
|
||||
// carry real values from the second one. Changing the interval
|
||||
// restarts the loop at 1s, which reaches a populated UI without
|
||||
// waiting out two default 3s intervals — and exercises the
|
||||
// interval dropdown while we are at it.
|
||||
await page.select("#interval-select", "1000");
|
||||
await page.waitForFunction(
|
||||
() =>
|
||||
Array.from(document.querySelectorAll(".latency-value")).filter(
|
||||
(el) => /\d/.test(el.textContent),
|
||||
).length >= 5,
|
||||
);
|
||||
// Let the resize/redraw handlers settle before measuring.
|
||||
await page.evaluate(
|
||||
() =>
|
||||
new Promise((resolve) =>
|
||||
requestAnimationFrame(() => requestAnimationFrame(resolve)),
|
||||
),
|
||||
);
|
||||
|
||||
const facts = await page.evaluate(collectLayoutFacts, {
|
||||
interactiveSelectors: INTERACTIVE_SELECTORS,
|
||||
});
|
||||
|
||||
const screenshot = join(
|
||||
ARTIFACT_DIR,
|
||||
`${viewport.width}x${viewport.height}-${viewport.name}.png`,
|
||||
);
|
||||
await page.screenshot({ path: screenshot, fullPage: true });
|
||||
|
||||
return {
|
||||
viewport,
|
||||
probes,
|
||||
facts,
|
||||
screenshot,
|
||||
checks: evaluateChecks(facts, viewport, probes),
|
||||
};
|
||||
} finally {
|
||||
await page.close().catch(() => {});
|
||||
}
|
||||
}
|
||||
|
||||
function report(results, conditions, browserVersion) {
|
||||
const label = (viewport) =>
|
||||
`${viewport.width}x${viewport.height}`.padEnd(9) +
|
||||
" " +
|
||||
viewport.name.padEnd(24);
|
||||
|
||||
console.log(`browser: ${browserVersion}`);
|
||||
console.log(`served from: ${BASE_URL} (built dist/)`);
|
||||
console.log(
|
||||
"breakpoints: " +
|
||||
conditions
|
||||
.map((c) => `${c.type}-width ${c.px}px (${c.source})`)
|
||||
.join(", "),
|
||||
);
|
||||
console.log("");
|
||||
|
||||
let passed = 0;
|
||||
let failed = 0;
|
||||
for (const result of results) {
|
||||
const bad = result.checks.filter((c) => !c.ok);
|
||||
passed += result.checks.length - bad.length;
|
||||
failed += bad.length;
|
||||
// Passing viewports get one line. Detail is for failures.
|
||||
console.log(
|
||||
`${bad.length === 0 ? "PASS" : "FAIL"} ${label(result.viewport)} ` +
|
||||
`${result.checks.length - bad.length}/${result.checks.length} checks` +
|
||||
`${result.viewport.expectStacked ? " [narrow layout expected]" : ""}`,
|
||||
);
|
||||
for (const check of bad) {
|
||||
console.log(` ${check.name}: ${check.detail}`);
|
||||
}
|
||||
if (bad.length > 0) {
|
||||
console.log(` why this width: ${result.viewport.why}`);
|
||||
console.log(` screenshot: ${result.screenshot}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log("");
|
||||
console.log(
|
||||
`${results.length} viewports, ${passed + failed} checks: ` +
|
||||
`${passed} passed, ${failed} failed`,
|
||||
);
|
||||
console.log(`artifacts: ${ARTIFACT_DIR}`);
|
||||
return failed;
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const { conditions, viewports } = deriveViewports(ROOT);
|
||||
mkdirSync(ARTIFACT_DIR, { recursive: true });
|
||||
|
||||
const { browser, version } = await connectBrowser();
|
||||
const results = [];
|
||||
try {
|
||||
for (const viewport of viewports) {
|
||||
results.push(await runViewport(browser, viewport));
|
||||
}
|
||||
} finally {
|
||||
await browser.disconnect().catch(() => {});
|
||||
}
|
||||
|
||||
writeFileSync(
|
||||
join(ARTIFACT_DIR, "results.json"),
|
||||
JSON.stringify({ browser: version, conditions, results }, null, 2) +
|
||||
"\n",
|
||||
);
|
||||
|
||||
const failed = report(results, conditions, version);
|
||||
process.exitCode = failed === 0 ? 0 : 1;
|
||||
}
|
||||
|
||||
await main();
|
||||
@@ -1,185 +0,0 @@
|
||||
// Viewport derivation for the responsive-layout harness.
|
||||
//
|
||||
// The widths tested are read out of the CSS the application actually
|
||||
// ships, not taken from a list of popular phone models. A generic 375px
|
||||
// "phone" test sails straight past an off-by-one error at a media query
|
||||
// boundary, which is the classic way a responsive layout breaks, so
|
||||
// every breakpoint found in the sources is probed three times: one pixel
|
||||
// below it, exactly on it, and one pixel above it.
|
||||
//
|
||||
// Nothing here hardcodes 768. If someone adds a second media block or
|
||||
// starts using Tailwind responsive prefixes, that breakpoint starts
|
||||
// being covered without this file being edited.
|
||||
|
||||
import { readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
// Tailwind CSS v4 default breakpoints, in rem. The app currently uses
|
||||
// none of these prefixes, so the whole table is inert until someone
|
||||
// writes an `md:`-prefixed utility class.
|
||||
const TAILWIND_BREAKPOINT_REM = {
|
||||
sm: 40,
|
||||
md: 48,
|
||||
lg: 64,
|
||||
xl: 80,
|
||||
"2xl": 96,
|
||||
};
|
||||
|
||||
// The app does not override the root font size, so rem and em in media
|
||||
// queries resolve against the browser default.
|
||||
const ROOT_FONT_SIZE_PX = 16;
|
||||
|
||||
// Extract every min-width / max-width condition from the @media blocks in
|
||||
// a stylesheet. Returns e.g. [{ type: "max", px: 768, source: "..." }].
|
||||
export function mediaConditionsFromCss(css, source) {
|
||||
const conditions = [];
|
||||
for (const block of css.matchAll(/@media([^{]+)\{/g)) {
|
||||
const features = block[1].matchAll(
|
||||
/\(\s*(min|max)-width\s*:\s*([\d.]+)(px|rem|em)\s*\)/g,
|
||||
);
|
||||
for (const feature of features) {
|
||||
const scale = feature[3] === "px" ? 1 : ROOT_FONT_SIZE_PX;
|
||||
conditions.push({
|
||||
type: feature[1],
|
||||
px: Math.round(Number(feature[2]) * scale),
|
||||
source,
|
||||
});
|
||||
}
|
||||
}
|
||||
return conditions;
|
||||
}
|
||||
|
||||
// Extract the breakpoints implied by Tailwind responsive prefixes used in
|
||||
// markup. A prefix only counts when it opens a utility class, so `text-sm`
|
||||
// does not masquerade as the `sm:` breakpoint.
|
||||
export function mediaConditionsFromMarkup(sources) {
|
||||
const conditions = [];
|
||||
for (const { path, text } of sources) {
|
||||
for (const [name, rem] of Object.entries(TAILWIND_BREAKPOINT_REM)) {
|
||||
const used = new RegExp(
|
||||
`(^|["'\\s])${name}:[a-z0-9[\\](),_./%-]+`,
|
||||
"m",
|
||||
).test(text);
|
||||
if (used) {
|
||||
conditions.push({
|
||||
type: "min",
|
||||
px: rem * ROOT_FONT_SIZE_PX,
|
||||
source: path,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return conditions;
|
||||
}
|
||||
|
||||
// Whether a given width should be rendering the app's narrow (stacked)
|
||||
// layout. The app keeps all of its narrow-viewport rules inside
|
||||
// `max-width` blocks, so a width is narrow exactly when one of those
|
||||
// blocks matches. Note that `max-width: 768px` matches *at* 768: getting
|
||||
// this inclusive boundary wrong in either direction is precisely what the
|
||||
// three-widths-per-breakpoint sweep exists to catch.
|
||||
export function expectsStackedLayout(width, conditions) {
|
||||
return conditions.some((c) => c.type === "max" && width <= c.px);
|
||||
}
|
||||
|
||||
// Viewports that are not derived from a breakpoint. Each one is here for
|
||||
// a stated reason; none of them is a stand-in for "a phone".
|
||||
const ANCHOR_VIEWPORTS = [
|
||||
{
|
||||
name: "floor-portrait",
|
||||
width: 320,
|
||||
height: 568,
|
||||
deviceScaleFactor: 2,
|
||||
touch: true,
|
||||
why: "320px is the narrowest viewport still in mainstream use; nothing has to work below it",
|
||||
},
|
||||
{
|
||||
name: "phone-landscape-narrow",
|
||||
width: 667,
|
||||
height: 375,
|
||||
deviceScaleFactor: 2,
|
||||
touch: true,
|
||||
why: "phone rotated to landscape, still inside the narrow layout",
|
||||
},
|
||||
{
|
||||
name: "phone-landscape-wide",
|
||||
width: 844,
|
||||
height: 390,
|
||||
deviceScaleFactor: 3,
|
||||
touch: true,
|
||||
why: "large phone rotated to landscape: crosses into the wide layout while still being a touch device",
|
||||
},
|
||||
{
|
||||
name: "desktop",
|
||||
width: 1280,
|
||||
height: 800,
|
||||
deviceScaleFactor: 1,
|
||||
touch: false,
|
||||
why: "desktop baseline",
|
||||
},
|
||||
];
|
||||
|
||||
export function deriveViewports(root) {
|
||||
const conditions = [
|
||||
...mediaConditionsFromCss(
|
||||
readFileSync(join(root, "src/styles.css"), "utf8"),
|
||||
"src/styles.css",
|
||||
),
|
||||
...mediaConditionsFromMarkup([
|
||||
{
|
||||
path: "src/main.js",
|
||||
text: readFileSync(join(root, "src/main.js"), "utf8"),
|
||||
},
|
||||
{
|
||||
path: "index.html",
|
||||
text: readFileSync(join(root, "index.html"), "utf8"),
|
||||
},
|
||||
]),
|
||||
];
|
||||
|
||||
if (conditions.length === 0) {
|
||||
throw new Error(
|
||||
"no responsive breakpoints found in src/styles.css, src/main.js or " +
|
||||
"index.html — either the responsive layout was deleted or this " +
|
||||
"derivation has stopped matching the sources",
|
||||
);
|
||||
}
|
||||
|
||||
const viewports = new Map();
|
||||
const add = (viewport) => {
|
||||
const key = `${viewport.width}x${viewport.height}`;
|
||||
if (!viewports.has(key)) viewports.set(key, viewport);
|
||||
};
|
||||
|
||||
for (const condition of conditions) {
|
||||
for (const [offset, label] of [
|
||||
[-1, "below"],
|
||||
[0, "at"],
|
||||
[+1, "above"],
|
||||
]) {
|
||||
const width = condition.px + offset;
|
||||
add({
|
||||
name: `${condition.type}-width-${condition.px}-${label}`,
|
||||
width,
|
||||
// Tall enough that the whole app is laid out in one column
|
||||
// without the viewport height influencing wrapping.
|
||||
height: 1024,
|
||||
deviceScaleFactor: 2,
|
||||
touch: true,
|
||||
why: `${offset === 0 ? "exactly on" : `1px ${label}`} the ${condition.type}-width: ${condition.px}px breakpoint declared in ${condition.source}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for (const anchor of ANCHOR_VIEWPORTS) add(anchor);
|
||||
|
||||
return {
|
||||
conditions,
|
||||
viewports: [...viewports.values()]
|
||||
.map((viewport) => ({
|
||||
...viewport,
|
||||
expectStacked: expectsStackedLayout(viewport.width, conditions),
|
||||
}))
|
||||
.sort((a, b) => a.width - b.width || a.height - b.height),
|
||||
};
|
||||
}
|
||||
154
yarn.lock
154
yarn.lock
@@ -197,14 +197,6 @@
|
||||
"@emnapi/runtime" "^1.7.1"
|
||||
"@tybys/wasm-util" "^0.10.1"
|
||||
|
||||
"@puppeteer/browsers@3.1.0":
|
||||
version "3.1.0"
|
||||
resolved "https://registry.yarnpkg.com/@puppeteer/browsers/-/browsers-3.1.0.tgz#5728ae0bc649263133ac1f8bd5d360eb75d11748"
|
||||
integrity sha512-RDLpio3fH/qrj5k4DVY6eyiN8tCS0Zovd/6jW//n605oeqkWcUjn+3k+9ZtZBnbwMpsu0F7xDIiKXvVmG5c5Bw==
|
||||
dependencies:
|
||||
modern-tar "^0.7.6"
|
||||
yargs "^18.0.0"
|
||||
|
||||
"@rollup/rollup-android-arm-eabi@4.57.0":
|
||||
version "4.57.0"
|
||||
resolved "https://registry.yarnpkg.com/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.57.0.tgz#f762035679a6b168138c94c960fda0b0cdb00d98"
|
||||
@@ -449,16 +441,6 @@
|
||||
resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.8.tgz#958b91c991b1867ced318bedea0e215ee050726e"
|
||||
integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==
|
||||
|
||||
ansi-regex@^6.2.2:
|
||||
version "6.2.2"
|
||||
resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.2.2.tgz#60216eea464d864597ce2832000738a0589650c1"
|
||||
integrity sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==
|
||||
|
||||
ansi-styles@^6.2.1:
|
||||
version "6.2.3"
|
||||
resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-6.2.3.tgz#c044d5dcc521a076413472597a1acb1f103c4041"
|
||||
integrity sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==
|
||||
|
||||
autoprefixer@^10.4.23:
|
||||
version "10.4.23"
|
||||
resolved "https://registry.yarnpkg.com/autoprefixer/-/autoprefixer-10.4.23.tgz#c6aa6db8e7376fcd900f9fd79d143ceebad8c4e6"
|
||||
@@ -491,43 +473,16 @@ caniuse-lite@^1.0.30001759, caniuse-lite@^1.0.30001760:
|
||||
resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001766.tgz#b6f6b55cb25a2d888d9393104d14751c6a7d6f7a"
|
||||
integrity sha512-4C0lfJ0/YPjJQHagaE9x2Elb69CIqEPZeG0anQt9SIvIoOH4a4uaRl73IavyO+0qZh6MDLH//DrXThEYKHkmYA==
|
||||
|
||||
chromium-bidi@17.0.2:
|
||||
version "17.0.2"
|
||||
resolved "https://registry.yarnpkg.com/chromium-bidi/-/chromium-bidi-17.0.2.tgz#921a586deecd0c2d8b9242c4c1b73c3aa39ff77c"
|
||||
integrity sha512-5v9GQFhTktFvotn/OFNJBmKLKRAb6n9r0bVCwf7sHgWc3/JryK0bj1nn93L3pHFrfgcsu6Be6EWsDi+1XHTGDg==
|
||||
dependencies:
|
||||
mitt "^3.0.1"
|
||||
zod "^3.24.1"
|
||||
|
||||
cliui@^9.0.1:
|
||||
version "9.0.1"
|
||||
resolved "https://registry.yarnpkg.com/cliui/-/cliui-9.0.1.tgz#6f7890f386f6f1f79953adc1f78dec46fcc2d291"
|
||||
integrity sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==
|
||||
dependencies:
|
||||
string-width "^7.2.0"
|
||||
strip-ansi "^7.1.0"
|
||||
wrap-ansi "^9.0.0"
|
||||
|
||||
detect-libc@^2.0.3:
|
||||
version "2.1.2"
|
||||
resolved "https://registry.yarnpkg.com/detect-libc/-/detect-libc-2.1.2.tgz#689c5dcdc1900ef5583a4cb9f6d7b473742074ad"
|
||||
integrity sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==
|
||||
|
||||
devtools-protocol@0.0.1653615:
|
||||
version "0.0.1653615"
|
||||
resolved "https://registry.yarnpkg.com/devtools-protocol/-/devtools-protocol-0.0.1653615.tgz#c600e0c619612156b2422a66d958ba188d87dbe8"
|
||||
integrity sha512-pGVkY3T/qXxAp2nFPodwYqOevk6ncNMSmvL8QfRCx5ZWGd6Vor7AFNmyaA8Zs6uJyP1QAfjuLandCgvSix1BNA==
|
||||
|
||||
electron-to-chromium@^1.5.263:
|
||||
version "1.5.282"
|
||||
resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.282.tgz#6695816e5b170210d6aa07561546ed7d97347630"
|
||||
integrity sha512-FCPkJtpst28UmFzd903iU7PdeVTfY0KAeJy+Lk0GLZRwgwYHn/irRcaCbQQOmr5Vytc/7rcavsYLvTM8RiHYhQ==
|
||||
|
||||
emoji-regex@^10.3.0:
|
||||
version "10.6.0"
|
||||
resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-10.6.0.tgz#bf3d6e8f7f8fd22a65d9703475bc0147357a6b0d"
|
||||
integrity sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==
|
||||
|
||||
enhanced-resolve@^5.18.3:
|
||||
version "5.18.4"
|
||||
resolved "https://registry.yarnpkg.com/enhanced-resolve/-/enhanced-resolve-5.18.4.tgz#c22d33055f3952035ce6a144ce092447c525f828"
|
||||
@@ -568,7 +523,7 @@ esbuild@^0.27.0:
|
||||
"@esbuild/win32-ia32" "0.27.2"
|
||||
"@esbuild/win32-x64" "0.27.2"
|
||||
|
||||
escalade@^3.1.1, escalade@^3.2.0:
|
||||
escalade@^3.2.0:
|
||||
version "3.2.0"
|
||||
resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.2.0.tgz#011a3f69856ba189dffa7dc8fcce99d2a87903e5"
|
||||
integrity sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==
|
||||
@@ -588,16 +543,6 @@ fsevents@~2.3.2, fsevents@~2.3.3:
|
||||
resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.3.tgz#cac6407785d03675a2a5e1a5305c697b347d90d6"
|
||||
integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==
|
||||
|
||||
get-caller-file@^2.0.5:
|
||||
version "2.0.5"
|
||||
resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-2.0.5.tgz#4f94412a82db32f36e3b0b9741f8a97feb031f7e"
|
||||
integrity sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==
|
||||
|
||||
get-east-asian-width@^1.0.0, get-east-asian-width@^1.5.0:
|
||||
version "1.6.0"
|
||||
resolved "https://registry.yarnpkg.com/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz#216900f91df11a8b2c198c3e1d93d6c035a776b9"
|
||||
integrity sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==
|
||||
|
||||
graceful-fs@^4.2.4:
|
||||
version "4.2.11"
|
||||
resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3"
|
||||
@@ -689,16 +634,6 @@ magic-string@^0.30.21:
|
||||
dependencies:
|
||||
"@jridgewell/sourcemap-codec" "^1.5.5"
|
||||
|
||||
mitt@^3.0.1:
|
||||
version "3.0.1"
|
||||
resolved "https://registry.yarnpkg.com/mitt/-/mitt-3.0.1.tgz#ea36cf0cc30403601ae074c8f77b7092cdab36d1"
|
||||
integrity sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==
|
||||
|
||||
modern-tar@^0.7.6:
|
||||
version "0.7.7"
|
||||
resolved "https://registry.yarnpkg.com/modern-tar/-/modern-tar-0.7.7.tgz#ca71d79603630076b10733b0751ccab284bbc1ef"
|
||||
integrity sha512-t9VmxaqrmANnEOBhpSDI6HD192Ge48k8vmWqQQL7hSFEqHEYwZbbsu49+aKLWZeRvFs3j1pMhXOqqF4kPlvjkQ==
|
||||
|
||||
nanoid@^3.3.11:
|
||||
version "3.3.11"
|
||||
resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.11.tgz#4f4f112cefbe303202f2199838128936266d185b"
|
||||
@@ -738,18 +673,6 @@ prettier@^3.8.1:
|
||||
resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
|
||||
integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
|
||||
|
||||
puppeteer-core@25.5.0:
|
||||
version "25.5.0"
|
||||
resolved "https://registry.yarnpkg.com/puppeteer-core/-/puppeteer-core-25.5.0.tgz#a41b14d582056b998e0bc3561ac47c7615d38a53"
|
||||
integrity sha512-XPNT0dQJtphqQ4I29zxlG4IIPbg1iEHAQKWuQgtMJGXjACV77pZSmJvDi51IIIfd+DTKICcopJwUx4upVQ4XbA==
|
||||
dependencies:
|
||||
"@puppeteer/browsers" "3.1.0"
|
||||
chromium-bidi "17.0.2"
|
||||
devtools-protocol "0.0.1653615"
|
||||
typed-query-selector "^2.12.2"
|
||||
webdriver-bidi-protocol "0.4.2"
|
||||
ws "^8.21.1"
|
||||
|
||||
rollup@^4.43.0:
|
||||
version "4.57.0"
|
||||
resolved "https://registry.yarnpkg.com/rollup/-/rollup-4.57.0.tgz#9fa13c1fb779d480038f45708b5e01b9449b6853"
|
||||
@@ -789,30 +712,6 @@ source-map-js@^1.2.1:
|
||||
resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.1.tgz#1ce5650fddd87abc099eda37dcff024c2667ae46"
|
||||
integrity sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==
|
||||
|
||||
string-width@^7.0.0, string-width@^7.2.0:
|
||||
version "7.2.0"
|
||||
resolved "https://registry.yarnpkg.com/string-width/-/string-width-7.2.0.tgz#b5bb8e2165ce275d4d43476dd2700ad9091db6dc"
|
||||
integrity sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==
|
||||
dependencies:
|
||||
emoji-regex "^10.3.0"
|
||||
get-east-asian-width "^1.0.0"
|
||||
strip-ansi "^7.1.0"
|
||||
|
||||
string-width@^8.2.1:
|
||||
version "8.2.2"
|
||||
resolved "https://registry.yarnpkg.com/string-width/-/string-width-8.2.2.tgz#7310516493df575742fe98af6fae87d85d5ed0ac"
|
||||
integrity sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==
|
||||
dependencies:
|
||||
get-east-asian-width "^1.5.0"
|
||||
strip-ansi "^7.1.2"
|
||||
|
||||
strip-ansi@^7.1.0, strip-ansi@^7.1.2:
|
||||
version "7.2.0"
|
||||
resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-7.2.0.tgz#d22a269522836a627af8d04b5c3fd2c7fa3e32e3"
|
||||
integrity sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==
|
||||
dependencies:
|
||||
ansi-regex "^6.2.2"
|
||||
|
||||
tailwindcss@4.1.18, tailwindcss@^4.1.18:
|
||||
version "4.1.18"
|
||||
resolved "https://registry.yarnpkg.com/tailwindcss/-/tailwindcss-4.1.18.tgz#f488ba47853abdb5354daf9679d3e7791fc4f4e3"
|
||||
@@ -836,11 +735,6 @@ tslib@^2.4.0:
|
||||
resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f"
|
||||
integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
|
||||
|
||||
typed-query-selector@^2.12.2:
|
||||
version "2.12.2"
|
||||
resolved "https://registry.yarnpkg.com/typed-query-selector/-/typed-query-selector-2.12.2.tgz#65e2462ac6b0aecfae1bfac1a4f3027070dbabaa"
|
||||
integrity sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==
|
||||
|
||||
update-browserslist-db@^1.2.0:
|
||||
version "1.2.3"
|
||||
resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz#64d76db58713136acbeb4c49114366cc6cc2e80d"
|
||||
@@ -862,49 +756,3 @@ vite@^7.3.1:
|
||||
tinyglobby "^0.2.15"
|
||||
optionalDependencies:
|
||||
fsevents "~2.3.3"
|
||||
|
||||
webdriver-bidi-protocol@0.4.2:
|
||||
version "0.4.2"
|
||||
resolved "https://registry.yarnpkg.com/webdriver-bidi-protocol/-/webdriver-bidi-protocol-0.4.2.tgz#f51bb71c2606e90e3d5727607c728b25d617b58b"
|
||||
integrity sha512-VSV+fzfChirL3e7jay2yUC7B4HQCGtEWEg/MSSQbK+qWbqeGlRLlXTzPpYr3XGUvbpDHumWZBJxgesg4N7dbtA==
|
||||
|
||||
wrap-ansi@^9.0.0:
|
||||
version "9.0.2"
|
||||
resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-9.0.2.tgz#956832dea9494306e6d209eb871643bb873d7c98"
|
||||
integrity sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==
|
||||
dependencies:
|
||||
ansi-styles "^6.2.1"
|
||||
string-width "^7.0.0"
|
||||
strip-ansi "^7.1.0"
|
||||
|
||||
ws@^8.21.1:
|
||||
version "8.21.3"
|
||||
resolved "https://registry.yarnpkg.com/ws/-/ws-8.21.3.tgz#660b4faddb6a3e575c86e078126919961f4de4fc"
|
||||
integrity sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==
|
||||
|
||||
y18n@^5.0.5:
|
||||
version "5.0.8"
|
||||
resolved "https://registry.yarnpkg.com/y18n/-/y18n-5.0.8.tgz#7f4934d0f7ca8c56f95314939ddcd2dd91ce1d55"
|
||||
integrity sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==
|
||||
|
||||
yargs-parser@^22.0.0:
|
||||
version "22.0.0"
|
||||
resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-22.0.0.tgz#87b82094051b0567717346ecd00fd14804b357c8"
|
||||
integrity sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==
|
||||
|
||||
yargs@^18.0.0:
|
||||
version "18.1.0"
|
||||
resolved "https://registry.yarnpkg.com/yargs/-/yargs-18.1.0.tgz#cd7e98c703ef51695bbbf062ed58f28e94291b56"
|
||||
integrity sha512-2rAgRKu54VsHkqI0/tYkmluGXHD4KW7yZoycuqDQ15QOTnc2VVfy0nN/1eMhnQLO00A+dwtK20xuCnc1YGeUyg==
|
||||
dependencies:
|
||||
cliui "^9.0.1"
|
||||
escalade "^3.1.1"
|
||||
get-caller-file "^2.0.5"
|
||||
string-width "^8.2.1"
|
||||
y18n "^5.0.5"
|
||||
yargs-parser "^22.0.0"
|
||||
|
||||
zod@^3.24.1:
|
||||
version "3.25.76"
|
||||
resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.76.tgz#26841c3f6fd22a6a2760e7ccb719179768471e34"
|
||||
integrity sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==
|
||||
|
||||
Reference in New Issue
Block a user