Add package-level documentation to core packages

pkg/cli/doc.go

@@ -0,0 +1,79 @@
+// Package cli provides the command-line interface for gh-aw (GitHub Agentic Workflows).
+//
+// This package implements the `gh aw` CLI extension using the Cobra command framework.
+// It provides commands for compiling workflows, managing campaigns, running audits,
+// and inspecting MCP servers. Each command follows consistent patterns for error
+// handling, output formatting, and user interaction.
+//
+// # Available Commands
+//
+// compile - Convert markdown workflow files to GitHub Actions YAML
+//
+// add - Interactively add workflows to repositories
+//
+// audit - Analyze workflow runs for issues and generate reports
+//
+// logs - Download and inspect GitHub Actions workflow logs
+//
+// mcp - Manage and inspect MCP (Model Context Protocol) servers
+//
+// actions - Build and manage custom GitHub Actions
+//
+// campaign - Execute and manage multi-repository workflow campaigns
+//
+// # Basic Usage
+//
+//	// Compile a single workflow
+//	err := cli.RunCompile(cli.CompileConfig{
+//		WorkflowFiles: []string{"workflow.md"},
+//		Verbose:      false,
+//	})
+//
+//	// Audit a workflow run
+//	err := cli.RunAuditWorkflowRun(cli.AuditConfig{
+//		Owner:  "owner",
+//		Repo:   "repo",
+//		RunID:  123456,
+//	})
+//
+// # Command Structure
+//
+// Each command follows a consistent pattern:
+//  1. Command definition in *_command.go files
+//  2. Runnable function (RunX) for testability
+//  3. Input validation with helpful error messages
+//  4. Console-formatted output using pkg/console
+//  5. Comprehensive help text with examples
+//
+// Commands use standard flags:
+//
+//	--verbose/-v    Enable detailed output
+//	--output/-o     Specify output directory
+//	--json/-j       Output results in JSON format
+//	--engine/-e     Override AI engine selection
+//
+// # Output Formatting
+//
+// All CLI output uses the console package for consistent formatting:
+//   - Success messages in green
+//   - Errors in red with actionable suggestions
+//   - Warnings in yellow
+//   - Info messages in blue
+//   - Progress indicators for long-running operations
+//
+// # Error Handling
+//
+// Commands follow these error handling conventions:
+//   - Early validation of inputs with clear error messages
+//   - Wrapped errors with context using fmt.Errorf
+//   - Console-formatted error output to stderr
+//   - Non-zero exit codes for failures
+//
+// # Related Packages
+//
+// pkg/workflow - Core compilation logic called by compile command
+//
+// pkg/console - Output formatting utilities
+//
+// pkg/logger - Debug logging controlled by DEBUG environment variable
+package cli

pkg/logger/doc.go

@@ -0,0 +1,116 @@
+// Package logger provides namespace-based debug logging with zero overhead
+// when disabled.
+//
+// The logger package implements a lightweight debug logging system inspired by
+// the debug npm package. It uses the DEBUG environment variable for selective
+// log enabling with pattern matching and namespace coloring. When logging is
+// disabled for a namespace, log calls have zero overhead (not even string
+// formatting).
+//
+// # Basic Usage
+//
+//	var log = logger.New("cli:compile")
+//
+//	func CompileWorkflow(path string) error {
+//		log.Printf("Compiling workflow: %s", path)
+//		// Only executed if DEBUG matches "cli:compile" or "cli:*"
+//
+//		if log.Enabled() {
+//			// Expensive operation only when logging is enabled
+//			log.Printf("Details: %+v", expensiveDebugInfo())
+//		}
+//		return nil
+//	}
+//
+// # Environment Variables
+//
+// DEBUG - Controls which namespaces are enabled:
+//
+//	DEBUG=*              # Enable all namespaces
+//	DEBUG=cli:*          # Enable all cli namespaces
+//	DEBUG=workflow:*     # Enable all workflow namespaces
+//	DEBUG=cli:*,parser:* # Enable multiple patterns
+//	DEBUG=*,-test:*      # Enable all except test namespaces
+//
+// DEBUG_COLORS - Controls color output (default: enabled in terminals):
+//
+//	DEBUG_COLORS=0       # Disable colors (auto-disabled when piping)
+//
+// # Namespace Convention
+//
+// Follow the pattern: pkg:filename or pkg:component
+//
+//	logger.New("cli:compile_command")   # Command-specific
+//	logger.New("workflow:compiler")     # Core component
+//	logger.New("parser:frontmatter")    # Subcomponent
+//	logger.New("mcp:gateway")           # Feature-specific
+//
+// Use consistent naming across the codebase for easy filtering.
+//
+// # Features
+//
+// Zero Overhead: Log calls are no-ops when the namespace is disabled.
+// No string formatting or function calls occur.
+//
+// Time Deltas: Each log shows time elapsed since the previous log in that
+// namespace (e.g., +50ms, +2.5s, +1m30s).
+//
+// Auto-Colors: Each namespace gets a consistent color in terminals. Colors
+// are generated deterministically from the namespace string.
+//
+// Pattern Matching: Supports wildcards (*) and exclusions (-pattern) for
+// flexible namespace filtering.
+//
+// # Performance
+//
+//	// No overhead - neither Printf nor Enabled() called when disabled
+//	log.Printf("Debug info: %s", expensiveFunction())
+//
+//	// Check first for expensive operations
+//	if log.Enabled() {
+//		result := expensiveFunction()
+//		log.Printf("Result: %+v", result)
+//	}
+//
+// # Use Cases
+//
+// Development Debugging: Enable specific namespaces during development
+// to trace execution flow without adding/removing print statements.
+//
+// Performance Analysis: Time deltas help identify slow operations and
+// bottlenecks in the compilation pipeline.
+//
+// Production Diagnostics: Users can enable logging to diagnose issues
+// by setting DEBUG environment variable before running commands.
+//
+// Integration Testing: Tests can enable logging selectively to verify
+// behavior without affecting test output.
+//
+// # Output Format
+//
+//	workflow:compiler Parsing workflow file +0ms
+//	workflow:compiler Generating YAML +125ms
+//	cli:compile Compilation complete +2.5s
+//
+// Each line shows: namespace (colored), message, time delta
+//
+// # Best Practices
+//
+// Use logger.New at package level with consistent namespace naming.
+//
+// Log significant operations, not every line - focus on key decision points.
+//
+// Check log.Enabled() before expensive debug operations like JSON marshaling.
+//
+// Use descriptive messages that make sense without source code context.
+//
+// Prefer structured data in messages for easy parsing if needed later.
+//
+// # Related Packages
+//
+// pkg/console - User-facing output formatting (errors, success, warnings)
+//
+// pkg/timeutil - Time formatting utilities used for delta calculations
+//
+// pkg/tty - Terminal detection for color support
+package logger

pkg/parser/doc.go

@@ -0,0 +1,77 @@
+// Package parser provides markdown frontmatter parsing and content extraction
+// for agentic workflow files.
+//
+// The parser package handles the extraction and validation of YAML frontmatter
+// from markdown files, which defines workflow configuration (triggers, permissions,
+// tools, safe outputs). It also extracts the markdown body content which serves
+// as the AI agent's prompt text.
+//
+// # Key Functionality
+//
+// Frontmatter Parsing: Extracts YAML configuration blocks from markdown files
+// using delimiters (---). Supports nested structures, includes, and imports.
+//
+// Content Extraction: Separates frontmatter from markdown body content while
+// preserving formatting and structure.
+//
+// Import Processing: Resolves @import directives to include external workflow
+// fragments, templates, and shared configurations.
+//
+// GitHub URL Resolution: Fetches workflow content from GitHub repositories
+// using various URL formats (raw.githubusercontent.com, github.com URLs).
+//
+// ANSI Strip: Removes terminal color codes from content to prevent YAML
+// parsing issues.
+//
+// # Basic Usage
+//
+//	// Parse frontmatter from markdown content
+//	frontmatter, content, err := parser.ParseFrontmatter([]byte(markdown))
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	// Process imports in workflow file
+//	processor := parser.NewImportProcessor(parser.ImportProcessorConfig{
+//		BasePath: "/path/to/workflows",
+//	})
+//	resolvedFrontmatter, err := processor.Process(frontmatter)
+//
+// # Architecture
+//
+// The parsing flow:
+//  1. Read markdown file content
+//  2. Extract YAML frontmatter block between --- delimiters
+//  3. Parse YAML into structured configuration
+//  4. Resolve @import directives recursively
+//  5. Merge imported configurations
+//  6. Extract remaining markdown as prompt content
+//  7. Validate configuration structure
+//
+// # Import System
+//
+// The parser supports flexible import directives:
+//   - Local files: @import path/to/template.md
+//   - GitHub URLs: @import github.com/owner/repo/workflow.md
+//   - Fragments: @import path/to/fragment#section
+//   - Includes: Include specific frontmatter sections from other files
+//
+// Imports are cached to avoid redundant fetches and processed recursively
+// to support multi-level includes.
+//
+// # Configuration Structure
+//
+// Parsed frontmatter maps to structured types in pkg/workflow:
+//   - Trigger configuration (on: schedule, pull_request, etc.)
+//   - Permissions (contents: read, issues: write, etc.)
+//   - Tools (MCP servers, safe outputs, GitHub toolsets)
+//   - Engine settings (copilot, claude, codex, custom)
+//   - Network restrictions (allowed/blocked domains)
+//   - Runtime overrides (node, python, go versions)
+//
+// # Related Packages
+//
+// pkg/workflow - Consumes parsed frontmatter for workflow compilation
+//
+// pkg/types - Shared type definitions (BaseMCPServerConfig)
+package parser

pkg/types/doc.go

@@ -0,0 +1,49 @@
+// Package types provides shared type definitions used across gh-aw packages.
+//
+// This package contains common data structures and interfaces that are used by
+// multiple packages to avoid circular dependencies and maintain clean separation
+// of concerns. The types here are focused on configuration structures that need
+// to be shared between parsing and workflow compilation.
+//
+// # Key Types
+//
+// BaseMCPServerConfig: The foundational configuration structure for MCP
+// (Model Context Protocol) servers. This type is embedded by both parser
+// and workflow packages to maintain consistency while allowing each package
+// to add domain-specific fields.
+//
+// MCP servers are AI tool providers that can run as:
+//   - stdio processes (command + args)
+//   - HTTP endpoints (url + headers)
+//   - Container services (container image + mounts)
+//
+// # Basic Usage
+//
+//	config := types.BaseMCPServerConfig{
+//		Type:    "stdio",
+//		Command: "npx",
+//		Args:    []string{"-y", "@modelcontextprotocol/server-filesystem"},
+//		Env: map[string]string{
+//			"ALLOWED_PATHS": "/workspace",
+//		},
+//	}
+//
+// # Architecture
+//
+// This package serves as a bridge between the parser package (which reads
+// workflow markdown files) and the workflow package (which generates GitHub
+// Actions YAML). By defining shared types here, we avoid circular imports
+// and ensure consistent configuration structures.
+//
+// The types are designed to be:
+//   - Serializable to JSON and YAML
+//   - Embeddable by other packages
+//   - Extensible with package-specific fields
+//   - Well-documented with struct tags
+//
+// # Related Packages
+//
+// pkg/parser - Embeds BaseMCPServerConfig in parser.MCPServerConfig
+//
+// pkg/workflow - Embeds BaseMCPServerConfig in workflow.MCPServerConfig
+package types

pkg/workflow/doc.go

@@ -0,0 +1,69 @@
+// Package workflow provides compilation and generation of GitHub Actions workflows
+// from markdown-based agentic workflow specifications.
+//
+// The workflow package is the core of gh-aw, handling the transformation of
+// user-friendly markdown files into production-ready GitHub Actions YAML workflows.
+// It supports advanced features including:
+//   - Agentic AI workflow execution with Claude, Codex, and Copilot engines
+//   - Safe output handling with configurable permissions
+//   - MCP (Model Context Protocol) server integration
+//   - Network sandboxing and firewall configuration
+//   - GitHub Actions security best practices (SHA pinning, input sanitization)
+//
+// # Basic Usage
+//
+//	compiler := workflow.NewCompiler(workflow.CompilerOptions{
+//		Verbose: true,
+//	})
+//	err := compiler.CompileWorkflow("path/to/workflow.md")
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+// # Architecture
+//
+// The compilation process consists of:
+//  1. Frontmatter parsing - Extracts YAML metadata (triggers, permissions, tools)
+//  2. Markdown processing - Extracts the AI prompt text from markdown body
+//  3. Tool configuration - Configures MCP servers, safe outputs, and GitHub tools
+//  4. Job generation - Creates main agent job, activation jobs, and safe output jobs
+//  5. YAML generation - Produces final GitHub Actions workflow with security features
+//
+// # Key Components
+//
+// Compiler: The main orchestrator that coordinates all compilation phases.
+// Handles markdown parsing, frontmatter extraction, and YAML generation.
+//
+// Engine Configuration: Supports multiple AI engines (copilot, claude, codex, custom).
+// Each engine has specific tool integrations and execution patterns.
+//
+// MCP Servers: Model Context Protocol servers provide tools to AI agents.
+// Configured via frontmatter and can run as stdio processes, HTTP endpoints,
+// or containerized services.
+//
+// Safe Outputs: Write operations (create issue, add comment, etc.) are
+// sanitized and executed in separate jobs with minimal permissions to
+// prevent prompt injection attacks.
+//
+// Network Sandboxing: Firewall configuration restricts network access to
+// approved domains, preventing data exfiltration and unauthorized API calls.
+//
+// # Security Features
+//
+// The workflow package implements multiple security layers:
+//   - SHA-pinned GitHub Actions (no tag-based references)
+//   - Input sanitization for all user-provided data
+//   - Read-only execution by default with explicit safe-output gates
+//   - Network firewalls with domain allowlists
+//   - Tool allowlisting (MCP servers, safe outputs)
+//   - Template injection prevention
+//   - Secrets redaction and masking
+//
+// # Related Packages
+//
+// pkg/parser - Markdown and YAML frontmatter parsing
+//
+// pkg/cli - Command-line interface for compilation and workflow management
+//
+// pkg/types - Shared type definitions for MCP and workflow configuration
+package workflow