diff --git a/pkg/actionpins/README.md b/pkg/actionpins/README.md index 826c2b366c3..ae1bed914c7 100644 --- a/pkg/actionpins/README.md +++ b/pkg/actionpins/README.md @@ -37,6 +37,19 @@ Resolution supports two modes: | `ResolveActionPin` | `func(actionRepo, version string, ctx *PinContext) (string, error)` | Resolves a pinned reference with optional dynamic SHA lookup and fallback behavior | | `GetCachedActionPin` | `func(repo string, ctx *PinContext) string` | Returns a pinned reference preferring cache/dynamic resolution when available | +## Usage Example + +```go +ctx := &actionpins.PinContext{StrictMode: true} + +reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx) +if err != nil { + panic(err) +} + +fmt.Println(reference) // actions/checkout@ # v5 +``` + ## Dependencies **Internal**: diff --git a/pkg/console/README.md b/pkg/console/README.md index 79c690e8722..32edbe615c5 100644 --- a/pkg/console/README.md +++ b/pkg/console/README.md @@ -1,4 +1,4 @@ -# Console Package +# console Package The `console` package provides utilities for formatting and rendering terminal output in GitHub Agentic Workflows. It covers message formatting, table and section rendering, interactive prompts, progress bars, spinners, struct rendering, and accessibility support. @@ -783,3 +783,7 @@ if console.IsAccessibleMode() { // Use simpler, non-animated output } ``` + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/envutil/README.md b/pkg/envutil/README.md index 42476acda9f..cd2db6590d2 100644 --- a/pkg/envutil/README.md +++ b/pkg/envutil/README.md @@ -44,3 +44,7 @@ concurrency := envutil.GetIntFromEnv("GH_AW_MAX_CONCURRENT_DOWNLOADS", 5, 1, 20, - Warning messages use `console.FormatWarningMessage` so they render consistently in terminals. - All warnings go to `os.Stderr` to avoid polluting structured stdout output. - The function only handles integers; floating-point or string env vars should be read directly via `os.Getenv`. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/logger/README.md b/pkg/logger/README.md index 1ed65d21221..8cf0fba0a6d 100644 --- a/pkg/logger/README.md +++ b/pkg/logger/README.md @@ -1,4 +1,4 @@ -# Logger Package +# logger Package A simple, debug-style logging framework for Go that follows the pattern matching syntax of the [debug npm package](https://www.npmjs.com/package/debug). @@ -212,3 +212,7 @@ slogLogger.Warn("something unusual happened", "count", 42) - Colors assigned using FNV-1a hash for consistent namespace-to-color mapping - Color palette chosen for readability on both light and dark terminals - Uses ANSI 256-color codes for better compatibility + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/repoutil/README.md b/pkg/repoutil/README.md index ff9d22454f3..5f818ef2b08 100644 --- a/pkg/repoutil/README.md +++ b/pkg/repoutil/README.md @@ -40,3 +40,7 @@ repoutil.SplitRepoSlug("github/gh-aw/x") // error: invalid repo format: github/g - All debug output uses `logger.New("repoutil:repoutil")` and is only emitted when `DEBUG=repoutil:*`. - For paths that include sub-folders (e.g. GitHub Actions `uses:` fields such as `github/codeql-action/upload-sarif`), use `gitutil.ExtractBaseRepo` first to strip the sub-path before calling `SplitRepoSlug`. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/semverutil/README.md b/pkg/semverutil/README.md index ae547da0afe..3e7b7cf869f 100644 --- a/pkg/semverutil/README.md +++ b/pkg/semverutil/README.md @@ -101,3 +101,7 @@ semverutil.IsCompatible("v6.0.0", "v5") // false - All debug output uses `logger.New("semverutil:semverutil")` and is only emitted when `DEBUG=semverutil:*`. - The package intentionally delegates to `golang.org/x/mod/semver` for canonical semver logic rather than implementing its own parsing. - `ParseVersion` uses `semver.Canonical` before splitting into components, ensuring correct handling of short forms like `v1` (canonicalized to `v1.0.0`). + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/sliceutil/README.md b/pkg/sliceutil/README.md index ae472db5108..311484a48a4 100644 --- a/pkg/sliceutil/README.md +++ b/pkg/sliceutil/README.md @@ -77,3 +77,7 @@ unique := sliceutil.Deduplicate(items) - `Any` is implemented via `slices.ContainsFunc` from the standard library. - `Deduplicate` uses a `map[T]bool` for O(n) time complexity. - None of these functions sort their output; callers that require sorted results should call `slices.Sort` on the returned slice. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/stats/README.md b/pkg/stats/README.md index 062b640fe48..a93079faa9c 100644 --- a/pkg/stats/README.md +++ b/pkg/stats/README.md @@ -30,6 +30,21 @@ The `stats` package provides `StatVar`, a compact accumulator for numeric metric | `SampleStdDev` | `func() float64` | Returns sample standard deviation | | `Median` | `func() float64` | Returns the exact median (middle value or midpoint of two middle values) | +## Usage Example + +```go +var s stats.StatVar + +s.Add(10) +s.Add(20) +s.Add(30) + +fmt.Println(s.Count()) // 3 +fmt.Println(s.Mean()) // 20 +fmt.Println(s.StdDev()) // 8.164965... +fmt.Println(s.Median()) // 20 +``` + ## Dependencies **Standard library only**: diff --git a/pkg/stringutil/README.md b/pkg/stringutil/README.md index 38da4436558..b1d0870292a 100644 --- a/pkg/stringutil/README.md +++ b/pkg/stringutil/README.md @@ -177,3 +177,7 @@ Returns a human-readable description of the token type (e.g. `"fine-grained pers - All debug output uses namespace-prefixed loggers (`stringutil:identifiers`, `stringutil:sanitize`, `stringutil:urls`, `stringutil:pat_validation`) and is only emitted when `DEBUG=stringutil:*`. - `SanitizeErrorMessage` is intentionally conservative: it excludes common GitHub Actions keywords to avoid over-redacting legitimate error messages. - `StripANSI` handles both CSI sequences (`ESC[`) and other ESC-prefixed sequences to cover the full range of ANSI escape codes found in terminal output. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/styles/README.md b/pkg/styles/README.md index 05468b69f55..6ff87f6bcb0 100644 --- a/pkg/styles/README.md +++ b/pkg/styles/README.md @@ -99,3 +99,7 @@ form := huh.NewForm(...).WithTheme(styles.HuhTheme) - The package uses `charm.land/lipgloss/v2` and `charm.land/lipgloss/v2/compat` for adaptive color support. - For visual examples and detailed usage guidelines, see `scratchpad/styles-guide.md`. - All `*` styles export pre-configured `lipgloss.Style` values (not functions), so they can be used with method chaining: `styles.Error.Copy().Underline(true)`. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/testutil/README.md b/pkg/testutil/README.md index c458334fdaa..6bb1d45294b 100644 --- a/pkg/testutil/README.md +++ b/pkg/testutil/README.md @@ -60,3 +60,7 @@ assert.Contains(t, yaml, "runs-on: ubuntu-latest") - `GetTestRunDir` uses `sync.Once` so the directory is created exactly once per process even when multiple test packages run concurrently. - `TempDir` delegates to `os.MkdirTemp` to generate unique subdirectory names. - Test artifacts placed in the test run directory are outside any git repository, which prevents `git` commands executed by tests from picking them up as untracked files. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/timeutil/README.md b/pkg/timeutil/README.md index 4537652be2e..3e21a4e20b3 100644 --- a/pkg/timeutil/README.md +++ b/pkg/timeutil/README.md @@ -60,3 +60,7 @@ timeutil.FormatDurationNs(90_000_000_000) // "1m30s" - `FormatDuration` is used by the `logger` package to display time-diff between consecutive log calls (the `+500ms` suffix in debug output). - `FormatDurationMs` is used for workflow run duration display, where GitHub Actions reports durations in milliseconds. - `FormatDurationNs` is used for job duration display, where GitHub Actions reports billing durations in nanoseconds. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/types/README.md b/pkg/types/README.md index 28fd060c788..3086b018765 100644 --- a/pkg/types/README.md +++ b/pkg/types/README.md @@ -107,3 +107,7 @@ Per-token-class weights for effective token computation. Each field corresponds - This package has no dependencies on other `gh-aw` packages, making it safe to import from anywhere. - All struct fields use both `json` and `yaml` struct tags so they can be round-tripped through both serialization formats. - `BaseMCPServerConfig` is designed to be embedded — packages add domain-specific fields and validation on top of the shared base. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/typeutil/README.md b/pkg/typeutil/README.md index c4c6712470c..a0f60a19bbc 100644 --- a/pkg/typeutil/README.md +++ b/pkg/typeutil/README.md @@ -75,3 +75,7 @@ ratio := typeutil.ConvertToFloat(jsonData["ratio"]) - All debug output uses `logger.New("typeutil:convert")` and is only emitted when `DEBUG=typeutil:*`. - `float64 → int` truncation is logged at debug level when the fractional part is lost. - `uint64 → int` overflow returns `0` rather than panicking, following the defensive convention used elsewhere in the codebase. + +--- + +*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.* diff --git a/pkg/workflow/README.md b/pkg/workflow/README.md index 6b6612335dc..90abc88c80b 100644 --- a/pkg/workflow/README.md +++ b/pkg/workflow/README.md @@ -194,6 +194,7 @@ The package is intentionally large (~320 source files) because it encodes all Gi | `GetCopilotAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Copilot-specific allowed domains | | `GetCodexAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Codex-specific allowed domains | | `GetClaudeAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Claude-specific allowed domains | +| `GetGeminiAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Gemini-specific allowed domains | | `GetThreatDetectionAllowedDomains` | `func(*NetworkPermissions) string` | Allowed domains for threat detection jobs | ### Error Types @@ -240,6 +241,9 @@ The package is intentionally large (~320 source files) because it encodes all Gi | `GetActionPin` | `func(actionRepo string) string` | Returns the pinned SHA for an action | | `GetActionPinByRepo` | `func(string) (ActionPin, bool)` | Looks up a pin by repo | | `DetectActionMode` | `func(version string) ActionMode` | Detects the action reference mode | +| `ParseTagRefTSV` | `func(line string) (sha, objType string, err error)` | Parses tab-separated tag ref output into SHA and object type | +| `ExtractActionsFromLockFile` | `func(lockFilePath string) ([]ActionUsage, error)` | Extracts action usages from a lock file | +| `CheckActionSHAUpdates` | `func(actions []ActionUsage, resolver *ActionResolver) []ActionUpdateCheck` | Checks whether action SHAs need updates | | `ApplyActionPinsToTypedSteps` | `func([]*WorkflowStep, *WorkflowData) []*WorkflowStep` | Applies pins to all steps | | `ValidateActionSHAsInLockFile` | `func(string, *ActionCache, bool) error` | Validates action SHAs in a lock file | @@ -305,6 +309,8 @@ The package is intentionally large (~320 source files) because it encodes all Gi | `GetAWFCommandPrefix` | `func(*WorkflowData) string` | Returns the `gh aw` command prefix | | `WrapCommandInShell` | `func(string) string` | Wraps a command in a shell `run:` block | | `GetCopilotAPITarget` | `func(*WorkflowData) string` | Returns the Copilot API target URL | +| `GetGeminiAPITarget` | `func(*WorkflowData, string) string` | Returns the Gemini API target hostname | +| `ComputeAWFExcludeEnvVarNames` | `func(*WorkflowData, []string) []string` | Computes secret-backed env var names to exclude from AWF | ### Versioning @@ -442,6 +448,10 @@ pkg/workflow ── FrontmatterConfig (typed structs) - `pkg/constants` — engine names, feature flags, job/step IDs - `pkg/console` — terminal formatting - `pkg/logger` — debug logging +- `pkg/actionpins` — action pin data and pin lookup helpers +- `pkg/semverutil` — semantic version helpers +- `pkg/typeutil` — safe type conversions +- `pkg/tty` — terminal capability detection - `pkg/stringutil`, `pkg/fileutil`, `pkg/gitutil`, `pkg/sliceutil` — utilities - `pkg/types` — shared MCP types