# 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
```