chore: update .gitignore, add docs site, plan docs
This commit is contained in:
datadunia
@@ -0,0 +1,220 @@
|
||||
# Node Config Lifecycle Hooks & Documentation Infrastructure
|
||||
|
||||
## TL;DR
|
||||
> **Quick Summary**: Complete the missing WireGuard lifecycle hooks (`PreDown`, `PostUp`) across the backend API and frontend UI. Simultaneously, establish standard documentation infrastructure using Swagger for the API and VitePress for static HTML documentation.
|
||||
>
|
||||
> **Deliverables**:
|
||||
> - Backend DB Model & API updated with `PreDown` and `PostUp`
|
||||
> - Dashboard UI updated with two new textareas for the hooks
|
||||
> - Swagger UI integrated at `server-core` (`/swagger/index.html`)
|
||||
> - Static HTML docs (VitePress) initialized in `apps/docs` with standard WireGuard guide structures
|
||||
>
|
||||
> **Estimated Effort**: Medium
|
||||
> **Parallel Execution**: YES (Frontend, Backend, and Docs can be built in parallel waves)
|
||||
> **Critical Path**: Backend API update -> Frontend UI update -> Swagger setup -> VitePress setup
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
### Original Request
|
||||
The user noted that the Node (WgServer) configuration currently lacks inputs for `PreDown` and `PostUp` (only `PreUp` and `PostDown` were present). Additionally, the user requested a plan for establishing HTML documentation (referencing wgdashboard documentation structure) and Swagger API documentation.
|
||||
|
||||
### Discussion & Findings
|
||||
- **Backend**: Found `PreUp` and `PostDown` in `apps/server-core/internal/models/models.go` and `apps/server-core/api/servers.go`.
|
||||
- **Frontend**: Found `PreUp` and `PostDown` in `apps/dashboard-ui/src/views/Servers.vue` and `apps/dashboard-ui/src/api/servers.ts`.
|
||||
- **Docs**: Neither `swag` nor `apps/docs` currently exists in the project.
|
||||
|
||||
### Self-Review (Metis Simulation)
|
||||
- **Guardrail**: String fields in GORM should use `gorm:"type:text"` to accommodate long bash scripts.
|
||||
- **Guardrail**: Swagger requires running `swag init` to generate `docs/docs.go`, which must be anonymously imported in `main.go`.
|
||||
- **Guardrail**: VitePress should be isolated in `apps/docs` as an independent NPM project to prevent polluting `dashboard-ui`.
|
||||
|
||||
---
|
||||
|
||||
## Work Objectives
|
||||
|
||||
### Core Objective
|
||||
Achieve full parity with WireGuard's standard lifecycle hooks in the database and UI, and lay down the foundation for professional developer and user documentation.
|
||||
|
||||
### Must Have
|
||||
- `PreDown` and `PostUp` fields in `WgServer` model.
|
||||
- Swagger annotation for at least the `Servers` endpoints to serve as a template.
|
||||
- VitePress sidebar containing the requested links: Access Remote Server, Add WireGuard Config, Peers, Sign In, Email Service, WebHooks.
|
||||
|
||||
### Must NOT Have
|
||||
- Do NOT merge VitePress into `apps/dashboard-ui/package.json`. It must be its own independent app in `apps/docs`.
|
||||
|
||||
---
|
||||
|
||||
## Execution Strategy
|
||||
|
||||
### Parallel Execution Waves
|
||||
```text
|
||||
Wave 1 (Foundation):
|
||||
├── Task 1: Update Backend Schema & API (PreDown, PostUp) [quick]
|
||||
└── Task 2: Initialize VitePress HTML Docs [quick]
|
||||
|
||||
Wave 2 (Integration):
|
||||
├── Task 3: Update Frontend Dashboard UI (PreDown, PostUp) [visual-engineering]
|
||||
└── Task 4: Setup Swagger API Documentation [deep]
|
||||
|
||||
Wave FINAL (Verification):
|
||||
├── Task F1: Plan Compliance Audit
|
||||
├── Task F2: Code Quality Review
|
||||
└── Task F3: Scope Fidelity Check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TODOs
|
||||
|
||||
- [x] 1. Update Backend Schema & API (`PreDown`, `PostUp`)
|
||||
|
||||
**What to do**:
|
||||
- Edit `apps/server-core/internal/models/models.go`: Add `PreDown` and `PostUp` (type string, `gorm:"type:text"`) to the `WgServer` struct.
|
||||
- Edit `apps/server-core/api/servers.go`:
|
||||
- Add `PreDown` and `PostUp` to `CreateServerRequest` and `UpdateServerRequest`.
|
||||
- Map these fields when creating/updating the model inside `CreateServer` and `UpdateServer` handlers.
|
||||
|
||||
**Recommended Agent Profile**:
|
||||
- **Category**: `quick`
|
||||
- **Skills**: `[]`
|
||||
|
||||
**Parallelization**: Wave 1
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `grep -q "PreDown" apps/server-core/internal/models/models.go` passes.
|
||||
- [ ] `grep -q "PostUp" apps/server-core/internal/models/models.go` passes.
|
||||
|
||||
**QA Scenarios**:
|
||||
```text
|
||||
Scenario: API accepts PreDown and PostUp
|
||||
Tool: Bash (curl)
|
||||
Preconditions: Server is running
|
||||
Steps:
|
||||
1. Send a POST or PUT request to `/api/v1/servers` with `pre_down` and `post_up` in JSON payload.
|
||||
Expected Result: Payload is accepted and saved without error.
|
||||
Evidence: .sisyphus/evidence/task-1-api-update.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [x] 2. Initialize VitePress HTML Docs
|
||||
|
||||
**What to do**:
|
||||
- Create directory `apps/docs`.
|
||||
- Initialize a standard `package.json` for VitePress.
|
||||
- Create `.vitepress/config.mts` with a sidebar structure matching the requested references:
|
||||
- Guides: Sign In, Access Remote Server, Add WireGuard Configuration, Add WireGuard Configuration Peers, Email Service, WebHooks.
|
||||
- Create markdown stubs for all the above pages inside `apps/docs/guides/`.
|
||||
|
||||
**Recommended Agent Profile**:
|
||||
- **Category**: `quick`
|
||||
- **Skills**: `[]`
|
||||
|
||||
**Parallelization**: Wave 1
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `apps/docs/package.json` exists with `vitepress` dependency.
|
||||
- [ ] `apps/docs/.vitepress/config.mts` configures the sidebar properly.
|
||||
- [ ] Markdown stubs exist for all guides.
|
||||
|
||||
**QA Scenarios**:
|
||||
```text
|
||||
Scenario: VitePress builds successfully
|
||||
Tool: Bash
|
||||
Preconditions: npm is installed
|
||||
Steps:
|
||||
1. cd apps/docs && npm install && npm run docs:build
|
||||
Expected Result: Build completes successfully producing static HTML in .vitepress/dist.
|
||||
Evidence: .sisyphus/evidence/task-2-vitepress-build.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [x] 3. Update Frontend Dashboard UI (`PreDown`, `PostUp`)
|
||||
|
||||
**What to do**:
|
||||
- Edit `apps/dashboard-ui/src/api/servers.ts`: Add `PreDown?: string` and `PostUp?: string` to the node interface.
|
||||
- Edit `apps/dashboard-ui/src/views/Servers.vue`:
|
||||
- Add two new textarea fields for `PostUp` and `PreDown` in the Add/Edit Node modal.
|
||||
- Order should logically be: `PreUp`, `PostUp`, `PreDown`, `PostDown`.
|
||||
- Ensure reactivity maps these inputs to the payload correctly.
|
||||
|
||||
**Recommended Agent Profile**:
|
||||
- **Category**: `visual-engineering`
|
||||
- **Skills**: `["vue-ui-futuristic/tailwind-futuristic"]`
|
||||
|
||||
**Parallelization**: Wave 2 (Depends on Task 1)
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] Types updated.
|
||||
- [ ] Form UI contains 4 total textarea boxes for the WireGuard hooks.
|
||||
|
||||
**QA Scenarios**:
|
||||
```text
|
||||
Scenario: UI renders new fields
|
||||
Tool: Playwright
|
||||
Preconditions: UI is running
|
||||
Steps:
|
||||
1. Navigate to Nodes page, click Register Node.
|
||||
Expected Result: PreDown and PostUp textareas are visible.
|
||||
Evidence: .sisyphus/evidence/task-3-ui-fields.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [x] 4. Setup Swagger API Documentation
|
||||
|
||||
**What to do**:
|
||||
- In `apps/server-core`, add `github.com/swaggo/swag/cmd/swag` and `github.com/swaggo/gin-swagger` via `go get`.
|
||||
- Add standard `@title`, `@version`, `@description` in `main.go`.
|
||||
- Add Swagger annotations (`@Summary`, `@Tags`, `@Accept`, `@Produce`, `@Success`) to the handlers in `api/servers.go`.
|
||||
- Mount `/swagger/*any` using `ginSwagger.WrapHandler(swaggerFiles.Handler)` in the Gin router.
|
||||
- Create a Makefile target `make swagger` inside `apps/server-core/Makefile` (or update existing) that runs `swag init`. Run it once so the `docs/` folder is generated.
|
||||
|
||||
**Recommended Agent Profile**:
|
||||
- **Category**: `deep`
|
||||
- **Skills**: `[]`
|
||||
|
||||
**Parallelization**: Wave 2
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] `go.mod` contains swaggo dependencies.
|
||||
- [ ] `/swagger/index.html` serves the API documentation.
|
||||
- [ ] `apps/server-core/docs/swagger.json` exists.
|
||||
|
||||
**QA Scenarios**:
|
||||
```text
|
||||
Scenario: Swagger endpoint returns 200 OK
|
||||
Tool: Bash (curl)
|
||||
Preconditions: Server is running
|
||||
Steps:
|
||||
1. curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/swagger/index.html
|
||||
Expected Result: Output is 200.
|
||||
Evidence: .sisyphus/evidence/task-4-swagger-200.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Verification Wave
|
||||
|
||||
- [x] F1. **Plan Compliance Audit** — `oracle`
|
||||
- [x] F2. **Code Quality Review** — `unspecified-high`
|
||||
- [x] F3. **Scope Fidelity Check** — `deep`
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Verification Commands
|
||||
```bash
|
||||
# Verify Swagger UI
|
||||
curl http://localhost:8080/swagger/index.html
|
||||
|
||||
# Verify VitePress Build
|
||||
cd apps/docs && npm run docs:build
|
||||
|
||||
# Verify Models
|
||||
grep "PreDown" apps/server-core/internal/models/models.go
|
||||
```
|
||||
Reference in New Issue
Block a user