shellguard: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working in this repository.

Build & Test Commands

make build          # Static binary to ./bin/shellguard (CGO_ENABLED=0)
make test           # go test ./... -count=1
make test-race      # go test ./... -race -count=1
make lint           # golangci-lint run ./...

Run a single test:

go test ./parser -run TestParseSimpleCommand -count=1

Run a single fuzz test:

go test ./parser -fuzz FuzzParse -fuzztime=30s

Project Structure

shellguard.go                    # Root package: Config, New(), RunStdio()
cmd/shellguard/                  # CLI entry point
server/                          # MCP server core, tool registration, Executor interface
parser/                          # Shell AST parser (mvdan.cc/sh/v3)
validator/                       # Command/flag allowlist validation
ssh/                             # SSH manager, ShellQuote, ReconstructCommand
manifest/                        # YAML command registry (embed.FS)
  manifests/                     # Allowed command manifests
  manifests/denied/              # Denied command manifests
output/                          # Output truncation (64KB cap)
toolkit/                         # Diagnostic tool provisioning (rg, jq, yq)

Dependency flow: server depends on all other packages. validator depends on parser and manifest. ssh (reconstruct) depends on parser. manifest, parser, and output are standalone with zero internal dependencies.

Code Style

Imports

Two groups separated by a blank line: stdlib first, then everything else (third-party and internal mixed together, alphabetically sorted).

import (
    "context"
    "fmt"

    "github.com/fawdyinc/shellguard/manifest"
    "github.com/fawdyinc/shellguard/parser"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

When a third-party package name conflicts with a local package, alias the third-party one (e.g., gossh "golang.org/x/crypto/ssh" in ssh/ssh.go).