|
| 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: |
| 100 | + - any field carrying the `x-cozystack-options` schema keyword → `DynamicOptionsWidget`, a runtime dropdown populated from the cluster's `Option` resource (`core.cozystack.io`) keyed by the keyword's `source`; `addDynamicOptionWidgets` (`lib/dynamic-options.ts`) recurses into `properties`, array `items` and `additionalProperties`, and replaces the former field-name-bound `StorageClassWidget` / `BackupClassWidget` / `VMDiskWidget`. |
| 101 | + - object with `additionalProperties: <schema>` → `AdditionalPropertiesField` |
| 102 | + - credential-shaped fields (`password`, `*token`, `*accessKey`, …) → |
| 103 | + `SensitiveStringWidget` — see `lib/sensitive-fields.ts` and its tests for |
| 104 | + the exact matching rules. |
| 105 | +4. Defaults are emitted to the parent once per schema via `getDefaultFormState` |
| 106 | + so the first submit always carries a populated spec. |
| 107 | + |
| 108 | +When you add a new widget binding: |
| 109 | + |
| 110 | +- Add it to the chain in `SchemaForm.tsx` in a deterministic order. |
| 111 | +- Walk `properties` *and* `items` for arrays. Do **not** walk |
| 112 | + `oneOf`/`anyOf`/`allOf` unless a real chart needs it — there's a |
| 113 | + "pin broken behaviour" test that documents this gap intentionally. |
| 114 | +- Don't mutate the input `uiSchema`. Return a new object. There are tests |
| 115 | + asserting this. |
| 116 | + |
| 117 | +## Project layout |
| 118 | + |
| 119 | +``` |
| 120 | +apps/console/ |
| 121 | + src/ |
| 122 | + App.tsx, main.tsx # entry + routing |
| 123 | + routes/ # one file per top-level page |
| 124 | + detail/ # ApplicationDetailPage + tabs (Overview, Workloads, …) |
| 125 | + components/ # page-level components, form widgets, command palette |
| 126 | + lib/ # app-definitions, tenant-context, sensitive-fields, … |
| 127 | + hooks/ |
| 128 | + test/setup.ts # vitest + jest-dom + manual RTL cleanup |
| 129 | +packages/ |
| 130 | + k8s-client/ # K8sClient (list/get/create/update/patch/delete/watch) + React Query hooks |
| 131 | + ui/ # AppShell, Sidebar, Header, Button, StatusBadge, Spinner, Dropdown, Section |
| 132 | + types/ # ApplicationDefinition, ApplicationInstance, Tenant, TenantNamespace, group/version constants |
| 133 | +Containerfile # multi-stage build → nginx-unprivileged on :8080 |
| 134 | +.github/workflows/ # test.yaml (typecheck + vitest), build.yaml (multi-arch image to ghcr) |
| 135 | +``` |
| 136 | + |
| 137 | +## Testing |
| 138 | + |
| 139 | +- Tests live next to the code they cover (`SensitiveStringWidget.test.tsx`, |
| 140 | + `sensitive-fields.test.ts`). Co-locate; don't centralise. |
| 141 | +- `apps/console/test/setup.ts` wires `@testing-library/jest-dom` and registers |
| 142 | + `afterEach(cleanup)` manually — vitest is **not** run with `globals: true`, |
| 143 | + so `expect`, `describe`, etc. must be imported explicitly. |
| 144 | +- When you fix a subtle widget bug, write the test first. The |
| 145 | + `addSensitiveStringWidgets` suite is the model: small focused cases, one |
| 146 | + invariant per `it`, and a "pin broken behaviour" group for known gaps. |
| 147 | + |
| 148 | +## CI |
| 149 | + |
| 150 | +`test.yaml` runs `pnpm typecheck` + `pnpm test` on every push and PR. |
| 151 | +`build.yaml` builds and pushes a multi-arch image to |
| 152 | +`ghcr.io/<repo>` on `main` and `v*` tags. Don't add other workflows without a |
| 153 | +clear reason — keep CI fast. |
| 154 | + |
| 155 | +## What goes in a good PR here |
| 156 | + |
| 157 | +- One feature or one fix per branch. Small enough that a human can review it |
| 158 | + in a few minutes without context. |
| 159 | +- A title that follows the conventional-commit style already in use |
| 160 | + (`feat(console): …`, `fix(forms): …`, `fix(external-ips): …`). |
| 161 | +- If you touched form logic, add or update tests. |
| 162 | +- If you added a new application kind to the sidebar/marketplace, double-check |
| 163 | + that the generic path handles it instead of special-casing. |
| 164 | +- Don't bundle drive-by reformatting with a behavioural change. |
0 commit comments