glacier

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

Go Report Card Static Badge Static Badge

Glacier is a Go framework that handles the plumbing so you can focus on what's yours. Like a glacier that shapes the landscape beneath the surface, Glacier is stable, deep, and predictable about the messy parts: argument parsing, configuration layering, lifecycle and signal handling, mock-driven testing, and HTTP transport faking. You write the logic. Glacier handles the rest.

Status

Glacier is in early design. The repo currently holds the development lifecycle and the brand identity. Code lands as component specs are accepted.

Glacier SDK

The Glacier SDK is a CLI binary, glacier, built on every Glacier framework package. It is the framework's longest-running integration test and the fastest way to start a new Glacier project.

Install

go install github.com/nathanbrophy/glacier/cmd/glacier@latest

Requires Go 1.25 or later. Confirm the binary is on your PATH:

glacier version

Commands

Command Group Description
glacier init CREATE Scaffold a new Glacier project
glacier new CREATE Add a package, command, or option to an existing project
glacier generate DEVELOP Run code generators (cli, mock, httpmock)
glacier lint DEVELOP gofmt, vet, staticcheck, and Glacier-specific lints
glacier test DEVELOP Live status panel and aggregated summary
glacier version INSPECT Print version; --check compares against latest
glacier explain INSPECT Explain a marker, exit code, or config key
glacier vibe UTILITY Glacier vibes animation
glacier completions UTILITY Shell completions (bash, zsh, fish, pwsh)

Color and logging

Color is on by default. Pass --no-color or set NO_COLOR to disable. Pass --force-color to keep color when piping to less -R. The default log level is Warn; use -V for Debug or --very-verbose for Trace.

Why dogfood

Every Glacier framework package is exercised by at least one SDK command. A Lynx-owned coverage row fails CI if any package falls out of use.

Read the SDK docs

The Promise

When you use Glacier, you should be able to say each of these truthfully:

  1. "I'm only writing what's mine."
  2. "I trust the defaults."
  3. "The error tells me what to do next."
  4. "Tests are easy because the framework helps."

Every component spec is reviewed against these four statements. If a design doesn't deliver them, the design is wrong.

License

License will be selected when the first code spec lands.

Documentation

Overview

Package glacier is the umbrella for the Glacier Go framework : a curated suite of consumable libraries that make Go development easy and just work.

Glacier ships fourteen packages organized in three tiers (kernel / mid / leaves) with no cyclic dependencies. The full architecture is documented in the framework-shape spec at specs/0002-framework-shape.md.

Less plumbing. More Go.

Example

Example shows the umbrella package's role: it is a documentation anchor for the framework. Users import the leaf packages directly (errs, conf, cli, mock, httpmock, term, fixture, ...). The root package itself has no callable surface; see specs/0002-framework-shape.md for the layered dependency map. 

package main

import (
	"fmt"

	"github.com/nathanbrophy/glacier/errs"
)

func main() {
	err := errs.Sentinel("example: synthetic")
	fmt.Println(err.Error())
}

Output:
example: synthetic

Source Files

View all Source files

Directories

Path Synopsis
Package assert provides Glacier's test assertions and runtime Must helpers.
 Package assert provides Glacier's test assertions and runtime Must helpers.
require
Package require mirrors every assertion in the parent assert package with t.Fatal semantics so a failing assertion immediately halts the test.
 Package require mirrors every assertion in the parent assert package with t.Fatal semantics so a failing assertion immediately halts the test.
Package cache is Glacier's generic key-value cache.
 Package cache is Glacier's generic key-value cache.
cli
Package cli is a first-class, gold-standard CLI builder : designed for any consumer building a CLI in Go, not as plumbing for Glacier's own SDK binary.
 Package cli is a first-class, gold-standard CLI builder : designed for any consumer building a CLI in Go, not as plumbing for Glacier's own SDK binary.
gen
Package gen is the codegen library for the Glacier CLI builder.
 Package gen is the codegen library for the Glacier CLI builder.
cmd
cligen command
Command cligen is the Glacier CLI code generator.
 Command cligen is the Glacier CLI code generator.
glacier command
Command glacier is the Glacier SDK binary.
 Command glacier is the Glacier SDK binary.
glacier/commands
Package commands implements the nine Glacier SDK commands.
 Package commands implements the nine Glacier SDK commands.
glacier/internal/benchcmp
Package benchcmp parses Go benchmark output and compares results against a stored baseline file.
 Package benchcmp parses Go benchmark output and compares results against a stored baseline file.
glacier/internal/castgen
Package castgen records terminal sessions of the SDK binary into asciinema v2 .cast files and renders a static .svg snapshot of the final frame.
 Package castgen records terminal sessions of the SDK binary into asciinema v2 .cast files and renders a static .svg snapshot of the final frame.
glacier/internal/castgen/cmd command
Command castgen records terminal sessions of the SDK and writes both asciinema v2 .cast files and self-contained .svg snapshots under site/public/casts/.
 Command castgen records terminal sessions of the SDK and writes both asciinema v2 .cast files and self-contained .svg snapshots under site/public/casts/.
glacier/internal/completions
Package completions provides shell-completion scripts for the glacier binary.
 Package completions provides shell-completion scripts for the glacier binary.
glacier/internal/explain
Package explain provides structured reference topics for the glacier explain command.
 Package explain provides structured reference topics for the glacier explain command.
glacier/internal/explaingen
Package explaingen is the build-time generator that renders explain topic files from accepted spec sections.
 Package explaingen is the build-time generator that renders explain topic files from accepted spec sections.
glacier/internal/explaingen/cmd command
explaingen is the build-time tool that renders explain topic files from accepted spec sections.
 explaingen is the build-time tool that renders explain topic files from accepted spec sections.
glacier/internal/figgen
Package figgen renders project-name banners in a block-character style inspired by ANSI Shadow figlet font.
 Package figgen renders project-name banners in a block-character style inspired by ANSI Shadow figlet font.
glacier/internal/ghreleases
Package ghreleases fetches release metadata from the GitHub Releases API using the Glacier httpc package.
 Package ghreleases fetches release metadata from the GitHub Releases API using the Glacier httpc package.
glacier/internal/mascots
Package mascots provides the curated library of six Glacier mascots.
 Package mascots provides the curated library of six Glacier mascots.
glacier/internal/profile
Package profile provides a one-call helper for enabling pprof CPU, heap, and goroutine profiling.
 Package profile provides a one-call helper for enabling pprof CPU, heap, and goroutine profiling.
glacier/internal/report
Package report writes kaomoji-prefixed status lines to a configurable writer.
 Package report writes kaomoji-prefixed status lines to a configurable writer.
glacier/internal/sdkerr
Package sdkerr defines SDK-internal error types and sentinel values.
 Package sdkerr defines SDK-internal error types and sentinel values.
glacier/internal/shimmer
Package shimmer renders the "GLACIER" wordmark with a scrolling aurora gradient per spec 0032 D-S58.
 Package shimmer renders the "GLACIER" wordmark with a scrolling aurora gradient per spec 0032 D-S58.
glacier/internal/vibetips
Package vibetips provides the 12-tip registry shown by glacier vibe.
 Package vibetips provides the 12-tip registry shown by glacier vibe.
Package concur is the Glacier answer to "I need a Mutex / errgroup / semaphore / sync.Pool / sync.Once / sync.WaitGroup : but ctx-aware, observable, and friendly to Glacier's error story." Production builds are byte-equivalent to stdlib equivalents where possible (zero overhead is the rule, not an aspiration).
 Package concur is the Glacier answer to "I need a Mutex / errgroup / semaphore / sync.Pool / sync.Once / sync.WaitGroup : but ctx-aware, observable, and friendly to Glacier's error story." Production builds are byte-equivalent to stdlib equivalents where possible (zero overhead is the rule, not an aspiration).
Package conf is the Glacier answer to "I have a few config sources (defaults, JSON file, env vars, flags) and a few struct-shaped config values I want them to populate." Two complementary APIs: a registration pattern where packages declare typed config structs with sensible defaults and conf.Load walks every registered struct and populates from layered sources; and a one-shot Decode[T] for programs with a single root config struct.
 Package conf is the Glacier answer to "I have a few config sources (defaults, JSON file, env vars, flags) and a few struct-shaped config values I want them to populate." Two complementary APIs: a registration pattern where packages declare typed config structs with sensible defaults and conf.Load walks every registered struct and populates from layered sources; and a one-shot Decode[T] for programs with a single root config struct.
Package errs provides the helpers underlying Glacier's error story: chain-preserving wrapping with optional stack capture, nil-aware joining, tree-walking iteration, library-register-validating sentinels, multi-target matching, retry markers, and stable error codes.
 Package errs provides the helpers underlying Glacier's error story: chain-preserving wrapping with optional stack capture, nil-aware joining, tree-walking iteration, library-register-validating sentinels, multi-target matching, retry markers, and stable error codes.
Package fixture provides test-resource management : the catch-all for everything tests need beyond stdlib testing and Glacier's assert package.
 Package fixture provides test-resource management : the catch-all for everything tests need beyond stdlib testing and Glacier's assert package.
Package fluent is Glacier's LINQ-equivalent: chainable, lazy, composable operators over Go 1.23+ iterators (iter.Seq[T] and iter.Seq2[K, V]).
 Package fluent is Glacier's LINQ-equivalent: chainable, lazy, composable operators over Go 1.23+ iterators (iter.Seq[T] and iter.Seq2[K, V]).
Package httpc is a first-class HTTP client wrapper around stdlib *http.Client.
 Package httpc is a first-class HTTP client wrapper around stdlib *http.Client.
Package httpmock provides a programmable http.RoundTripper for testing code that uses *http.Client.
 Package httpmock provides a programmable http.RoundTripper for testing code that uses *http.Client.
gen
Package gen is the codegen library for the Glacier httpmock package.
 Package gen is the codegen library for the Glacier httpmock package.
internal
lockfile
Package lockfile provides cooperative cross-process advisory file locking.
 Package lockfile provides cooperative cross-process advisory file locking.
reflectx
Package reflectx provides reflection helpers shared by mock, fluent, and conf.
 Package reflectx provides reflection helpers shared by mock, fluent, and conf.
safefile
Package safefile provides path-canonicalization and safe file-open helpers used by fixture/ to prevent path-traversal attacks on test-data directories.
 Package safefile provides path-canonicalization and safe file-open helpers used by fixture/ to prevent path-traversal attacks on test-data directories.
safejson
Package safejson wraps encoding/json with security guards for untrusted input.
 Package safejson wraps encoding/json with security guards for untrusted input.
sigh
Package sigh wires OS signals into the context lifecycle.
 Package sigh wires OS signals into the context lifecycle.
Package log provides Glacier's slog conventions: default text and JSON handlers with stable attribute ordering and TTY-aware color, two extra levels (Trace and Notice), context-based attribute attachment, explicit logger injection and retrieval, and a Redact helper for secret marking.
 Package log provides Glacier's slog conventions: default text and JSON handlers with stable attribute ordering and TTY-aware color, two extra levels (Trace and Notice), context-based attribute attachment, explicit logger injection and retrieval, and a Redact helper for secret marking.
Package mock provides interface mocking for tests in two complementary modes.
 Package mock provides interface mocking for tests in two complementary modes.
gen
Package gen is the codegen library for the Glacier mock package.
 Package gen is the codegen library for the Glacier mock package.
Package obs provides Glacier's OpenTelemetry-based observability : metrics and traces.
 Package obs provides Glacier's OpenTelemetry-based observability : metrics and traces.
Package option provides the canonical functional-options framework used by every Glacier package configurable at construction.
 Package option provides the canonical functional-options framework used by every Glacier package configurable at construction.
Package term provides Glacier's terminal-interaction layer: TTY capability detection, ANSI color and style primitives (with NO_COLOR and GLACIER_NO_COLOR support), Unicode glyph registry with ASCII fallback, beauty-writer helpers (box layout, alignment, text wrapping, column formatting, banner rendering), interactive prompts (text, password, confirm, select, multi-select), and the Animator : a coordinating frame-loop that renders progress bars and spinners while buffering log output above the animation so log lines never tear the display.
 Package term provides Glacier's terminal-interaction layer: TTY capability detection, ANSI color and style primitives (with NO_COLOR and GLACIER_NO_COLOR support), Unicode glyph registry with ASCII fallback, beauty-writer helpers (box layout, alignment, text wrapping, column formatting, banner rendering), interactive prompts (text, password, confirm, select, multi-select), and the Animator : a coordinating frame-loop that renders progress bars and spinners while buffering log output above the animation so log lines never tear the display.
Package tests holds integration-level verification tests for the Glacier SDK spec (0032).
 Package tests holds integration-level verification tests for the Glacier SDK spec (0032).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.