docs: add CLAUDE.md development standards, bump v0.6.1

Adds CLAUDE.md which Claude Code reads automatically before every
session. Covers version bumping, changelog format, commit conventions,
file size limits, section/page architecture, and API standards.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
This commit is contained in:
NixReaper
2026-04-11 18:13:05 -05:00
co-authored by Claude Sonnet 4.6
parent 6dba99d164
commit 5c98ac0ee6
3 changed files with 173 additions and 1 deletions
+7
View File
@@ -6,6 +6,13 @@ Pre-1.0 versions treat MINOR as feature releases and PATCH as bug fixes.
---
## [0.6.1] — 2026-04-11
### Changes
- **`CLAUDE.md` added** — development standards file auto-read by Claude Code before every session. Documents version numbering rules, changelog format, commit message conventions, file size limits, section/page architecture patterns, API conventions, and project structure.
---
## [0.6.0] — 2026-04-11
### Features
+165
View File
@@ -0,0 +1,165 @@
# NixPanel Development Standards
This file is read automatically by Claude Code before every session.
All rules below are **mandatory** — follow them without being asked.
---
## 1. Version Numbering
Versioning follows [Semantic Versioning](https://semver.org/). Pre-1.0 rules:
| Change type | Bump | Example |
|---|---|---|
| New feature, new page, new section | **MINOR** | 0.5.1 → 0.6.0 |
| Bug fix, refactor, chore, docs | **PATCH** | 0.5.1 → 0.5.2 |
| Breaking API/schema change | **MINOR** | 0.5.x → 0.6.0 |
**Always** bump the version in `package.json` before committing any user-visible change.
---
## 2. Changelog
File: `CHANGELOG.md` at the repo root.
### Format
```markdown
## [X.Y.Z] — YYYY-MM-DD
### Features ← new functionality
### Changes ← non-breaking behaviour changes / refactors
### Bug Fixes ← defect corrections
### Refactors ← internal restructuring with no behaviour change
```
### Rules
- Add a new entry **at the top** of the file (below the header block) for every commit.
- One entry per version — if multiple changes share a version, group them under the same header.
- Bullet points must be descriptive enough that a developer can understand what changed and why without reading the diff.
- Use bold for the affected component/file: `- **BasicSetup.tsx** — description`.
- Today's date format: `YYYY-MM-DD`.
---
## 3. Commit Messages
Format: `type(scope): short imperative summary`
| Type | When to use |
|---|---|
| `feat` | New feature or page |
| `fix` | Bug fix |
| `refactor` | Code restructuring, no behaviour change |
| `chore` | Version bump, changelog, config, tooling |
| `docs` | Documentation only |
Rules:
- Summary line ≤ 72 characters.
- Always include `Co-Authored-By: Claude Sonnet 4.6 <[email protected]>` trailer.
- Use a multiline HEREDOC — never single-line for complex messages.
### Workflow for every change
1. Make code changes.
2. Bump version in `package.json`.
3. Add entry to `CHANGELOG.md`.
4. Stage all changed files including `package.json` and `CHANGELOG.md`.
5. Commit everything together in **one commit**.
6. Push to `origin main`.
> Do **not** make a separate `chore: bump version` commit — version + changelog belong in the same commit as the code change.
---
## 4. File Size Limit
**No source file should exceed 300 lines.**
When a file approaches this limit, split it by responsibility:
- React pages → extract sub-components into a `pages/<section>/` subfolder.
- Fastify route files → split into sub-plugins under `routes/<section>/` with an `index.ts` registering them.
- Shared UI primitives → `components/` folder.
---
## 5. Page / Section Architecture
### Frontend
Each nav category in the sidebar maps to a **section folder**:
```
pages/<section-name>/
index.tsx ← card-grid landing page (always create this first)
ToolName.tsx ← one file per tool/feature
```
Unimplemented tools use `<ComingSoon title="..." description="..." />` from `components/ComingSoon.tsx`.
Section landing pages use `<SectionCard>` from `components/SectionCard.tsx`.
### Backend
Route files live under `routes/nixserver/<section>/`:
```
routes/nixserver/<section>/
index.ts ← registers sub-plugins, no route logic here
list.ts ← read-only GET routes
create.ts ← POST / creation route
modify.ts ← PUT / PATCH routes
status.ts ← suspend / unsuspend / delete / bulk
```
---
## 6. Project Structure (key paths)
```
nixpanel-server/
package.json ← root version number lives here
CHANGELOG.md ← always update before committing
CLAUDE.md ← this file
nixserver/src/
components/
navData.ts ← NAV array + NavCategory/NavItem types
Sidebar.tsx ← sidebar UI
Layout.tsx ← thin shell (topbar + Outlet)
SectionCard.tsx ← reusable section card
ComingSoon.tsx ← placeholder for unimplemented tools
pages/
server-configuration/ ← example of section folder pattern
index.tsx
BasicSetup.tsx
ChangeRoot.tsx
...
server/src/
routes/nixserver/
accounts/ ← example of split route folder
index.ts
list.ts
create.ts
modify.ts
status.ts
```
---
## 7. API Conventions
- All responses: `{ success: true, data: ... }` or `{ success: false, error: "..." }`.
- All admin routes use `preHandler: [requireAdmin]` or `preHandler: [requireAdminOrReseller]`.
- Settings stored as key-value pairs in the `Setting` model (`key String @id`, `value String`).
- New settings keys use UPPERCASE (matching WHM convention): `CONTACTEMAIL`, `TTL`, etc.
---
## 8. Git Remote
```
origin https://github.com/NixReaper/nixpanel-server.git (fetch/push)
branch main
```
Always push to `origin main` after committing.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "nixpanel-server",
"version": "0.6.0",
"version": "0.6.1",
"private": true,
"workspaces": [
"server",