From 5a0a048fba392303b2f938cd05fb11da208e5b87 Mon Sep 17 00:00:00 2001
From: Tyler Butler <tyler@tylerbutler.com>
Date: Fri, 12 Jun 2026 16:19:28 -0700
Subject: [PATCH] feat: capture flag default values in help data

Add a default: Option(String) field to help.Flag and populate it from
each flag's configured default via flag_default_info (with a join_csv
helper for list flags). Foundation for rendering defaults in --help and
for the public document tree.
---
 CHANGELOG.md                  |  3 +++
 src/glint.gleam               | 24 ++++++++++++++++++++++++
 src/glint/internal/help.gleam |  4 ++--
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 573dbc3..57335a0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## [Unreleased](https://github.com/TanklesXL/glint/compare/v1.1.0...HEAD)
 
+- captured each flag's configured default value in the help data
+  (`help.Flag.default`)
+
 # v1
 
 ## [1.3.0](https://github.com/TanklesXL/glint/compare/v1.2.1...v1.3.0)
diff --git a/src/glint.gleam b/src/glint.gleam
index 5ba3494..8968495 100644
--- a/src/glint.gleam
+++ b/src/glint.gleam
@@ -729,6 +729,29 @@ fn flag_type_info(flag: FlagEntry) {
   }
 }
 
+fn flag_default_info(flag: FlagEntry) -> Option(String) {
+  case flag.value {
+    I(FlagInternals(value: Some(v), ..)) -> Some(int.to_string(v))
+    F(FlagInternals(value: Some(v), ..)) -> Some(float.to_string(v))
+    S(FlagInternals(value: Some(v), ..)) -> Some(v)
+    B(FlagInternals(value: Some(v), ..)) ->
+      Some(case v {
+        True -> "true"
+        False -> "false"
+      })
+    LI(FlagInternals(value: Some(v), ..)) -> Some(join_csv(v, int.to_string))
+    LF(FlagInternals(value: Some(v), ..)) -> Some(join_csv(v, float.to_string))
+    LS(FlagInternals(value: Some(v), ..)) -> Some(string.join(v, ","))
+    _ -> None
+  }
+}
+
+/// stringify each item and join with commas, for list-flag defaults.
+///
+fn join_csv(items: List(a), to_string: fn(a) -> String) -> String {
+  items |> list.map(to_string) |> string.join(",")
+}
+
 /// build the help representation for a list of flags
 ///
 fn build_flags_help(flags: Flags) -> List(help.Flag) {
@@ -737,6 +760,7 @@ fn build_flags_help(flags: Flags) -> List(help.Flag) {
     help.Flag(
       meta: help.Metadata(name: name, description: flag.description),
       type_: flag_type_info(flag),
+      default: flag_default_info(flag),
     ),
     ..acc
   ]
diff --git a/src/glint/internal/help.gleam b/src/glint/internal/help.gleam
index f1ec672..0778f27 100644
--- a/src/glint/internal/help.gleam
+++ b/src/glint/internal/help.gleam
@@ -20,7 +20,7 @@ fn heading_style(heading: String, colour: Colour) -> String {
 
 // --- HELP: CONSTANTS ---
 //
-pub const help_flag = Flag(Metadata("help", "Print help information"), "")
+pub const help_flag = Flag(Metadata("help", "Print help information"), "", None)
 
 const flags_heading = "FLAGS:"
 
@@ -61,7 +61,7 @@ pub type Metadata {
 /// Help type for flag metadata
 ///
 pub type Flag {
-  Flag(meta: Metadata, type_: String)
+  Flag(meta: Metadata, type_: String, default: Option(String))
 }
 
 /// Help type for command metadata