diff --git a/.dockerignore b/.dockerignore index 8db1dad..9902b39 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,53 +1,86 @@ -# Mirrors .gitignore, with one deliberate exception: .gitignore itself stays -# in the build context, because prettier 3 reads it as a default ignore file -# and dropping it would change what the lint phase's prettier check sees. +# .dockerignore does NOT use .gitignore semantics. Docker matches with +# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross +# `/` and an unprefixed pattern is anchored at the context root. Every +# depth-independent pattern therefore needs `**/`, or `config/.env` and +# `certs/server.key` still ship while this file reads as solved. Only +# genuinely root-anchored entries go unprefixed. Never transplant these +# into .gitignore, where `**/` is wrong. # -# .git is deliberately NOT excluded: the build derives the version it stamps -# from it (script/version). It is sent without its config, which holds the -# clone's remote URL and any credential in it, and which the build stage, the -# final image, would otherwise carry. git describe does not need it. -.git/config +# Matching is case-sensitive, so secrets use character ranges rather +# than an ALL-CAPS twin, which would still miss `Server.Key`. +# +# Extend with this repo's own host-built artifacts, written anchored: +# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and +# deletes the package directory from the context. -# OS -.DS_Store -Thumbs.db +# .git is sent without its config. Without a VERSION build argument the +# stage that compiles runs `git describe --tags --always` on .git, which +# does not need .git/config; that file can hold a credential, such as a +# password in a remote URL or the token the CI checkout step stores there. +# Each submodule keeps a config with the same exposure in its git directory +# under .git/modules/, nested again for a submodule's own submodules, or in +# its own .git directory when it keeps one. +# KNOWN GAP: a submodule whose name has a `config` segment (`config`, +# `deploy/config`, `config/lib`) loses its whole git directory, because +# `**/.git/modules/**/config` also matches that segment's directory +# under .git/modules/. Go's version stamping then fails the build; +# nothing leaks. Name such a submodule without that segment: +# `git submodule add --name`. +**/.git/config +**/.git/modules/**/config -# Editors -*.swp -*.swo -*~ -*.bak -.idea/ -.vscode/ -*.sublime-* +# Agent scratch: one full checkout of the repo per in-flight agent. +# Anchored because it occurs once where agents run at the repo root. +# KNOWN GAP: a repo running agents in subdirectories still ships +# `services/api/.claude/` and must add its own anchored entry. +.claude -# Node -node_modules +# Environment files. `*.env` covers bare `.env` and the `prod.env` +# convention. Re-include a committed template with a negation if the +# build needs one: `!docs/example.env`. +**/*.[eE][nN][vV] +**/.[eE][nN][vV].* +**/.[eE][nN][vV][rR][cC] -# TypeScript / build artifacts -dist -build -*.tsbuildinfo -coverage -.nyc_output/ +# Private keys and the bundles carrying them. Public certificates +# (*.crt, *.cer) are deliberately absent: they are legitimate inputs. +**/*.[pP][eE][mM] +**/*.[kK][eE][yY] +**/*.[pP]12 +**/*.[pP][fF][xX] +**/[iI][dD]_[rR][sS][aA] +**/[iI][dD]_[dD][sS][aA] +**/[iI][dD]_[eE][cC][dD][sS][aA] +**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK] +**/[iI][dD]_[eE][dD]25519 +**/[iI][dD]_[eE][dD]25519_[sS][kK] -# Vitest -.vitest-cache/ +# Dependencies: restored inside the image, never copied in. +**/node_modules -# Environment / secrets -.env -.env.* -*.pem -*.key +# OS metadata. +**/.DS_Store +**/Thumbs.db + +# Editor state: never a build input, and it churns COPY. +**/*.swp +**/*.swo +**/*~ +**/*.bak +**/.idea +**/.vscode +**/*.sublime-* + +# TypeScript / build artifacts: the image compiles its own. +/dist +/build +/*.tsbuildinfo +/coverage +/.nyc_output +/.vitest-cache # Compiled binary (built by make build-bin); around 100 MB -bin/quak +/bin/quak # quak runtime data (in case anyone runs the CLI from inside the repo) -.quak/ - -# Local per-developer tool state, including agent worktrees. Correctness, -# not context size: a worktree copied in here has its own test/ tree, which -# vitest globs alongside the real one, so the containerised suite runs N+1 -# times over and still reports success. -.claude/ +/.quak diff --git a/.gitignore b/.gitignore index 7820f68..ca2f6e2 100644 --- a/.gitignore +++ b/.gitignore @@ -11,9 +11,41 @@ Thumbs.db .vscode/ *.sublime-* +# Agent scratch (worktrees of this repo, created and destroyed by +# in-flight tooling). Unanchored: .gitignore patterns already match at +# every depth, so no prefix is wanted here. This is not a .dockerignore +# entry and must not be given a `**/` prefix on the way into one. +.claude/ + # Node node_modules/ +# Secrets. Unanchored like every entry above, so each matches at every +# depth. Matching is case-sensitive on Linux, so names use character +# ranges rather than a lowercase form that misses `Server.Key`. + +# Environment files. `*.env` covers bare `.env` and the `prod.env` +# convention. Only the templates `example.env` and `sample.env` are +# re-included below. A repository that commits any other template adds +# its own negation after these lines, for example `!.env.example`. +*.[eE][nN][vV] +.[eE][nN][vV].* +.[eE][nN][vV][rR][cC] +!example.env +!sample.env + +# Private keys and the bundles carrying them. +*.[pP][eE][mM] +*.[kK][eE][yY] +*.[pP]12 +*.[pP][fF][xX] +[iI][dD]_[rR][sS][aA] +[iI][dD]_[dD][sS][aA] +[iI][dD]_[eE][cC][dD][sS][aA] +[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK] +[iI][dD]_[eE][dD]25519 +[iI][dD]_[eE][dD]25519_[sS][kK] + # TypeScript / build artifacts dist/ build/ @@ -24,18 +56,8 @@ coverage/ # Vitest .vitest-cache/ -# Environment / secrets -.env -.env.* -*.pem -*.key - # Compiled binary (built by make build-bin) bin/quak # quak runtime data (in case anyone runs the CLI from inside the repo) .quak/ - -# Local per-developer tool settings and scratch state, including the -# worktrees agents check out under this directory -.claude/ diff --git a/.prettierignore b/.prettierignore index ffce635..23d67fc 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,5 +1,2 @@ node_modules/ yarn.lock -dist/ -build/ -coverage/ diff --git a/Dockerfile b/Dockerfile index 03a95a3..f67c63b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -58,6 +58,8 @@ COPY --from=test /app/package.json /dev/null COPY script/ script/ COPY package.json yarn.lock ./ RUN script/bootstrap +# A tar-stream context keeps the sender's file owners, which git refuses. +RUN git config --system --add safe.directory /app COPY . . diff --git a/README.md b/README.md index 354c53d..dbd05f2 100644 --- a/README.md +++ b/README.md @@ -137,16 +137,15 @@ alpine. We provide: - `script/lint` — run eslint and a prettier check, by building the `lint` phase of the `Dockerfile`; requires docker (see Linting and testing below) - `script/fmt` — format all files with prettier (writes) -- `script/fmt-check` — check formatting on the host (read-only); standalone, and - not called by `script/check` or `script/precommit`, because `script/lint` - already checks formatting in the container -- `script/check` — run all checks: `test`, `lint` (our own extension) +- `script/fmt-check` — check formatting on the host (read-only) +- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own + extension) - `script/docker` — build the image, tagged via `script/projectname` -- `script/cibuild` — build the image (what CI runs); its last stage depends on - the `lint` and `test` phases, so this one build lints, tests and compiles +- `script/cibuild` — what CI runs: `script/bootstrap`, then `script/check`, then + the image build - `script/precommit` — run by the git pre-commit hook (our own extension); runs - `script/lint`, which checks both lint and formatting, but deliberately not the - tests, so the TDD red-phase commit can land + `script/lint` and `script/fmt-check` but deliberately not the tests, so the + TDD red-phase commit can land - `script/install-precommit` — installs the git pre-commit hook (our own extension); `make hooks` shims to it @@ -162,22 +161,19 @@ script runs the tools on the host: docker is required, and that also works where the docker daemon is remote and bind mounts are impossible. The last stage of the `Dockerfile` compiles the package, and it copies a file -from each phase, so it cannot be built unless lint and the tests pass. That is -why `script/cibuild` is a single `docker build`: it runs lint and the tests once -each and then compiles. +from each phase, so it cannot be built unless lint and the tests pass. The image +build in `script/cibuild` therefore runs lint and the tests a second time, after +`script/check` has run them. Every `docker build` in `script/` passes `--no-cache`. On an unchanged tree Docker would otherwise serve the lint and test steps from cache, nothing would run, and the build would still exit 0. -The formatting check is part of the `lint` phase, not a step beside it, so -`script/check` and `script/precommit` do not call `script/fmt-check` as well; -that would run prettier a second time over the same tree for the same verdict. -`script/fmt-check` remains as a standalone entrypoint for asking the formatting -question on the host. Its verdict matches the container's: prettier is pinned to -an exact version, installed from `yarn.lock` under `--frozen-lockfile` in both -places, and reads `.gitignore` as its default ignore file — which is why -`.dockerignore` keeps `.gitignore` in the build context. +`script/fmt-check` runs prettier on the host. Its verdict matches the `lint` +phase's: prettier is pinned to an exact version, installed from `yarn.lock` +under `--frozen-lockfile` in both places, and reads `.gitignore` as its default +ignore file — which is why `.dockerignore` keeps `.gitignore` in the build +context. ### Version @@ -259,11 +255,10 @@ All work on quak is test-driven. No exceptions. history must still show tests landing before (or with) the matching implementation. 8. The pre-commit hook installed by `make hooks` runs `script/precommit`, which - runs `script/lint` — eslint and the prettier check, in the container — but - not the tests, and so not the full `make check`. This is deliberate so the - TDD red-phase commit (failing tests, no implementation yet) can land. The - `test` phase is part of the image build, which is what CI executes via - `script/cibuild`, so a red branch still cannot reach `next`. + runs `script/lint` and `script/fmt-check` but not the tests, and so not the + full `make check`. This is deliberate so the TDD red-phase commit (failing + tests, no implementation yet) can land. CI executes `script/cibuild`, which + runs the tests, so a red branch still cannot reach `next`. ## Design @@ -995,14 +990,12 @@ documents: before the implementation. Tests are the canonical API documentation and must be commented thoroughly. `main` and `next` are always green. -- **Required checks before every commit:** `make lint` must pass — that is - eslint plus the prettier check, and it builds the `lint` phase of the - `Dockerfile`, so it needs docker. The pre-commit hook enforces exactly that. - `make check` (which also runs the tests) must pass before merging into `next`. - `make fmt-check` is available for a host-side formatting check on its own, but - it is not a separate requirement: `make lint` already covers it, and running - both would check formatting twice. Never invoke eslint or prettier directly; - linting runs in the container only. +- **Required checks before every commit:** `make lint` and `make fmt-check` must + pass. `make lint` is eslint plus the prettier check, and it builds the `lint` + phase of the `Dockerfile`, so it needs docker. The pre-commit hook enforces + exactly that. `make check` (which also runs the tests) must pass before + merging into `next`. Never invoke eslint or prettier directly; linting runs in + the container only. - **Formatting:** prettier with 4-space indents and `proseWrap: always` for markdown. Use `make fmt` to format. Use `yarn` not `npm`. diff --git a/REPO_POLICIES.md b/REPO_POLICIES.md index 2256291..20382d1 100644 --- a/REPO_POLICIES.md +++ b/REPO_POLICIES.md @@ -1,6 +1,6 @@ --- title: Repository Policies -last_modified: 2026-09-08 +last_modified: 2026-10-04 --- This document covers repository structure, tooling, and workflow standards. Code @@ -104,10 +104,14 @@ style conventions are in separate documents: `lint` phase and a `test` phase, with the final stage depending on both so the image cannot be built unless they pass. For non-server repos the final stage brings up a development environment; for server repos it is the runtime image. - 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. + The gate phases and the build stage start from their pinned base images and + install what those images lack either inline, as the canonical Go `Dockerfile` + below does for `git`, or by running `script/bootstrap`, as the `prompts` + repo's own `Dockerfile` does for its yarn packages. The development + environment stage installs development prerequisites by running + `script/bootstrap` rather than duplicating its installs inline. A stage that + runs `script/bootstrap` COPYs `script/` and the dependency manifests + (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it. - **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is no separate lint file. `script/lint` and `script/test` each build one phase @@ -156,11 +160,14 @@ style conventions are in separate documents: not evidence that anything ran: a sub-second build reporting success is a cache hit, not a result. Never invalidate by pruning — `docker builder prune` and friends destroy a build cache shared with every other build on the host. + When a check is added or changed, prove it works by planting a defect it must + catch and watching the run fail on it, then revert the defect. A green run + alone shows neither that the check ran nor that it covers what it should. - **The gate phases are separate stages, and the build stage depends on both.** The lint phase is based on the `golangci/golangci-lint` image (pinned by hash), so lint failures surface in seconds rather than after a full compile, - and the test phase is based on the Go image. The canonical Go repo + and the test phase is based on the Debian Go image. The canonical Go repo `Dockerfile`: ```dockerfile @@ -173,8 +180,9 @@ style conventions are in separate documents: COPY . . RUN golangci-lint run --config .golangci.yml ./... - # Test phase - # golang:1.x-alpine, YYYY-MM-DD + # Test phase. -race needs cgo and so a C compiler, which the Debian Go + # image ships and the alpine one does not. + # golang:1.x, YYYY-MM-DD FROM golang@sha256:... AS test WORKDIR /src COPY go.mod go.sum ./ @@ -191,15 +199,29 @@ style conventions are in separate documents: FROM golang@sha256:... AS builder COPY --from=lint /src/go.sum /dev/null COPY --from=test /src/go.sum /dev/null + RUN apk add --no-cache git + # A tar-stream context keeps the sender's file owners, which git refuses. + RUN git config --system --add safe.directory /src WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . - ARG VERSION=dev - RUN CGO_ENABLED=0 go build -trimpath \ - -ldflags="-s -w -X main.Version=${VERSION}" \ - -o /app ./cmd/app/ + # The VERSION build arg when one is given, otherwise + # `git describe --tags --always` on the .git in the build context. With + # .git present, a version that is still empty, dev or unknown fails the + # build: git is missing or could not read the checkout. + ARG VERSION + RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \ + if [ -e .git ]; then \ + case "$VERSION" in ""|dev|unknown) \ + echo "version is '$VERSION' although .git is present" >&2; \ + exit 1 ;; \ + esac; \ + fi; \ + CGO_ENABLED=0 go build -trimpath \ + -ldflags="-s -w -X main.Version=${VERSION}" \ + -o /app ./cmd/app/ # Runtime stage, and the last one FROM alpine@sha256:... @@ -221,10 +243,41 @@ style conventions are in separate documents: (e.g. a web frontend compiled in a separate stage), the lint phase must create placeholder files so the embed directives resolve. Example: `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`. - - If the project requires CGO or system libraries for linting (e.g. - `vips-dev`), install them in the lint phase with `apk add`. - - `ARG VERSION=dev` is declared in the stage that compiles and supplied by - `script/docker` and `script/cibuild`; no stage may call `git describe`. + - If the project requires CGO or system libraries for linting, install them + in the lint phase. The `golangci/golangci-lint` image is Debian-based and + has no `apk`, so install with `apt-get` under the Debian package name + (`libvips-dev`, where alpine says `vips-dev`), and delete the package + lists in the same `RUN`, so the layer does not keep them: + + ```dockerfile + RUN apt-get update \ + && apt-get install -y --no-install-recommends libvips-dev \ + && rm -rf /var/lib/apt/lists/* + ``` + + - `.dockerignore` lets `.git` into the build context. It keeps out every git + `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the + repository's own, each submodule's under `.git/modules/`, and that of a + submodule keeping its own `.git` directory. `git describe` does not need + them, and each can hold a credential: a password in a remote URL, or the + token the CI checkout step stores there. A submodule whose name has a + `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole + git directory to `**/.git/modules/**/config`, and Go's version stamping + then fails the build: give it a name without that segment + (`git submodule add --name`). The stage that compiles has `git` (the + Debian Go image has it; an alpine one needs `apk add --no-cache git`) and + takes the version from the `VERSION` build argument when one is given, + otherwise from `git describe --tags --always`. That gives the tag on a + tagged commit; on a later commit, the tag, the number of commits since it + and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no + tag is reachable. The stage that compiles also marks its working directory + safe for git (`git config --system --add safe.directory /src`): a context + sent as a tar stream keeps the sender's file owners, and git refuses a + checkout owned by another user, so the version would come out empty. + `ARG VERSION` has no default, and the build fails if the context carries + `.git` and the version still comes out empty, `dev` or `unknown`. A plain + `docker build .` with no build arguments must succeed; a Dockerfile that + refuses an empty build argument drops that refusal and keeps the argument. - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that runs `script/cibuild` on push, and checks out the repo as its only other step. @@ -233,7 +286,12 @@ style conventions are in separate documents: carry the same guarantee, because its gate phases may come from the cache. The image build is uncached and so runs the gate phases a second time. That is the price of the rule above, and it is worth paying: the image that ships is built - from a run of its own gates rather than from a cache entry. + from a run of its own gates rather than from a cache entry. A separate + workflow limited to `main` by a `branches` list under `on: push` cannot be + checked by review: to try a change to it, add the feature branch to that list + and push, then remove the branch from the list again before merging. Keep any + job in it that publishes behind `if: github.ref_name == 'main'`, so the run + from the feature branch publishes nothing. - Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with @@ -286,17 +344,19 @@ style conventions are in separate documents: ``` `-count=1` is required on both invocations: it defeats Go's test _result_ - cache, so the target cannot report a pass it did not earn, and the rerun - reproduces a failure instead of replaying it. It leaves the build cache - alone, so it costs the runtime of the suite and no recompilation. + cache, so neither run can report a stored pass in place of running the + tests. It leaves the build cache alone, so it costs the runtime of the suite + and no recompilation. - Note that this is a second, independent cache, stacked below the Docker - layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26) - addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes; - it does not guarantee `go test` inside that step does any work, because the - `GOCACHE` baked into earlier image layers survives into the re-executed - step. They are two separate defects requiring two separate fixes, and a fix - for one must not be recorded as covering the other. + That cache is Go's own, separate from Docker's layer cache. Go stores a + passing result in its cache directory (`GOCACHE`), and when the same tests + run again on unchanged code it prints that result, marked `(cached)`, + without running them. That matters on a developer's machine, where this + target runs and the directory lasts from one run to the next. The `test` + phase of the `Dockerfile` needs no `-count=1`: its base image holds no + result for this repo's tests and nothing before its `go test` step runs a + test, so there is nothing to replay. `--no-cache` (above) is what makes that + step run on an unchanged tree. Python example: @@ -340,7 +400,7 @@ style conventions are in separate documents: — which is more dangerous than a short file with no secret patterns at all, because it reads as solved and stops anyone looking. Give every depth-independent pattern the `**/` prefix and leave only genuinely - root-anchored entries unprefixed: `.git`, and the repo's own host-built + root-anchored entries unprefixed: `.claude`, and the repo's own host-built binary, written `/myapp` and never `**/myapp`, which would also match `cmd/myapp/` and delete the package directory from the context. Matching is case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so @@ -365,12 +425,13 @@ style conventions are in separate documents: directory, so a repo running agents in subdirectories still ships `services/api/.claude/` and must add its own anchored entry there. -- **Excluding `.git` means `git describe` cannot run inside any build stage, and - it fails quietly there.** In a build stage there is no repository, so - `git describe` writes nothing to stdout, `-X main.Version=` comes out empty, - the binary reports no version at all, and the build still exits 0. Compute the - version on the host and thread it in as a build arg. `script/docker` and - `script/cibuild` do this, byte-identically across repos: +- **A plain `docker build .` of a clone stamps the version that + `git describe --tags --always` gives**, derived from the `.git` in the build + context as the canonical `Dockerfile` above shows. Without its failure check, + a missing `git` or an unreadable checkout would leave `-X main.Version=` empty + and the build would still exit 0. `script/docker` and `script/cibuild` pass + the version they compute on the host; it takes precedence. They do this + byte-identically across repos: ```sh # Own line: a failing command substitution inside an argument does not @@ -387,7 +448,7 @@ style conventions are in separate documents: fallback is applied — a live check that fires on a build from an export with no `.git` and on a repository with no commits yet. Do not fold it into the substitution as `|| echo unknown`, which makes the guard unreachable. The - Dockerfile's side is `ARG VERSION=dev` in the stage that compiles, declared + Dockerfile's side is `ARG VERSION` in the stage that compiles, declared there because `ARG` is stage-scoped; passing `VERSION` to a repo whose Dockerfile declares no such `ARG` is ignored and costs nothing, which is why the scripts stay byte-identical. One consequence for CI: the standard @@ -426,12 +487,18 @@ style conventions are in separate documents: `test-support` depguard rule, where a repo names its own test-support packages by full import path. A repo adds entries there and changes nothing else, and a re-vendor carries its entries forward. The canonical golangci-lint version is - v2.12.2 (released 2026-05-06), pinned as the digest of the lint phase's base + v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base image - (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`, - which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the - only pin, since no repo installs golangci-lint on the host: bumping the - version means changing it and nothing else. + (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`, + which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go` + directive must not name a newer Go minor version than the one golangci-lint + was built with, or golangci-lint refuses to lint it: this release lints + `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo + installs golangci-lint on the host. A repo sets the lint phase digest to the + one named here and re-vendors `.golangci.yml` in the same commit, whichever of + the two prompted the change: the canonical copy can name linters that an older + golangci-lint rejects, and a newer golangci-lint can add linters that + `default: all` switches on until the canonical copy disables them. - **`script/bootstrap` installs a pinned tool by comparing versions, never by testing presence.** An `if ! command -v ; then install; fi` guard tests @@ -455,6 +522,11 @@ style conventions are in separate documents: Keep it POSIX sh: no arrays, no `[[`, no `grep -P`. + A Go tool a repo needs on the host is installed with `go install` pinned to + a commit hash (`go install @`). It is never tracked as + a `go.mod` tool dependency or through a `tools.go` file, either of which + pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`. + - When pinning images or packages by hash, add a comment above the reference with the version and date (YYYY-MM-DD). @@ -567,10 +639,10 @@ style conventions are in separate documents: 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: + only project-level config files (`README.md`, `AGENTS.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; thin only: one `main.go` per binary whose body is a single call into `internal/` or `pkg/`, no project logic in @@ -601,3 +673,7 @@ style conventions are in separate documents: - Go: `go.mod`, `go.sum`, `.golangci.yml` - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore` - Python: `pyproject.toml` + +- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It + is never committed under a file or directory named after one agent tool, such + as `CLAUDE.md` or `.claude/`, and never split into separate memory files. diff --git a/TODO.md b/TODO.md index c8baf5c..59e3228 100644 --- a/TODO.md +++ b/TODO.md @@ -25,6 +25,14 @@ declares one. # Completed Steps +- 2026-10-06: The files this repository copies from `sneak/prompts` are copied + again from its commit `dd4027b` (issue 171). `.gitignore` and `.dockerignore` + keep out more secret files, and this repository's build artifacts follow the + copied content. `script/check` runs `script/fmt-check` again, `script/cibuild` + runs `script/bootstrap` and `script/check` before the image build, + `script/fmt` and `script/fmt-check` find the pinned yarn under nvm, and the + image's last stage marks `/app` safe for git. + - 2026-10-06: `quak backup` writes the account and album records `backup-metadata` writes (issue 166): `account.json` with the account's `email` and `userID`, and in each album's JSON its `ownerID`, `isShared`, diff --git a/script/check b/script/check index 1607369..92875f7 100755 --- a/script/check +++ b/script/check @@ -1,11 +1,8 @@ #!/bin/sh -# script/check: run all checks (test, lint). Our own extension to -# scripts-to-rule-them-all. Both are Docker phases. Must not modify any -# files. -# -# script/fmt-check is not called here, unlike the template: the lint -# phase already runs `prettier --check .`, so calling it would run -# prettier a second time over the same tree for the same verdict. +# script/check: run all checks (test, lint, fmt-check). Our own +# extension to scripts-to-rule-them-all. test and lint are Docker +# phases; fmt-check is native, because a formatter writes the working +# tree. Must not modify any files. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" @@ -13,6 +10,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" main() { "$SCRIPT_DIR/test" "$SCRIPT_DIR/lint" + "$SCRIPT_DIR/fmt-check" } main "$@" diff --git a/script/cibuild b/script/cibuild index 38fecf3..d8d3200 100755 --- a/script/cibuild +++ b/script/cibuild @@ -1,8 +1,7 @@ #!/bin/sh -# script/cibuild: run the CI build. The image's last stage depends on the -# lint and test phases, so this one build runs eslint, prettier and the -# suite once each and then compiles. Unlike the template it does not run -# script/check first, which would run lint and the tests a second time. +# script/cibuild: run the CI build. It bootstraps first: a CI runner +# checks out and runs this and nothing else, and script/fmt-check runs +# the formatter on the host, which a pristine checkout cannot do. # --no-cache for the same reason as script/docker: the gate phases the # final stage depends on are RUN steps, and a cached one is a check that # did not run. @@ -13,11 +12,12 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" + "$SCRIPT_DIR/bootstrap" + "$SCRIPT_DIR/check" # Own line: a failing command substitution inside an argument does # not trip `set -e`, so the inline form degrades silently to an - # empty constant. The version resolved here goes in as the VERSION - # build arg, which takes precedence over what the build would derive - # from the .git in its context. + # empty constant. The VERSION build argument takes precedence over + # the version a build stage derives from the .git in the context. version="$(git describe --tags --always --dirty 2>/dev/null || true)" [ -n "$version" ] || version="unknown" docker build --no-cache \ diff --git a/script/docker b/script/docker index 940f456..07b626c 100755 --- a/script/docker +++ b/script/docker @@ -12,9 +12,8 @@ main() { cd "$ROOT" # Own line: a failing command substitution inside an argument does # not trip `set -e`, so the inline form degrades silently to an - # empty constant. The version resolved here goes in as the VERSION - # build arg, which takes precedence over what the build would derive - # from the .git in its context. + # empty constant. The VERSION build argument takes precedence over + # the version a build stage derives from the .git in the context. version="$(git describe --tags --always --dirty 2>/dev/null || true)" [ -n "$version" ] || version="unknown" docker build --no-cache \ diff --git a/script/fmt b/script/fmt index 52825df..fe1b79a 100755 --- a/script/fmt +++ b/script/fmt @@ -4,9 +4,28 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +# Must match the pin in script/bootstrap. +NODE_VERSION="22.17.0" + +# script/bootstrap installs node and yarn under nvm and leaves neither +# on the PATH of the shell that called it, so resolve the pinned +# toolchain here the way bootstrap's own install step does. nvm is a +# bash script, hence the subshell. +run_yarn() { + if command -v yarn >/dev/null 2>&1; then + exec yarn "$@" + fi + if [ ! -s "$HOME/.nvm/nvm.sh" ]; then + echo "fmt: no yarn; run script/bootstrap first" >&2 + exit 1 + fi + exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null && + shift && exec yarn "$@"' bash "$NODE_VERSION" "$@" +} + main() { cd "$ROOT" - yarn run prettier --write . + run_yarn run prettier --write . } main "$@" diff --git a/script/fmt-check b/script/fmt-check index adfaff4..0e164bd 100755 --- a/script/fmt-check +++ b/script/fmt-check @@ -4,9 +4,28 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +# Must match the pin in script/bootstrap. +NODE_VERSION="22.17.0" + +# script/bootstrap installs node and yarn under nvm and leaves neither +# on the PATH of the shell that called it, so resolve the pinned +# toolchain here the way bootstrap's own install step does. nvm is a +# bash script, hence the subshell. +run_yarn() { + if command -v yarn >/dev/null 2>&1; then + exec yarn "$@" + fi + if [ ! -s "$HOME/.nvm/nvm.sh" ]; then + echo "fmt-check: no yarn; run script/bootstrap first" >&2 + exit 1 + fi + exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null && + shift && exec yarn "$@"' bash "$NODE_VERSION" "$@" +} + main() { cd "$ROOT" - yarn run prettier --check . + run_yarn run prettier --check . } main "$@" diff --git a/script/precommit b/script/precommit index e87c5c8..af98730 100755 --- a/script/precommit +++ b/script/precommit @@ -2,17 +2,17 @@ # script/precommit: run by the git pre-commit hook; fails the commit if # checks fail. Our own extension to scripts-to-rule-them-all. # -# Runs lint but deliberately NOT the tests, so the TDD red-phase commit -# (failing tests, no implementation yet) can land. CI runs -# script/cibuild, whose image build includes the test phase, and so -# catches any branch that ships red. The lint phase includes the -# prettier check, so a badly formatted tree still fails the commit. +# Runs lint and fmt-check but deliberately NOT the tests, so the TDD +# red-phase commit (failing tests, no implementation yet) can land. CI +# runs script/cibuild, which runs the tests, and so catches any branch +# that ships red. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" main() { "$SCRIPT_DIR/lint" + "$SCRIPT_DIR/fmt-check" } main "$@" diff --git a/test/packaging/build-context.test.ts b/test/packaging/build-context.test.ts index ea52581..8d9c103 100644 --- a/test/packaging/build-context.test.ts +++ b/test/packaging/build-context.test.ts @@ -29,18 +29,19 @@ const patterns = (name: string): string[] => const dockerignore = patterns(".dockerignore"); describe(".dockerignore", () => { - // Everything here is either generated, enormous, or secret. `.claude/` is - // the correctness one: see the header comment and issue #25. + // Everything here is either generated, enormous, or secret. `.claude` is + // the correctness one: see the header comment and issue #25. The leading + // `/` anchors an entry at the root of the context. it.each([ - ".claude/", - ".quak/", - "bin/quak", - "node_modules", - "coverage", - "dist", - ".vitest-cache/", - ".nyc_output/", - "*.tsbuildinfo", + ".claude", + "/.quak", + "/bin/quak", + "**/node_modules", + "/coverage", + "/dist", + "/.vitest-cache", + "/.nyc_output", + "/*.tsbuildinfo", ])("keeps %s out of the build context", (pattern) => { expect(dockerignore).toContain(pattern); }); @@ -57,7 +58,7 @@ describe(".dockerignore", () => { // The build stage is the final image, so a .git/config sent in would // ship the clone's remote URL and any credential in it. it("sends .git without its config", () => { - expect(dockerignore).toContain(".git/config"); + expect(dockerignore).toContain("**/.git/config"); }); // BuildKit lets a `Dockerfile.dockerignore` shadow the root one; such a