effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/unstable/cli/CliOutput.ts

@@ -409,6 +409,8 @@ const renderTable = (rows: ReadonlyArray<Row>, widthCap: number) => {
   return rows.map(({ left, right }) => `  ${pad(left, col)}${right}`).join("\n")
 }
 
+const formatSubcommandName = (name: string, alias: string | undefined): string => alias ? `${name}, ${alias}` : name
+
 /**
  * Color functions interface for help formatting.
  * @internal
@@ -497,16 +499,83 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
     sections.push("")
   }
 
+  // Global Flags section
+  if (doc.globalFlags && doc.globalFlags.length > 0) {
+    sections.push(colors.bold("GLOBAL FLAGS"))
+
+    const globalFlagRows: Array<Row> = doc.globalFlags.map((flag) => {
+      const names: Array<string> = []
+
+      // Add main name with -- prefix first
+      names.push(colors.green(`--${flag.name}`))
+
+      // Add aliases after (like -f) to match expected ordering
+      for (const alias of flag.aliases) {
+        names.push(colors.green(alias))
+      }
+
+      const namesPart = names.join(", ")
+      const typePart = flag.type !== "boolean" ? ` ${colors.dim(flag.type)}` : ""
+
+      return {
+        left: namesPart + typePart,
+        right: flag.description ?? ""
+      }
+    })
+
+    sections.push(renderTable(globalFlagRows, 30))
+    sections.push("")
+  }
+
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
-    sections.push(colors.bold("SUBCOMMANDS"))
+    const ungrouped = doc.subcommands.find((group) => group.group === undefined)
+
+    if (ungrouped) {
+      sections.push(colors.bold("SUBCOMMANDS"))
+      sections.push(renderTable(
+        ungrouped.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      if (doc.subcommands.length > 1) {
+        sections.push("")
+      }
+    }
 
-    const subcommandRows: Array<Row> = doc.subcommands.map((sub) => ({
-      left: colors.cyan(sub.name),
-      right: sub.description
-    }))
+    for (const group of doc.subcommands) {
+      if (group.group === undefined) continue
+      sections.push(colors.bold(`${group.group}:`))
+      sections.push(renderTable(
+        group.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      sections.push("")
+    }
+  }
 
-    sections.push(renderTable(subcommandRows, 20))
+  // Examples section
+  if (doc.examples && doc.examples.length > 0) {
+    sections.push(colors.bold("EXAMPLES"))
+
+    let first = true
+    let previousHadDescription = false
+    for (const example of doc.examples) {
+      if (example.description) {
+        if (!first) sections.push("")
+        sections.push(`  ${colors.dim(`# ${example.description}`)}`)
+      } else if (previousHadDescription) {
+        sections.push("")
+      }
+      sections.push(`  ${colors.cyan(example.command)}`)
+      first = false
+      previousHadDescription = !!example.description
+    }
     sections.push("")
   }