docs: add CLAUDE.md#13
Conversation
Add the authoritative dev guide for this Claude-driven SPA: stack, dev loop, code style, architecture rules (direct-to-Kubernetes, dynamic discovery from ApplicationDefinitions, watch via useK8sList, tenant scoping, oauth2-proxy), the RJSF form pipeline, project layout, testing, CI, and PR conventions. Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
📝 WalkthroughWalkthroughAdded ChangesDevelopment Conventions and Architecture Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces CLAUDE.md, a comprehensive development guide for the cozystack-ui project that outlines the architecture, tech stack, and coding standards for AI-driven development. Review feedback identifies several documentation inaccuracies, including non-existent versions for Vite and TypeScript, inconsistencies in the form widget binding instructions compared to the current implementation, and a mismatch regarding missing patch support in the Kubernetes client hooks.
| ## Stack | ||
|
|
||
| - **pnpm workspace** — `apps/console` is the SPA; `packages/{k8s-client,ui,types}` are workspace deps. | ||
| - **React 19 + Vite 8 + TypeScript ~6.0** with `module: esnext`, |
There was a problem hiding this comment.
The versions for Vite (8) and TypeScript (6.0) are incorrect as these versions have not been released. This may cause the LLM to assume the availability of non-existent features or APIs. Consider updating these to the actual versions used in the project (e.g., Vite 6 and TypeScript 5.x).
| When you add a new widget binding: | ||
|
|
||
| - Add it to the chain in `SchemaForm.tsx` in a deterministic order. | ||
| - Walk `properties` *and* `items` for arrays. Do **not** walk |
There was a problem hiding this comment.
The guide states that widget binding logic should walk both properties and items for arrays. However, several helper functions in apps/console/src/components/SchemaForm.tsx (such as addStorageClassWidgets, addBackupClassWidgets, and addAdditionalPropertiesWidgets) currently only walk properties. This inconsistency should be resolved to ensure the guide accurately reflects the required implementation pattern.
| hooks/ | ||
| test/setup.ts # vitest + jest-dom + manual RTL cleanup | ||
| packages/ | ||
| k8s-client/ # K8sClient (list/get/create/update/patch/delete/watch) + React Query hooks |
There was a problem hiding this comment.
The description for packages/k8s-client/ mentions patch support, but the useK8sPatch hook is missing from packages/k8s-client/src/hooks.ts. If patching is a supported operation, the corresponding hook should be implemented or the documentation updated to reflect the available hooks.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 121-137: Add a language token to the fenced code block in
CLAUDE.md (the multi-line listing block that begins with ``` and shows the
apps/console/ structure) so markdownlint rule MD040 stops flagging it; change
the opening fence from ``` to ```text (or another appropriate language) and
leave the closing ``` unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ``` | ||
| 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) | ||
| ``` |
There was a problem hiding this comment.
Add a language to the fenced code block to satisfy markdownlint.
Line 121 opens a fenced block without a language, which triggers MD040. Add a language token (for example text) to avoid lint noise/failures.
Proposed fix
-```
+```text
apps/console/
src/
App.tsx, main.tsx # entry + routing
@@
.github/workflows/ # test.yaml (typecheck + vitest), build.yaml (multi-arch image to ghcr)
-```
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| 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) | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 121-121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 121 - 137, Add a language token to the fenced code
block in CLAUDE.md (the multi-line listing block that begins with ``` and shows
the apps/console/ structure) so markdownlint rule MD040 stops flagging it;
change the opening fence from ``` to ```text (or another appropriate language)
and leave the closing ``` unchanged.
Aleksei Sviridkin (lexfrei)
left a comment
Aleksei Sviridkin (lexfrei)
left a comment
There was a problem hiding this comment.
LGTM — docs-only PR adding a CLAUDE.md that's accurate against the current codebase. Walked through every concrete claim and verified it. One minor wording suggestion and a markdownlint nit are below; not blockers.
Verified against current code:
- pnpm workspace + workspace layout matches (
apps/console,packages/{k8s-client,types,ui}). - TS compiler options exactly match (
tsconfig.base.json:module: esnext,moduleResolution: bundler,verbatimModuleSyntax: true,allowImportingTsExtensions: true,erasableSyntaxOnly: true,noUnusedLocals: true,noUnusedParameters: true). - Path aliases match
tsconfig.json:@/,@cozystack/{types,ui,k8s-client}. - Every widget the doc names exists as a separate file:
apps/console/src/components/{StorageClassWidget,BackupClassWidget,VMDiskWidget,AdditionalPropertiesField,SensitiveStringWidget,SchemaForm}.tsx. useK8sList/useK8sGet/useK8sCreate/useK8sUpdate/useK8sDeleteall exported frompackages/k8s-client/src/hooks.ts.K8sClientclass inclient.tshaslist/get/create/update/patch/delete/watchmethods — matches the doc.useTenantContextexported fromapps/console/src/lib/tenant-context.tsx:95./oauth2/userinfois referenced inapps/console/src/lib/config.ts:35.apps/console/test/setup.tsmatches the description verbatim — explicitafterEach(cleanup)because vitest is not inglobals: truemode.Containerfileproxies/api,/apis,/k8stohttps://kubernetes.default.svc:443; Vite dev server (apps/console/vite.config.ts) proxies the same paths tohttp://localhost:8001. Both match the doc.- CI workflows are exactly
test.yaml(typecheck + vitest) andbuild.yaml. No others. - The no-semicolons rule is followed by every file I sampled (
App.tsx,BackupClassWidget.tsx, …).BackupClassWidget.tsxopens withimport type { WidgetProps }— matches theverbatimModuleSyntaxclaim.
Bot findings dismissed with evidence:
-
Gemini P1 — "Vite 8 and TypeScript 6.0 versions have not been released": false positive. Both are actually installed (
node_modules/.pnpmshowstypescript@6.0.3andvite@8.0.8), CI runs on a frozen lockfile, theTestjob is green. Gemini's training data predates these releases. -
Gemini P3 — "
useK8sPatchhook missing": false positive based on a misread. The doc says "K8sClient(list/get/create/update/patch/delete/watch) + React Query hooks" —K8sClient.patchIS implemented inpackages/k8s-client/src/client.ts. The hook list isn't enumerated in the doc, and the absence of auseK8sPatchwrapper doesn't contradict anything written.
One real minor wording suggestion:
- Gemini P2 — "Walk
propertiesanditemsfor arrays" (line 113) is currently only true foraddSensitiveStringWidgets(apps/console/src/lib/sensitive-fields.ts:91-93walks both subtrees and has the "pin broken behaviour" test for theoneOf/anyOf/allOfgap).addStorageClassWidgetsandaddBackupClassWidgetsinSchemaForm.tsxonly walkproperties. The doc reads as a description of current behavior; it's actually an instruction for future widgets to follow theaddSensitiveStringWidgetsshape. Worth a one-line clarification, e.g. "Walkpropertiesanditemsfor arrays — seeaddSensitiveStringWidgetsas the reference shape; the olderaddStorageClassWidgets/addBackupClassWidgetsonly walkpropertiesand should be aligned when next touched." Not a blocker; this is doc framing.
CodeRabbit nit:
- Fenced code block at line 121 has no language tag — triggers markdownlint MD040. Easy fix:
```texton line 121. Markdownlint isn't wired in CI for this repo (onlytest.yaml+build.yaml), so this is hygiene only.
None of the four findings rise to a blocker. The docs are accurate against the artifact they describe, which is what a CLAUDE.md is for.
2 participants
Summary
.ts/.tsximport extensions,import type, path aliases), architecture rules (direct-to-Kubernetes, dynamic discovery fromApplicationDefinition, watch viauseK8sList, tenant scoping, oauth2-proxy), the RJSF form pipeline inSchemaForm.tsx, project layout, testing setup, CI, and PR conventions.Test plan
Summary by CodeRabbit
Note: This is an internal documentation update with no end-user-facing changes.