docs: cut CLAUDE.md to rules-only (179 → 74 lines)
CLAUDE.md now carries only what must be known *before* opening a file: hard rules, gotchas, and an entry-point table. Everything descriptive moved to the doc that lives next to the code. Moved out: - stack versions, plugin roles, asset pipeline, nav shape, user/ repo tracking rules → docs/reference/architecture.md - Playwright layout, config facts, auth-setup project, test account → docs/reference/testing.md (new) - folder map, full make command list (build/test/demo/worktree targets that only existed in CLAUDE.md) → README.md - dev/prod Twig settings table → already in docs/guides/deploy-cycle.md Fixed while verifying, all of them descriptions that had drifted: - demo fixtures were listed as italy-2026-demo + no-photos-demo; the actual folders are italy-2025 + italy-2026-demo - the map engine was cited at js/src/maplibre-utils.js; it is js/maplibre-utils.js, a hand-authored file beside the bundles - the build-output list omitted fonts/ and the generated templates/partials/weather-icons.html.twig, and did not flag that js/maplibre-utils.js and js/nav.js are sources living in js/ - README called user/ a "standalone git repo" (it is a submodule) - docs/README.md linked to a non-existent working/production-todo.md - git-sync-notes.md pointed at "CLAUDE.md §1", a section number that no longer exists Net: ~17.1k → ~8.5k chars of always-loaded context. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+2
-1
@@ -10,12 +10,13 @@
|
||||
|
||||
**Checking project status?** → [`working/`](working/)
|
||||
- [Backlog](working/backlog.md)
|
||||
- [Production todo](working/production-todo.md)
|
||||
- [Bugs and fixes](working/bugs-and-fixes.md)
|
||||
- [QA results](working/qa/results.md)
|
||||
|
||||
**Design or architecture decisions?** → [`reference/`](reference/)
|
||||
- [Design system](reference/design-system.md)
|
||||
- [Architecture overview](reference/architecture.md)
|
||||
- [Testing](reference/testing.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -66,6 +66,23 @@ Three categories, by how each plugin is installed and maintained:
|
||||
|
||||
---
|
||||
|
||||
## Asset pipeline
|
||||
|
||||
`make build-assets` runs the theme's `npm run build` (esbuild) in a throwaway `node:20-alpine` container, as the host uid so outputs land in the tracked theme tree owned by you rather than root.
|
||||
|
||||
| Source | → Output |
|
||||
|---|---|
|
||||
| `js/src/main.js` | `js/main.js` + `css-compiled/main.css` + `fonts/` (font files via the `woff2` loader) |
|
||||
| `js/src/map.js` | `js/map.js` + `css-compiled/map.css` — bundles `maplibre-gl`, `@mapbox/togeojson`, and `js/maplibre-utils.js` |
|
||||
| `js/src/feed-actions.js` | `js/feed-actions.js` |
|
||||
| `js/src/trip-publish.js` | `js/trip-publish.js` |
|
||||
| `js/src/post-form.js` | `js/post/` (ESM + code splitting) + `css-compiled/post-form.css` |
|
||||
| `scripts/gen-weather-icons.js` | `templates/partials/weather-icons.html.twig` (Lucide SVGs inlined into a Twig map) |
|
||||
|
||||
**The trap:** `js/` holds both bundles *and* hand-authored sources. `js/maplibre-utils.js` (the `MapUtils` map engine, a plain IIFE imported by `js/src/map.js`) and `js/nav.js` are sources despite sitting beside the minified bundles. `css/style.css` and `css/tokens.css` are hand-authored too — only `css-compiled/` is generated.
|
||||
|
||||
---
|
||||
|
||||
## Template hierarchy
|
||||
|
||||
All page templates extend `base.html.twig`:
|
||||
@@ -83,6 +100,8 @@ templates/
|
||||
|
||||
The standalone `dailies.html.twig`, `map.html.twig`, `stats.html.twig` and `stories.html.twig` view templates were **removed** in the 2026-07-04 standalone-page cleanup — the trip page (`trip.html.twig`) consolidated the feed, inline map, and inline stats.
|
||||
|
||||
Site nav (in `base.html.twig`) is deliberately minimal — **Home + Past Trips only**. It does not link to trip sub-sections, because those standalone views no longer exist.
|
||||
|
||||
Partials live in `templates/partials/` (plus macros in `templates/macros/`). Key partials: `base.html.twig` (site shell extended by all page templates), `entry-map.html.twig` (shared map column + `initEntryMap` call, used by trip + home), `trip-feed-col.html.twig` (feed column chrome, shared by trip + home), `home-predeparture.html.twig`, `entry-journal.html.twig` / `entry-story.html.twig` (feed cards), `trip-publish-toggle.html.twig`, and `weather-icons.html.twig`.
|
||||
|
||||
### Shared partial contracts
|
||||
@@ -205,3 +224,7 @@ Rendered as route polyline on map
|
||||
| `user/plugins/api/api.yaml` | `session_enabled: true` for GPX manager auth |
|
||||
| `user/themes/intotheeast/css/tokens.css` | Design tokens (colors, fonts, spacing) |
|
||||
| `CLAUDE.md` | Project rules and always-loaded context for Claude |
|
||||
|
||||
### What the `user/` repo tracks
|
||||
|
||||
Only `pages/`, `config/`, `accounts/`, and `themes/` are versioned in the content repo. `plugins/` and `data/` are ignored — **except** the three custom plugins, un-ignored explicitly in `user/.gitignore`. Also ignored: the test accounts, the demo-trip pages, secrets (`config/plugins/git-sync.yaml`, `config/security.yaml`, `api-private.php`), and the whole `env/` override tree. Read `user/.gitignore` for the authoritative list.
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# Testing
|
||||
|
||||
Every suite drives the **live site over HTTP**, so the dev server must be running (`make start`) before any of them.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Scope |
|
||||
|---|---|
|
||||
| `make test` | Everything: `test-config` → `test-post` → `test-ui` |
|
||||
| `make test-config` | Form/config sanity via `scripts/test-form-config.sh` |
|
||||
| `make test-post` | End-to-end post submission via `scripts/test-post.sh` |
|
||||
| `make test-ui` | Playwright suite (`npx playwright test`) |
|
||||
| `make test-account` | Creates the `testrunner` admin if absent (a dependency of `test-post` and `test-ui`) |
|
||||
|
||||
Focused runs bypass `make`:
|
||||
|
||||
```bash
|
||||
npx playwright test tests/ui/maps # one suite
|
||||
npx playwright test tests/ui/maps --headed # watch it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
playwright.config.js ← config (testDir: ./tests/ui)
|
||||
tests/
|
||||
├─ global-setup.js ← runs once before all projects
|
||||
├─ global-teardown.js ← runs once after
|
||||
├─ fixtures/
|
||||
└─ ui/
|
||||
├─ helpers.js ← shared helpers; import from here rather than re-rolling
|
||||
├─ auth/ ← includes auth.setup.js (see below)
|
||||
├─ a11y/ dailies/ gpx/ home/
|
||||
├─ maps/ nav/ post/ stories/ trip/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Config facts
|
||||
|
||||
| Setting | Value | Why it matters |
|
||||
|---|---|---|
|
||||
| `baseURL` | `process.env.GRAV_BASE_URL \|\| 'http://localhost:8081'` | Set `GRAV_BASE_URL` to test a worktree's isolated server on `8090+` |
|
||||
| `retries` | `0` | A failing test is a real failure, not flake — do not paper over it with retries |
|
||||
| `timeout` | `30_000` | Per test |
|
||||
| `screenshot` | `only-on-failure` | Video off; artifacts stay small |
|
||||
| `reporter` | `line` | |
|
||||
|
||||
### Auth is a dependency project
|
||||
|
||||
Two Playwright projects, in order:
|
||||
|
||||
1. **`setup`** — matches `auth.setup.js`, logs in once, writes `tests/.auth/user.json`.
|
||||
2. **`chromium`** — `dependencies: ['setup']`, consumes that file as `storageState`.
|
||||
|
||||
So every test in `chromium` starts already authenticated. **Never add a per-test login** — it duplicates the setup project and slows the suite.
|
||||
|
||||
### The test account
|
||||
|
||||
`make test-account` creates a `testrunner` admin (via `bin/plugin login new-user`, admin type `both`) inside the container if `user/accounts/testrunner.yaml` is missing. It is git-ignored.
|
||||
|
||||
- Never commit it.
|
||||
- Keep the password free of shell/Make/URL-special characters — it is interpolated by the Makefile, `scripts/test-post.sh`, and the Playwright setup, and a special character breaks at least one of them.
|
||||
@@ -3,7 +3,8 @@
|
||||
## ⚠️ Config lives in the ENVIRONMENT tree, not `user/config/` (IMPORTANT)
|
||||
|
||||
Prod has a per-environment override directory `user/env/<hostname>/config/`
|
||||
(created for Twig prod-mode — see CLAUDE.md §1). **A crucial Grav side effect:
|
||||
(created for Twig prod-mode — see [`../guides/deploy-cycle.md`](../guides/deploy-cycle.md) →
|
||||
"The env override tree"). **A crucial Grav side effect:
|
||||
once that env dir exists, the Admin panel saves ALL config changes — system and
|
||||
plugin — into the active environment's config tree**, not `user/config/`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user