more improvements

Author: ernestl

DESIGN.md

@@ -10,11 +10,12 @@ revmap is a read-only CLI tool that queries the Snap Store's dashboard API to di
 
 ```
 revmap/
-  main.go                 Entry point; embeds README, sets version via ldflags
+  main.go                 Entry point; embeds README and DESIGN, sets version via ldflags
   cache-snaps.json        Configuration: list of snaps to pre-cache
   cache/                  Generated cache files (gitignored)
   demo.sh                 Interactive demo script (invoked by demo command)
   test.sh                 Unified test runner (--unit, --static, --all)
+  version.sh              Single source of truth for version string
   cmd/
     root.go               Root Cobra command, group registration, command ordering
     version.go            Version resolution (ldflags or VCS fallback)
@@ -23,28 +24,26 @@ revmap/
     whoami.go             Account information display
     list.go               Revision listing with filters and table output
     show.go               Single revision detail view
-    cache.go              Cache-build subcommand (pre-build cache generation)
+    helpers.go            Shared utilities (cache fallback error detection)
     design.go             Embedded DESIGN display (rendered via glamour)
     readme.go             Embedded README display (rendered via glamour)
     demo.go               Demo subcommand (runs demo.sh)
-    design.go             Embedded DESIGN display (rendered via glamour)
-    readme.go             Embedded README display (rendered via glamour)
-    list_test.go           Tests for list logic
-    show_test.go           Tests for show logic
-    version_test.go        Tests for version logic
+    list_test.go          Tests for list logic
+    show_test.go          Tests for show logic
+    version_test.go       Tests for version logic
   cmd/cache-build/
     main.go               Standalone cache-build binary (separate main package)
   store/
     constants.go          API URLs and app-wide constants
     auth.go               Macaroon serialization, SSO discharge, login flow
     credentials.go        File-based credential storage with env var override
     account.go            Account info retrieval (whoami endpoint)
-    client.go             Authenticated HTTP client with auto-refresh
+    client.go             Authenticated HTTP client with connection pooling and auto-refresh
     revisions.go          Store API calls (revisions, releases with pagination)
     cache.go              Cache data structures, gzip read/write, file lookup
     auth_test.go          Tests for macaroon serialization and caveat extraction
     credentials_test.go   Tests for credential storage
-    client_test.go        Tests for refresh detection
+    client_test.go        Tests for client transport and refresh detection
 ```
 
 ## Command Groups
@@ -55,9 +54,7 @@ Commands are organized into three groups displayed in `--help` output. Sorting i
 - **Query:** list, show
 - **Learn:** readme, design, demo
 
-## Authentication
-
-### Version
+## Version
 
 The project produces two binaries (`revmap` and `cache-build`), both receiving the same version via ldflags at build time.
 
@@ -67,7 +64,7 @@ The project produces two binaries (`revmap` and `cache-build`), both receiving t
 
 Cobra's built-in `Version` field provides the `--version` flag automatically.
 
-### Macaroon Scheme
+## Authentication
 
 The Snap Store uses a two-macaroon authentication model:
 
@@ -188,7 +185,7 @@ A standalone binary (`cmd/cache-build/main.go`) that fetches the complete revisi
 
 Built by `make build` alongside the main binary, with the same version injected via ldflags. Supports `-version` to print its version.
 
-**Performance:** The HTTP client is created via `NewClientWithWorkers(n)` which configures a transport with `MaxIdleConnsPerHost` matching the worker count, ensuring TCP/TLS connections are reused across concurrent requests rather than being re-established.
+**Performance:** The HTTP client is created via `NewClientWithWorkers(n)` which configures a transport with `MaxIdleConnsPerHost` set to `n + 10`, ensuring TCP/TLS connections are reused across concurrent requests rather than being re-established.
 
 **Authentication:** If credentials already exist (user ran `revmap login` or `SNAPCRAFT_STORE_CREDENTIALS` is set), they are used directly. Otherwise, `cache-build` checks for `REVMAP_EMAIL` and `REVMAP_PASSWORD` environment variables and performs a non-interactive login via `store.Login(email, password, "")`. The OTP parameter is always empty — the account must not have two-factor authentication enabled. A 2FA-enabled account will return `ErrTwoFactorRequired`, surfaced as `"automatic login failed: two-factor authentication required"`.
 
@@ -267,6 +264,7 @@ All user-facing messages follow consistent conventions:
 | Package | Purpose |
 |---|---|
 | `github.com/spf13/cobra` | CLI framework |
+| `github.com/charmbracelet/glamour` | Terminal markdown rendering (readme/design commands) |
 | `golang.org/x/term` | Secure password input (no echo) |
 | `gopkg.in/macaroon.v1` | Macaroon creation, serialization, binding (matches snapd) |
 

README.md

@@ -172,12 +172,24 @@ The demo uses the snapd snap as an example and walks through
 list/show commands with various filters, including cache
 fallback.
 
+### readme / design
+
+Display documentation directly in the terminal, rendered with
+styled markdown (headers, code blocks, syntax highlighting):
+
+    revmap readme
+    revmap design
+
+The `design` command is particularly useful as context for
+coding agents before making contributions.
+
 ### cache-build
 
-Build the offline cache for all snaps in `cache-snaps.json`:
+`cache-build` is a standalone binary (not a revmap subcommand) that
+builds the offline cache for all snaps in `cache-snaps.json`:
 
-    revmap cache-build
-    revmap cache-build --workers 50
+    ./cache-build
+    ./cache-build -workers 50
 
 Requires authentication. See the Offline Cache section below
 for the full workflow.
@@ -223,7 +235,7 @@ snaps.
 
    Options:
 
-       revmap cache-build --workers 50
+       ./cache-build -workers 50
 
 3. Build the snap (cache is bundled automatically):
 
@@ -240,7 +252,7 @@ set environment variables instead:
 
     export REVMAP_EMAIL="user@example.com"
     export REVMAP_PASSWORD="secret"
-    revmap cache-build
+    ./cache-build
 
 The account **must not** have two-factor authentication (2FA)
 enabled. A 2FA-enabled account will fail with "two-factor
@@ -297,8 +309,8 @@ latest git tag. Check with:
 
     ./cache-build -version
 
-The `cache` target depends on `build` and runs
-`revmap cache-build`. You must be logged in first:
+The `cache` target runs `go run ./cmd/cache-build`.
+You must be logged in first:
 
     revmap login
     make cache

cmd/cache-build/main.go

@@ -4,11 +4,11 @@
 package main
 
 import (
+	"errors"
 	"flag"
 	"fmt"
 	"os"
 	"strconv"
-	"strings"
 	"sync"
 	"time"
 
@@ -133,7 +133,8 @@ func buildCacheForSnap(client *store.Client, snapName string, workers int) error
 			if err != nil {
 				// Skip 404s — some revisions in the releases list
 				// may have been deleted from the revision endpoint.
-				if strings.Contains(err.Error(), "status 404") {
+				var storeErr *store.StoreError
+				if errors.As(err, &storeErr) && storeErr.StatusCode == 404 {
 					mu.Lock()
 					if (idx+1)%100 == 0 {
 						fmt.Printf("    %d/%d details fetched\n", idx+1, len(releases.Revisions))

cmd/demo.go

@@ -24,6 +24,7 @@ using the snapd snap as an example. Requires authentication.
 The demo walks through various list and show commands,
 pausing between each for review. Use --no-pause to run
 without pauses.`,
+	Args: cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		script := findDemoScript()
 		if script == "" {

cmd/helpers.go

@@ -1,15 +1,20 @@
 package cmd
 
-import "strings"
+import (
+	"errors"
+
+	"github.com/ernestl/revmap/store"
+)
 
 // isCacheFallbackErr returns true if the error indicates a permission
 // or access issue (401, 403, 404) where falling back to cache is appropriate.
 func isCacheFallbackErr(err error) bool {
-	if err == nil {
-		return false
+	var storeErr *store.StoreError
+	if errors.As(err, &storeErr) {
+		switch storeErr.StatusCode {
+		case 401, 403, 404:
+			return true
+		}
 	}
-	msg := err.Error()
-	return strings.Contains(msg, "status 401") ||
-		strings.Contains(msg, "status 403") ||
-		strings.Contains(msg, "status 404")
+	return false
 }

cmd/list.go

@@ -103,9 +103,14 @@ func init() {
 	listCmd.Flags().StringVarP(&columns, "columns", "c", defaultColumns, "columns to display (comma-separated)")
 }
 
-// columnNames returns the sorted list of available column names.
+// columnNames returns the available column names in display order.
 func columnNames() string {
-	return "revision, version, arch, status, created, confinement, base, size"
+	names := make([]string, 0, len(allColumns))
+	for name := range allColumns {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return strings.Join(names, ", ")
 }
 
 var listCmd = &cobra.Command{
@@ -121,6 +126,9 @@ By default only the last 90 days are shown. Use --all to fetch
 complete history, or --limit/-n to fetch up to a specific number
 of revisions across all pages.
 
+Available columns: arch, base, confinement, created, revision, size, status, version.
+Build types: release, fips (comma-separated).
+
 Examples:
   revmap list snapd
   revmap list snapd --since 7d -a amd64
@@ -242,6 +250,8 @@ func listFromCache(snapName, reason string) error {
 
 // applyCacheTimeWindow filters cached revisions by the time window
 // and limit flags (same logic as FetchOptions but applied locally).
+// Revisions are sorted newest-first before applying limits so that
+// --limit returns the N most recent revisions.
 func applyCacheTimeWindow(revisions []store.RevisionEntry) []store.RevisionEntry {
 	opts, err := parseTimeWindow(since, until, limit, fetchAll)
 	if err != nil {
@@ -250,6 +260,11 @@ func applyCacheTimeWindow(revisions []store.RevisionEntry) []store.RevisionEntry
 		return revisions
 	}
 
+	// Sort newest-first before applying limits.
+	sort.Slice(revisions, func(i, j int) bool {
+		return revisions[i].Revision > revisions[j].Revision
+	})
+
 	var result []store.RevisionEntry
 	for _, rev := range revisions {
 		if !opts.Since.IsZero() || !opts.Until.IsZero() {

cmd/login.go

@@ -49,7 +49,8 @@ with snapcraft export-login output to skip interactive login.`,
 			return nil
 		}
 
-		if store.CredentialsExist() {
+		// Without --export, check if already logged in (file or env var).
+		if loginExportFile == "" && store.CredentialsExist() {
 			fmt.Println("You are already logged in. Run 'revmap logout' first to re-authenticate.")
 			return nil
 		}

cmd/readme.go

@@ -17,7 +17,10 @@ func SetReadme(content string) {
 var readmeCmd = &cobra.Command{
 	Use:   "readme",
 	Short: "Display the full README documentation",
-	Args:  cobra.NoArgs,
+	Long: `Display the full README rendered with terminal styling.
+Useful as a quick reference for available commands, flags,
+and workflows without leaving the terminal.`,
+	Args: cobra.NoArgs,
 	Run: func(cmd *cobra.Command, args []string) {
 		out, err := glamour.Render(embeddedReadme, "auto")
 		if err != nil {

cmd/show.go

@@ -25,6 +25,10 @@ Requires authentication. Run 'revmap login' first.
 If not authenticated or lacking permissions, cached data is
 used automatically when available.
 
+Without --fields, the full JSON response is displayed. Use -f to
+select specific fields from the revision object (e.g. version,
+status, architectures, created_at, base, confinement, size).
+
 Examples:
   revmap show snapd 17339
   revmap show snapd 17339 -f version,status,architectures`,

store/client.go

@@ -92,6 +92,8 @@ func (c *Client) Do(req *http.Request) (*http.Response, error) {
 
 // needsRefresh checks whether a 401 response contains the
 // "macaroon-needs-refresh" error code from the store.
+// It reads and restores the response body so the caller can
+// still consume it if this returns false.
 func needsRefresh(resp *http.Response) bool {
 	var body struct {
 		ErrorList []struct {
@@ -103,8 +105,9 @@ func needsRefresh(resp *http.Response) bool {
 		} `json:"error-list"`
 	}
 
-	// Read and parse the body to check for the refresh error code.
+	// Read the body, then restore it for the caller.
 	raw, err := io.ReadAll(resp.Body)
+	resp.Body = io.NopCloser(bytes.NewReader(raw))
 	if err != nil {
 		return false
 	}