Admin portal scaffolding

.github/workflows/ci-admin.yml

@@ -0,0 +1,146 @@
+# Copyright 2026 CloudBlue LLC
+# SPDX-License-Identifier: Apache-2.0
+
+name: CI (Admin Portal)
+
+on:
+  push:
+    branches:
+      - master
+      - 'release/**'
+    paths:
+      - 'admin/**'
+      - 'Makefile'
+      - '.github/workflows/ci-admin.yml'
+  pull_request:
+    paths:
+      - 'admin/**'
+      - 'Makefile'
+      - '.github/workflows/ci-admin.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  GOLANGCI_LINT_VERSION: 'v2.8.0'
+  PNPM_VERSION: '10.28.2'
+
+jobs:
+  lint-go:
+    name: Lint (Go)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: admin/go.mod
+          cache-dependency-path: admin/go.sum
+
+      - name: Run golangci-lint (admin module)
+        # The admin module embeds ui/dist in !dev builds; use dev tags for
+        # backend lint/test so checks do not depend on prebuilt UI artifacts.
+        uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
+        with:
+          version: ${{ env.GOLANGCI_LINT_VERSION }}
+          working-directory: admin
+          args: --build-tags=dev
+
+  lint-ui:
+    name: Lint (UI)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+
+      - name: Install pnpm
+        run: corepack enable && corepack prepare pnpm@${{ env.PNPM_VERSION }} --activate
+
+      - name: Install dependencies
+        working-directory: admin/ui
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: admin/ui
+        run: pnpm lint
+
+  test-go:
+    name: Test (Go)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: admin/go.mod
+          cache-dependency-path: admin/go.sum
+
+      - name: Run tests
+        # Keep Go test path independent from ui/dist embed requirements.
+        run: cd admin && go test -race -tags dev ./...
+
+  test-ui:
+    name: Test (UI)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+
+      - name: Install pnpm
+        run: corepack enable && corepack prepare pnpm@${{ env.PNPM_VERSION }} --activate
+
+      - name: Install dependencies
+        working-directory: admin/ui
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        working-directory: admin/ui
+        run: pnpm test --passWithNoTests
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint-go, lint-ui, test-go, test-ui]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version-file: admin/go.mod
+          cache-dependency-path: admin/go.sum
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+
+      - name: Install pnpm
+        run: corepack enable && corepack prepare pnpm@${{ env.PNPM_VERSION }} --activate
+
+      - name: Build admin portal
+        run: make build-admin
+
+      - name: Verify binary exists
+        run: |
+          test -f bin/chaperone-admin
+          ./bin/chaperone-admin --version

.github/workflows/security.yml

@@ -101,14 +101,18 @@ jobs:
         #   into message strings. Log injection is not possible.
         #   Safety net: the "no-raw-logging" step below enforces that all
         #   production code uses slog, not fmt.Print*/log.Print*.
-        run: gosec -exclude=G706 -exclude-dir=sdk -exclude-dir=plugins ./...
+        run: gosec -exclude=G706 -exclude-dir=sdk -exclude-dir=plugins -exclude-dir=admin ./...
 
       - name: Run gosec (SDK module)
         run: cd sdk && gosec ./...
 
       - name: Run gosec (Contrib module)
         run: cd plugins/contrib && gosec ./...
 
+      - name: Run gosec (admin module)
+        # Use -tags=dev so the embed directive for ui/dist is not required.
+        run: cd admin && gosec -tags=dev -exclude=G706 ./...
+
   # TODO: Enable when repo is public (requires GitHub Advanced Security)
   # dependency-review:
   #   name: Dependency Review

.gitignore

@@ -10,6 +10,8 @@
 /dist/
 /chaperone
 /chaperone-onboard
+/chaperone-admin
+admin/chaperone-admin
 
 # Test binary, built with `go test -c`
 *.test
@@ -69,3 +71,12 @@ test/load/results/
 
 # PID files for background processes
 .target-server.pid
+
+# SQLite database artifacts
+*.db
+*.db-shm
+*.db-wal
+
+# Admin portal frontend
+admin/ui/node_modules/
+admin/ui/dist/

Makefile

@@ -87,6 +87,46 @@ clean: ## Remove build artifacts
 	@rm -rf $(BUILD_DIR)
 	@rm -f coverage.out coverage.html
 
+# ============================================================================
+# Admin Portal
+# ============================================================================
+
+ADMIN_BINARY_NAME := chaperone-admin
+ADMIN_MODULE_DIR := admin
+ADMIN_CMD_PATH := ./cmd/chaperone-admin
+ADMIN_UI_DIR := admin/ui
+
+ADMIN_LDFLAGS := -ldflags "-s -w \
+	-X main.Version=$(VERSION) \
+	-X main.GitCommit=$(GIT_COMMIT) \
+	-X main.BuildDate=$(BUILD_DATE)"
+
+ADMIN_LDFLAGS_DEV := -ldflags "\
+	-X main.Version=$(VERSION)-dev \
+	-X main.GitCommit=$(GIT_COMMIT) \
+	-X main.BuildDate=$(BUILD_DATE)"
+
+.PHONY: build-admin
+build-admin: build-admin-ui ## Build the admin portal binary (production)
+	@echo "Building $(ADMIN_BINARY_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	cd $(ADMIN_MODULE_DIR) && CGO_ENABLED=0 go build $(ADMIN_LDFLAGS) -o ../$(BUILD_DIR)/$(ADMIN_BINARY_NAME) $(ADMIN_CMD_PATH)
+
+.PHONY: build-admin-dev
+build-admin-dev: ## Build admin portal for development (no UI build needed)
+	@echo "Building $(ADMIN_BINARY_NAME) (development)..."
+	@mkdir -p $(BUILD_DIR)
+	cd $(ADMIN_MODULE_DIR) && go build -tags dev $(ADMIN_LDFLAGS_DEV) -o ../$(BUILD_DIR)/$(ADMIN_BINARY_NAME) $(ADMIN_CMD_PATH)
+
+.PHONY: build-admin-ui
+build-admin-ui: ## Build the admin portal SPA
+	@echo "Building admin UI..."
+	cd $(ADMIN_UI_DIR) && pnpm install && pnpm build
+
+.PHONY: run-admin
+run-admin: build-admin-dev ## Build and run admin portal
+	@$(BUILD_DIR)/$(ADMIN_BINARY_NAME)
+
 # ============================================================================
 # Development Certificates
 # ============================================================================
@@ -104,24 +144,28 @@ test: ## Run tests (all modules)
 	go test -v ./...
 	cd sdk && go test -v ./...
 	cd plugins/contrib && go test -v ./...
+	cd admin && go test -tags dev -v ./...
 
 .PHONY: test-race
 test-race: ## Run tests with race detector
 	go test -race -v ./...
 	cd sdk && go test -race -v ./...
 	cd plugins/contrib && go test -race -v ./...
+	cd admin && go test -race -tags dev -v ./...
 
 .PHONY: test-cover
 test-cover: ## Run tests with coverage
 	go test -coverprofile=coverage.out ./...
 	cd sdk && go test -coverprofile=coverage-sdk.out ./...
 	cd plugins/contrib && go test -coverprofile=coverage-contrib.out ./...
+	cd admin && go test -tags dev -coverprofile=coverage-admin.out ./...
 	go tool cover -html=coverage.out -o coverage.html
 	@echo "Coverage report: coverage.html"
 
 .PHONY: test-short
 test-short: ## Run short tests only
 	go test -short -v ./...
+	cd admin && go test -short -tags dev -v ./...
 
 .PHONY: test-integration
 test-integration: ## Run integration tests
@@ -254,7 +298,8 @@ lint: ## Run linters (all modules)
 	@if [ -x "$(GOLANGCI_LINT)" ]; then \
 		$(GOLANGCI_LINT) run && \
 		(cd sdk && $(GOLANGCI_LINT) run) && \
-		(cd plugins/contrib && $(GOLANGCI_LINT) run); \
+		(cd plugins/contrib && $(GOLANGCI_LINT) run) && \
+		(cd admin && $(GOLANGCI_LINT) run --build-tags=dev); \
 	else \
 		echo "golangci-lint not installed. Run: make tools"; \
 		exit 1; \
@@ -265,6 +310,7 @@ lint-fix: ## Run linters and fix issues
 	$(GOLANGCI_LINT) run --fix
 	cd sdk && $(GOLANGCI_LINT) run --fix
 	cd plugins/contrib && $(GOLANGCI_LINT) run --fix
+	cd admin && $(GOLANGCI_LINT) run --fix --build-tags=dev
 
 .PHONY: fmt
 fmt: ## Format code (all modules)
@@ -274,25 +320,30 @@ fmt: ## Format code (all modules)
 	cd sdk && gofmt -s -w .
 	cd plugins/contrib && go fmt ./...
 	cd plugins/contrib && gofmt -s -w .
+	cd admin && go fmt ./...
+	cd admin && gofmt -s -w .
 
 .PHONY: vet
-vet: ## Run go vet
+vet: ## Run go vet (all modules)
 	go vet ./...
 	cd sdk && go vet ./...
 	cd plugins/contrib && go vet ./...
+	cd admin && go vet -tags dev ./...
 
 .PHONY: tidy
 tidy: ## Tidy and verify go.mod (all modules)
 	go mod tidy
 	go mod verify
 	cd sdk && go mod tidy
 	cd plugins/contrib && go mod tidy && go mod verify
+	cd admin && go mod tidy
 
 .PHONY: gosec
 gosec: ## Run gosec security scanner (all modules)
 	@if [ -x "$(GOSEC)" ]; then \
-		$(GOSEC) -exclude=G706 -exclude-dir=sdk -exclude-dir=plugins ./... && \
-		(cd sdk && $(GOSEC) ./...); \
+		$(GOSEC) -exclude=G706 -exclude-dir=sdk -exclude-dir=plugins -exclude-dir=admin ./... && \
+		(cd sdk && $(GOSEC) ./...) && \
+		(cd admin && $(GOSEC) -tags=dev ./...); \
 	else \
 		echo "gosec not installed. Run: make tools"; \
 		exit 1; \
@@ -302,7 +353,8 @@ gosec: ## Run gosec security scanner (all modules)
 govulncheck: ## Run govulncheck vulnerability scanner (all modules)
 	@if [ -x "$(GOVULNCHECK)" ]; then \
 		$(GOVULNCHECK) ./... && \
-		(cd sdk && $(GOVULNCHECK) ./...); \
+		(cd sdk && $(GOVULNCHECK) ./...) && \
+		(cd admin && $(GOVULNCHECK) ./...); \
 	else \
 		echo "govulncheck not installed. Run: make tools"; \
 		exit 1; \
@@ -324,7 +376,8 @@ ADDLICENSE_FLAGS := -f .copyright-header.tmpl \
 	-ignore 'bin/**' \
 	-ignore 'certs/**' \
 	-ignore '.ai/**' \
-	-ignore '.claude/**'
+	-ignore '.claude/**' \
+	-ignore 'admin/ui/**'
 
 .PHONY: license-check
 license-check: ## Check that all source files have copyright headers