pmg/AGENTS.md

PMG - Development Guide

DO NOT USE UNNECESSARY CODE COMMENTS - The code is read and written by humans who are proficient in Go programming language. Write idiomatic Go code following DRY and SOLID principles. DO NOT SHY AWAY FROM PROPOSING REFACTORING THAT IMPROVES THE CODE BASE.

Build & Test

go build ./...          # Build
go test ./... -count=1  # Run all tests
go test ./config/ -v -count=1  # Run specific package tests

Project Structure

• cmd/ — CLI commands (npm, pypi, setup, version)
• config/ — Configuration loading, templates, merging
• sandbox/ — Sandbox policy enforcement (macOS Seatbelt, Linux Bubblewrap)
• proxy/ — Proxy-based package interception
• guard/ — Guard-based package analysis
• analyzer/ — Package security analysis
• internal/ — Internal utilities (analytics, eventlog, flows, ui)

Proxy E2E Tests

• test/proxye2e/ is a hermetic (no network) table-driven framework for the proxy flow. It runs the real proxy, interceptors, cooldown handlers and analyzer verdict-mapping against an in-process mock registry and a stub malysis gRPC client.
• Any security-sensitive change to the proxy flow (interceptors, cooldown, malware allow/confirm/block, trusted/insecure bypass, new controls) MUST add or extend an E2E case in test/proxye2e/. Add a TestCase with Config/Setup/Exec/Assert; do not build new scaffolding.

Code Style

• Keep things short and simple
• Avoid unnecessary code comments
• Use comments for trade-offs, known uncovered cases, and anything useful for a human reader
• Code itself should be readable without comments explaining the obvious
• Follow existing patterns in the codebase
• Use testify (assert/require) for test assertions — do not use raw if checks with t.Errorf/t.Fatalf
• Use require for assertions that should stop the test on failure (e.g. nil error checks before using a value)
• Use assert for assertions where the test can continue after failure
• Table-driven tests preferred

Code Reuse

• Follow DRY — do not duplicate code
• Prefer refactoring existing code for reusability over copying and modifying
• Extract shared logic into functions or packages when patterns repeat

Error Handling

• Never swallow errors — always handle them explicitly
• Prefer failing fast by returning errors up the call stack
• When soft failure is acceptable, log with log.Warnf from github.com/safedep/dry/log
• Do not use _ = someFunc() to discard errors silently
• For CLI/user-facing errors, prefer usefulerror with a specific code and actionable help so ui.ErrorExit does not classify expected failures as Unknown
• Check the error from fmt.Fprintf/fmt.Fprintln/fmt.Fprint (the errcheck linter flags these). Return it up the stack: if _, err := fmt.Fprintf(out, ...); err != nil { return err }