Cozystack Marketplace + Console — a pure SPA that talks directly to the
Kubernetes API. No BFF, no backend, no codegen. UI entities are discovered
at runtime from ApplicationDefinition CRDs in the cluster.
This UI is developed entirely by Claude. There is no human author writing features in parallel. Every file in this repo was produced through a Claude session and every change should be reviewable as a small, self-contained PR. Implications:
- Keep modules small and obvious. The next Claude session has no tribal knowledge — only what's in code, tests, and this file.
- Prefer convention over abstraction. Three similar widgets are better than a premature factory.
- If you're tempted to write a comment explaining what the code does, rename things instead. Only comment the non-obvious why (constraints, k8s quirks, workarounds) — and keep it to one short line.
- Don't leave half-finished scaffolding behind. If you start a refactor and bail, revert it.
- pnpm workspace —
apps/consoleis the SPA;packages/{k8s-client,ui,types}are workspace deps. - React 19 + Vite 8 + TypeScript ~6.0 with
module: esnext,moduleResolution: bundler,verbatimModuleSyntax,allowImportingTsExtensions,erasableSyntaxOnly,noUnusedLocals,noUnusedParameters. - Tailwind 4 via
@tailwindcss/vite+ Base UI (@base-ui/react) for primitives. - React Query for caching; custom watch layer streams chunked JSON events.
- RJSF (
@rjsf/core+validator-ajv8) for application config forms. - Vitest + jsdom + @testing-library/react for tests.
- Monaco for YAML view, noVNC for the VM console tab.
pnpm install
kubectl proxy --port 8001 # required — terminates TLS, proxies /api + /apis
pnpm dev # http://localhost:3001
pnpm typecheck # tsc --noEmit across the workspace
pnpm test # vitest run
pnpm lint # eslint
pnpm build # tsc check + vite build into apps/console/distThe Vite dev server proxies /api, /apis, and /k8s (VNC WebSocket prefix)
to kubectl proxy. In production, nginx (see Containerfile) proxies the
same paths to kubernetes.default.svc using the pod's service-account token.
- No semicolons. Match the surrounding code — every file in the tree follows this. Don't reformat existing files.
- Always import with explicit
.ts/.tsxextensions — required byallowImportingTsExtensionsand the way packages re-export. import type { ... }for type-only imports — required byverbatimModuleSyntax.- Path aliases:
@/→apps/console/src/, plus the workspace deps@cozystack/{k8s-client,ui,types}. Don't reach into../../packages/.... - No
any. Useunknownand narrow, or a precise local interface.as anycasts in older files are debt to pay down, not a pattern to extend. - No new top-level deps without a reason in the PR description. This is a static SPA that ships to every Cozystack cluster — bundle size matters.
- Talk to the Kubernetes API directly. Use
@cozystack/k8s-client(useK8sList,useK8sGet,useK8sCreate,useK8sUpdate,useK8sDelete). Don't add a backend, server route, or proxy of your own. - Discover, don't hardcode. The marketplace, sidebar, detail pages, and
forms are all driven from
ApplicationDefinitionresources (cozystack.io/v1alpha1). Adding a new application kind to Cozystack should require zero UI changes — if it doesn't, fix the generic path instead of adding a special case. useK8sListalready does watches. It seeds with a LIST then upgrades to a chunked-encoding WATCH against the sameresourceVersion. Don't poll. Don't addrefetchInterval. If you need a one-shot, pass{ watch: false }.- Tenant scoping. Most resources live in
tenant-<name>namespaces. Pull the active tenant fromuseTenantContext()— never read the namespace from a URL param or guess it. - Auth. In production the SPA sits behind oauth2-proxy. The client
relies on cookies forwarded by nginx, and
/oauth2/userinforeturns the logged-in user. There is no token handling in the SPA itself.
Every application's configure form is built from
ApplicationDefinition.spec.application.openAPISchema (a JSON-encoded OpenAPI
schema). The pipeline in apps/console/src/components/SchemaForm.tsx:
sanitizeSchemastrips Kubernetes-specific extensions (x-kubernetes-int-or-string,x-kubernetes-preserve-unknown-fields) and renames"Chart Values"→"Parameters".keysOrderToUiSchemareadsspec.dashboard.keysOrderand emits per-levelui:orderarrays.- A chain of
addXxxWidgets(schema, uiSchema)walks the schema and binds widgets:- any field carrying the
x-cozystack-optionsschema keyword →DynamicOptionsWidget, a runtime dropdown populated from the cluster'sOptionresource (core.cozystack.io) keyed by the keyword'ssource;addDynamicOptionWidgets(lib/dynamic-options.ts) recurses intoproperties, arrayitemsandadditionalProperties, and replaces the former field-name-boundStorageClassWidget/BackupClassWidget/VMDiskWidget. - object with
additionalProperties: <schema>→AdditionalPropertiesField - credential-shaped fields (
password,*token,*accessKey, …) →SensitiveStringWidget— seelib/sensitive-fields.tsand its tests for the exact matching rules.
- any field carrying the
- Defaults are emitted to the parent once per schema via
getDefaultFormStateso the first submit always carries a populated spec.
When you add a new widget binding:
- Add it to the chain in
SchemaForm.tsxin a deterministic order. - Walk
propertiesanditemsfor arrays. Do not walkoneOf/anyOf/allOfunless a real chart needs it — there's a "pin broken behaviour" test that documents this gap intentionally. - Don't mutate the input
uiSchema. Return a new object. There are tests asserting this.
apps/console/
src/
App.tsx, main.tsx # entry + routing
routes/ # one file per top-level page
detail/ # ApplicationDetailPage + tabs (Overview, Workloads, …)
components/ # page-level components, form widgets, command palette
lib/ # app-definitions, tenant-context, sensitive-fields, …
hooks/
test/setup.ts # vitest + jest-dom + manual RTL cleanup
packages/
k8s-client/ # K8sClient (list/get/create/update/patch/delete/watch) + React Query hooks
ui/ # AppShell, Sidebar, Header, Button, StatusBadge, Spinner, Dropdown, Section
types/ # ApplicationDefinition, ApplicationInstance, Tenant, TenantNamespace, group/version constants
Containerfile # multi-stage build → nginx-unprivileged on :8080
.github/workflows/ # test.yaml (typecheck + vitest), build.yaml (multi-arch image to ghcr)
- Tests live next to the code they cover (
SensitiveStringWidget.test.tsx,sensitive-fields.test.ts). Co-locate; don't centralise. apps/console/test/setup.tswires@testing-library/jest-domand registersafterEach(cleanup)manually — vitest is not run withglobals: true, soexpect,describe, etc. must be imported explicitly.- When you fix a subtle widget bug, write the test first. The
addSensitiveStringWidgetssuite is the model: small focused cases, one invariant perit, and a "pin broken behaviour" group for known gaps.
test.yaml runs pnpm typecheck + pnpm test on every push and PR.
build.yaml builds and pushes a multi-arch image to
ghcr.io/<repo> on main and v* tags. Don't add other workflows without a
clear reason — keep CI fast.
- One feature or one fix per branch. Small enough that a human can review it in a few minutes without context.
- A title that follows the conventional-commit style already in use
(
feat(console): …,fix(forms): …,fix(external-ips): …). - If you touched form logic, add or update tests.
- If you added a new application kind to the sidebar/marketplace, double-check that the generic path handles it instead of special-casing.
- Don't bundle drive-by reformatting with a behavioural change.