datadunia
221 lines
8.1 KiB
Markdown
221 lines
8.1 KiB
Markdown
# 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
|
|
```
|