diff --git a/pkg/cli/doc.go b/pkg/cli/doc.go new file mode 100644 index 0000000000..38bd911637 --- /dev/null +++ b/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 diff --git a/pkg/logger/doc.go b/pkg/logger/doc.go new file mode 100644 index 0000000000..8ff05ebdc3 --- /dev/null +++ b/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 diff --git a/pkg/parser/doc.go b/pkg/parser/doc.go new file mode 100644 index 0000000000..76a1886e51 --- /dev/null +++ b/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 diff --git a/pkg/types/doc.go b/pkg/types/doc.go new file mode 100644 index 0000000000..67dd232ab7 --- /dev/null +++ b/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 diff --git a/pkg/workflow/doc.go b/pkg/workflow/doc.go new file mode 100644 index 0000000000..6050fd896c --- /dev/null +++ b/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