Nexus-Guard-Suite/.sisyphus/plans/archived/nodes-wg-hooks-and-docs.md

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

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

• 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:

  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
  

---

• 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:

  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
  

---

• 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:

  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
  

---

• 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:

  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

• F1. Plan Compliance Audit — oracle
• F2. Code Quality Review — unspecified-high
• F3. Scope Fidelity Check — deep

---

Success Criteria

Verification Commands

# 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