Skip to content

AGENTS.md

Latest commit

 

History

History
357 lines (254 loc) · 9.33 KB

AGENTS.md

File metadata and controls

357 lines (254 loc) · 9.33 KB

AGENTS.md

This file provides guidance for AI agents and humans working with the NPN codebase.

Table of Contents

Project Overview

NPN

It's basically Postman, but much smaller (8MB download) and faster. You can run npn as an HTTP server, or use a native desktop or mobile app.

This application is managed with Project Forge.

Quick Start

# Build the application
make build

# Run in development mode with live reload
./bin/dev.sh # or `make dev`

# Run tests
./bin/test.sh # or `make test`

# Lint code
./bin/check.sh

# Format code
./bin/format.sh

# Build for production
./bin/build/build.sh # or `make build-release`

Project Structure

app/                   # Application code
├── cmd/               # CLI commands and the main entrypoint of the app
├── controller/        # HTTP request handlers (MVC controllers, usually)
├── lib/               # Common logic and services, usually provided by modules
└── util/              # Utility functions and helpers
assets/               # Static files (CSS, JS, images)
bin/                  # Build and development scripts
client/               # TypeScript/JavaScript client code
doc/                  # Project documentation
tools/                # Platform-specific build tools
views/                # HTML templates (quicktemplate)

Key Directories

  • /app/controller/: HTTP handlers organized by feature area
  • /app/lib/: Mostly logic provided by github.com/kyleu/npn
  • /bin/: Development and build automation scripts
  • /views/: HTML templates using quicktemplate syntax

Development Workflow

1. Making Changes

Development Server

# Start development server with live reload
./bin/dev.sh

# The server will automatically:
# - Rebuild Go code on changes
# - Recompile templates on changes
# - Rebuild client assets on changes
# - Restart the server as needed

Manual Builds

make build
./build/debug/npn

2. Before Committing

# Format code
./bin/format.sh

# Run linting and validation
./bin/check.sh

# Run tests
./bin/test.sh

# Ensure everything builds
make build

# If changes are significant, consider running
./bin/build/release-test.sh

3. Template Development

# Compile templates manually (automatically handled by `dev.sh` and `make build`)
./bin/templates.sh

# Templates use quicktemplate syntax (.html files -> .html.go files)
# Located in /views/ directory

Build Commands

Command Description
make build Build debug binary
make build-release Build optimized release binary
make dev Start development server with live reload (powered by air)
make lint Run linters and code quality checks
make clean Remove build artifacts and compiled templates
make templates Compile quicktemplate files (automatically handled by dev.sh and make build)
make help Show available make targets

Script Commands

Script Description
./bin/dev.sh Development server with live reload
./bin/check.sh Lint, format check, and validation
./bin/format.sh Format Go code with gofumpt
./bin/test.sh Run all tests
./bin/templates.sh Compile quicktemplate files
./bin/coverage.sh Generate test coverage report

Testing

Running Tests

# All tests
./bin/test.sh # or gotestsum -- ./app/...

# Single package
go test ./app/util -v

# Single test
go test ./app/util -run TestPlural

# With coverage
./bin/coverage.sh

# Watch mode
./bin/test.sh -w

# Clean cache and run
./bin/test.sh -c

Test Organization

  • Unit tests: Alongside source code with _test.go suffix
  • Integration tests: In /test/ directory
  • E2E tests: Playwright tests in /test/playwright/

Code Style & Conventions

Go Code Standards

  • Formatting: Use bin/format.sh or gofumpt (enforced by linters)
  • Max line length: 160 characters
  • Function length: Max 100 lines recommended
  • Cyclomatic complexity: Max 30 recommended
  • Error handling: Always check errors, provide context
  • Naming: PascalCase for exported, camelCase for internal

Import Organization

import (
    // Standard library
    "context"
    "fmt"

    // Third-party
    "go.uber.org/zap"

    // Project imports
    "github.com/kyleu/npn/app/util"
)

HTML Template Conventions

  • Use quicktemplate syntax (not html/template)
  • Templates in /views/ compile to .html.go files
  • Follow existing naming patterns (PascalCase for template names)
  • Leverage existing component templates in /views/components/

Key Technologies

Core Stack

See technology.md for a complete list.

Frontend

  • TypeScript: Progressive enhancement client code
  • ESBuild: Fast asset bundling
  • CSS: Modern CSS with CSS custom properties
  • SVG: Embedded icon system

Development Tools

  • Air: Live reload for development
  • gofumpt: Opinionated Go formatting
  • golangci-lint: Comprehensive Go linting
  • gotestsum: Enhanced test runner

Common Patterns

Error Handling

import "github.com/pkg/errors"

func process(url string) (any, error) {
    data, err := fetch(url)
    if err != nil {
        return nil, errors.Wrapf(err, "failed to fetch data from [%s]", url)
    }
    return data, nil
}

Controllers (MVC)

Project Forge controllers can serve both HTML pages and API responses using the same handler. The Act helper provides authentication, CORS, telemetry, error handling, and request state:

func APIEndpoint(w http.ResponseWriter, r *http.Request) {
	controller.Act("api.endpoint", w, r, func(as *app.State, ps *cutil.PageState) (string, error) {
		data := getSomeData()
		// Set data for API responses (json, xml, csv, yaml, etc.)
		ps.SetTitleAndData("API Response", data)
		page := &views.SomePage{Data: data}
		return controller.Render(r, as, page, ps, "breadcrumb")
	})
}

Content Type Support

The Render function automatically serves multiple formats based on Accept headers or ?format= query params:

  • JSON: Accept: application/json or ?format=json
  • CSV: Accept: text/csv or ?format=csv
  • XML: Accept: application/xml or ?format=xml
  • YAML: Accept: application/yaml or ?format=yaml
  • Debug: ?format=debug (admin access required)
  • HTML: Default for browser requests

Configuration

Use environment variables with sensible defaults. Document the allowed envvars in running.md:

count := util.GetEnvInt("my_variable", 42000)

Configuration

Project Configuration

The project definition lives in .projectforge/project.json, which represents the [github.com/kyleu/npn(httpsgithub.com/kyleu/npnv) configuration.

Troubleshooting

Common Issues

Build fails with template errors
make clean;make build
Linting errors
# Auto-fix formatting
./bin/format.sh

# Check what's wrong
./bin/check.sh
Development server not reloading
  • Check that air is installed and working
  • Verify .air.toml configuration exists
  • Restart with ./bin/dev.sh

Performance Issues

  • Use go tool pprof for profiling (see /bin/util/ scripts)
  • Check telemetry data for bottlenecks
  • Review database query patterns
  • Verify proper HTTP caching headers

Additional Resources

Documentation

Build Scripts

Explore /bin/ directory for additional utilities:

  • /bin/util/: Profiling and analysis tools
  • /bin/workspace.sh: Helper script for macOS iTerm2 users
  • /bin/tag.sh: Version tagging
  • /bin/export.sh: Project export

Development Files

  • Makefile: Primary build targets
  • .air.toml: Live reload configuration (if present)
  • go.mod: Go dependency management
  • client/package.json: Frontend dependencies

Getting Help

  • Check existing documentation in /doc/
  • Examine similar patterns in existing code
  • Look at example applications in README.md

This file is maintained for both AI agents and human developers. When making changes, ensure information remains accurate and examples stay current with the codebase.