go/pkg/help/.github/copilot-instructions.md

Copilot Instructions for Help Module

Project Overview

This repository contains the help module, which was formerly part of the Snider/Core framework. The module provides assistance and documentation functionality for applications, allowing them to embed and display help documentation.

The project consists of three main components:

1. Go Library: A Go module that provides a help service for displaying documentation
2. Documentation: MkDocs-based documentation that can be embedded in applications
3. Angular UI Component: A custom HTML element built with Angular Elements for the help interface

Technology Stack

• Go Library: Go 1.25 with embedded file systems
• Documentation: MkDocs Material theme with Python
• UI Component: Angular 20.3+ with Angular Elements
• Build Tools:
  • GoReleaser for Go library releases
  • Angular CLI for UI builds
  • Task (Taskfile) for documentation builds
• Package Management:
  • Go modules for Go dependencies
  • pip for Python/MkDocs dependencies
  • npm for Node.js/Angular dependencies

Project Structure

.
├── help.go                # Main Go library implementation
├── help_test.go           # Go tests
├── go.mod                 # Go module definition
├── examples/              # Example applications
│   ├── show_help/         # Example: showing help
│   └── show_at/           # Example: showing help at specific anchor
├── src/                   # MkDocs documentation source
│   ├── index.md           # Main documentation page
│   ├── images/            # Documentation images
│   └── stylesheets/       # Custom CSS
├── public/                # Built documentation (embedded in Go binary)
├── ui/                    # Angular help UI component
│   ├── src/               # Angular source code
│   ├── public/            # Static assets
│   └── package.json       # Node.js dependencies
├── mkdocs.yml             # MkDocs configuration
├── taskfile.dist.yml      # Task runner configuration
└── .github/               # GitHub workflows and configurations

Development Setup

Prerequisites

• Go 1.25 or later
• Python 3 with pip
• Node.js and npm
• Task (task runner) - optional but recommended

Initial Setup

1. Install Go dependencies:

   go mod tidy
   

2. Install documentation dependencies:

   pip install -r requirements.txt
   

3. Install UI dependencies (if working on the Angular component):

   cd ui
   npm install
   

Running the Documentation Server

Using Task (recommended):

task dev

Or using MkDocs directly:

mkdocs serve

This starts a live-reloading development server for the documentation at http://localhost:8000.

Building

Build Documentation

The documentation is built into the public directory and embedded in the Go binary:

task build
# or
mkdocs build --clean -d public

Build UI Component

cd ui
npm run build

This creates the Angular custom element in the dist directory.

Testing

Go Tests

Run all Go tests with coverage:

go test -v -coverprofile=coverage.out ./...

The test suite includes:

• Service initialization tests
• Display functionality tests
• Error handling tests
• Custom source and asset loading tests

UI Tests

Run Angular tests:

cd ui
npm test

Code Style and Conventions

Go Code

• Follow standard Go conventions and formatting (use gofmt or go fmt)
• Use meaningful variable and function names
• Keep functions focused and single-purpose
• Follow the existing patterns for interfaces (Logger, App, Core, Display, Help)
• Use context.Context for service lifecycle management
• Embed static assets using //go:embed directives

Documentation (Markdown)

• Follow MkDocs Material conventions
• Use clear, concise language
• Include code examples where appropriate
• Keep line length reasonable for readability
• Use proper heading hierarchy

Angular/TypeScript Code

• Follow Angular style guide
• Use Prettier for code formatting (configuration in ui/package.json)
• Settings:
  • Print width: 100 characters
  • Single quotes preferred
  • Angular parser for HTML files

General Guidelines

• Write clear, self-documenting code
• Add comments for complex logic or non-obvious decisions
• Keep commits atomic and well-described
• Follow the existing code patterns in the repository

API Overview

Main Interfaces

• Help: Main interface for the help service with Show(), ShowAt(anchor string), and ServiceStartup(ctx context.Context) methods
• Core: Application core interface providing ACTION dispatch and App access
• App: Application interface providing Logger access
• Logger: Logging interface with Info and Error methods
• Display: Marker interface for display service dependency checking

Options

The Options struct allows configuration:

• Source: Path to custom static site directory
• Assets: Custom fs.FS for documentation assets (can be embed.FS or any fs.FS implementation)

Usage Pattern

// Initialize with default embedded documentation
helpService, err := help.New(help.Options{})

// Or with custom embedded assets
helpService, err := help.New(help.Options{
    Assets: myDocs,
})

// Or with custom directory source
helpService, err := help.New(help.Options{
    Source: "path/to/docs",
})

// Start the service
err = helpService.ServiceStartup(ctx)

// Show help
err = helpService.Show()

// Show help at specific location
err = helpService.ShowAt("ui/how/settings#resetPassword")

Important Notes for AI Assistants

1. Minimal Changes: Make the smallest possible changes to achieve the goal
2. No Breaking Changes: Don't modify working code unless necessary
3. Testing: Always run go test ./... before and after changes to ensure nothing breaks
4. Build Verification: Ensure go build succeeds after making changes
5. Dependencies: Check for security vulnerabilities before adding new dependencies using govulncheck or similar security scanning tools
6. Module Name: The Go module is github.com/Snider/help - do not change this
7. Embedded Assets: The public directory is embedded in the Go binary via //go:embed all:public/*
8. Documentation: When changing documentation, rebuild with task build or mkdocs build

CI/CD Workflows

• Go CI (.github/workflows/go.yml): Runs tests and uploads coverage on push/PR to main
• Release (.github/workflows/release.yml): Uses GoReleaser to build and publish releases

Contributing

When contributing to this repository:

1. Run tests before making changes: go test ./...
2. Make minimal, focused changes
3. Run tests after changes to verify nothing broke
4. Follow the existing code style
5. Update documentation if the API changes
6. Ensure all CI checks pass
7. Keep commits atomic with clear messages

Common Tasks

• Run tests: go test -v ./...
• Run tests with coverage: go test -v -coverprofile=coverage.out ./...
• Build documentation: task build or mkdocs build --clean -d public
• Serve documentation: task dev or mkdocs serve
• Format Go code: go fmt ./...
• Tidy dependencies: go mod tidy