Skip to content
This repository was archived by the owner on Jun 26, 2026. It is now read-only.

Commit 3732f7c

Browse files
authored
Merge pull request #13 from cozystack/docs/claude-md
docs: add CLAUDE.md
2 parents f6ff3f2 + c90aa71 commit 3732f7c

1 file changed

Lines changed: 166 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# cozystack-ui
2+
3+
Cozystack Marketplace + Console — a **pure SPA that talks directly to the
4+
Kubernetes API**. No BFF, no backend, no codegen. UI entities are discovered
5+
at runtime from `ApplicationDefinition` CRDs in the cluster.
6+
7+
## Development model
8+
9+
This UI is **developed entirely by Claude**. There is no human author writing
10+
features in parallel. Every file in this repo was produced through a Claude
11+
session and every change should be reviewable as a small, self-contained PR.
12+
Implications:
13+
14+
- Keep modules small and obvious. The next Claude session has no tribal
15+
knowledge — only what's in code, tests, and this file.
16+
- Prefer convention over abstraction. Three similar widgets are better than a
17+
premature factory.
18+
- If you're tempted to write a comment explaining *what* the code does, rename
19+
things instead. Only comment the non-obvious *why* (constraints, k8s quirks,
20+
workarounds) — and keep it to one short line.
21+
- Don't leave half-finished scaffolding behind. If you start a refactor and
22+
bail, revert it.
23+
24+
## Stack
25+
26+
- **pnpm workspace** — `apps/console` is the SPA; `packages/{k8s-client,ui,types}` are workspace deps.
27+
- **React 19 + Vite 8 + TypeScript ~6.0** with `module: esnext`,
28+
`moduleResolution: bundler`, `verbatimModuleSyntax`, `allowImportingTsExtensions`,
29+
`erasableSyntaxOnly`, `noUnusedLocals`, `noUnusedParameters`.
30+
- **Tailwind 4** via `@tailwindcss/vite` + **Base UI** (`@base-ui/react`) for primitives.
31+
- **React Query** for caching; custom watch layer streams chunked JSON events.
32+
- **RJSF** (`@rjsf/core` + `validator-ajv8`) for application config forms.
33+
- **Vitest + jsdom + @testing-library/react** for tests.
34+
- **Monaco** for YAML view, **noVNC** for the VM console tab.
35+
36+
## Dev loop
37+
38+
```sh
39+
pnpm install
40+
kubectl proxy --port 8001 # required — terminates TLS, proxies /api + /apis
41+
pnpm dev # http://localhost:3001
42+
pnpm typecheck # tsc --noEmit across the workspace
43+
pnpm test # vitest run
44+
pnpm lint # eslint
45+
pnpm build # tsc check + vite build into apps/console/dist
46+
```
47+
48+
The Vite dev server proxies `/api`, `/apis`, and `/k8s` (VNC WebSocket prefix)
49+
to `kubectl proxy`. In production, nginx (see `Containerfile`) proxies the
50+
same paths to `kubernetes.default.svc` using the pod's service-account token.
51+
52+
## Code style
53+
54+
- **No semicolons.** Match the surrounding code — every file in the tree
55+
follows this. Don't reformat existing files.
56+
- **Always import with explicit `.ts` / `.tsx` extensions** — required by
57+
`allowImportingTsExtensions` and the way packages re-export.
58+
- **`import type { ... }` for type-only imports** — required by `verbatimModuleSyntax`.
59+
- **Path aliases**: `@/` → `apps/console/src/`, plus the workspace deps
60+
`@cozystack/{k8s-client,ui,types}`. Don't reach into `../../packages/...`.
61+
- **No `any`.** Use `unknown` and narrow, or a precise local interface.
62+
`as any` casts in older files are debt to pay down, not a pattern to extend.
63+
- **No new top-level deps without a reason in the PR description.** This is a
64+
static SPA that ships to every Cozystack cluster — bundle size matters.
65+
66+
## Architecture rules
67+
68+
1. **Talk to the Kubernetes API directly.** Use `@cozystack/k8s-client`
69+
(`useK8sList`, `useK8sGet`, `useK8sCreate`, `useK8sUpdate`, `useK8sDelete`).
70+
Don't add a backend, server route, or proxy of your own.
71+
2. **Discover, don't hardcode.** The marketplace, sidebar, detail pages, and
72+
forms are all driven from `ApplicationDefinition` resources
73+
(`cozystack.io/v1alpha1`). Adding a new application kind to Cozystack
74+
should require zero UI changes — if it doesn't, fix the generic path
75+
instead of adding a special case.
76+
3. **`useK8sList` already does watches.** It seeds with a LIST then upgrades
77+
to a chunked-encoding WATCH against the same `resourceVersion`. Don't
78+
poll. Don't add `refetchInterval`. If you need a one-shot, pass
79+
`{ watch: false }`.
80+
4. **Tenant scoping.** Most resources live in `tenant-<name>` namespaces.
81+
Pull the active tenant from `useTenantContext()` — never read the
82+
namespace from a URL param or guess it.
83+
5. **Auth.** In production the SPA sits behind oauth2-proxy. The client
84+
relies on cookies forwarded by nginx, and `/oauth2/userinfo` returns the
85+
logged-in user. There is no token handling in the SPA itself.
86+
87+
## Forms (RJSF) pipeline
88+
89+
Every application's configure form is built from
90+
`ApplicationDefinition.spec.application.openAPISchema` (a JSON-encoded OpenAPI
91+
schema). The pipeline in `apps/console/src/components/SchemaForm.tsx`:
92+
93+
1. `sanitizeSchema` strips Kubernetes-specific extensions
94+
(`x-kubernetes-int-or-string`, `x-kubernetes-preserve-unknown-fields`) and
95+
renames `"Chart Values"` → `"Parameters"`.
96+
2. `keysOrderToUiSchema` reads `spec.dashboard.keysOrder` and emits per-level
97+
`ui:order` arrays.
98+
3. A chain of `addXxxWidgets(schema, uiSchema)` walks the schema and binds
99+
widgets by **field name** convention:
100+
- `storageClass` → `StorageClassWidget`
101+
- `backupClassName` → `BackupClassWidget`
102+
- `disks[].name` → `VMDiskWidget`
103+
- object with `additionalProperties: <schema>` → `AdditionalPropertiesField`
104+
- credential-shaped fields (`password`, `*token`, `*accessKey`, …) →
105+
`SensitiveStringWidget` — see `lib/sensitive-fields.ts` and its tests for
106+
the exact matching rules.
107+
4. Defaults are emitted to the parent once per schema via `getDefaultFormState`
108+
so the first submit always carries a populated spec.
109+
110+
When you add a new widget binding:
111+
112+
- Add it to the chain in `SchemaForm.tsx` in a deterministic order.
113+
- Walk `properties` *and* `items` for arrays. Do **not** walk
114+
`oneOf`/`anyOf`/`allOf` unless a real chart needs it — there's a
115+
"pin broken behaviour" test that documents this gap intentionally.
116+
- Don't mutate the input `uiSchema`. Return a new object. There are tests
117+
asserting this.
118+
119+
## Project layout
120+
121+
```
122+
apps/console/
123+
src/
124+
App.tsx, main.tsx # entry + routing
125+
routes/ # one file per top-level page
126+
detail/ # ApplicationDetailPage + tabs (Overview, Workloads, …)
127+
components/ # page-level components, form widgets, command palette
128+
lib/ # app-definitions, tenant-context, sensitive-fields, …
129+
hooks/
130+
test/setup.ts # vitest + jest-dom + manual RTL cleanup
131+
packages/
132+
k8s-client/ # K8sClient (list/get/create/update/patch/delete/watch) + React Query hooks
133+
ui/ # AppShell, Sidebar, Header, Button, StatusBadge, Spinner, Dropdown, Section
134+
types/ # ApplicationDefinition, ApplicationInstance, Tenant, TenantNamespace, group/version constants
135+
Containerfile # multi-stage build → nginx-unprivileged on :8080
136+
.github/workflows/ # test.yaml (typecheck + vitest), build.yaml (multi-arch image to ghcr)
137+
```
138+
139+
## Testing
140+
141+
- Tests live next to the code they cover (`SensitiveStringWidget.test.tsx`,
142+
`sensitive-fields.test.ts`). Co-locate; don't centralise.
143+
- `apps/console/test/setup.ts` wires `@testing-library/jest-dom` and registers
144+
`afterEach(cleanup)` manually — vitest is **not** run with `globals: true`,
145+
so `expect`, `describe`, etc. must be imported explicitly.
146+
- When you fix a subtle widget bug, write the test first. The
147+
`addSensitiveStringWidgets` suite is the model: small focused cases, one
148+
invariant per `it`, and a "pin broken behaviour" group for known gaps.
149+
150+
## CI
151+
152+
`test.yaml` runs `pnpm typecheck` + `pnpm test` on every push and PR.
153+
`build.yaml` builds and pushes a multi-arch image to
154+
`ghcr.io/<repo>` on `main` and `v*` tags. Don't add other workflows without a
155+
clear reason — keep CI fast.
156+
157+
## What goes in a good PR here
158+
159+
- One feature or one fix per branch. Small enough that a human can review it
160+
in a few minutes without context.
161+
- A title that follows the conventional-commit style already in use
162+
(`feat(console): …`, `fix(forms): …`, `fix(external-ips): …`).
163+
- If you touched form logic, add or update tests.
164+
- If you added a new application kind to the sidebar/marketplace, double-check
165+
that the generic path handles it instead of special-casing.
166+
- Don't bundle drive-by reformatting with a behavioural change.

0 commit comments

Comments
 (0)