From 86bcc099bd2def986118327895fbe4afc9b8ad15 Mon Sep 17 00:00:00 2001
From: Christer <christer@serverpod.dev>
Date: Mon, 20 Oct 2025 12:12:08 +0200
Subject: [PATCH 1/2] fix(cli_tools): Enclose option help in quotes

In the carapace yaml generator, ensure the option help text is formatted with quotes/escapes to that it is correct yaml format.
---
 .../completion/carapace_generator.dart               | 12 ++++++++++--
 .../test/better_command_runner/completion_test.dart  | 10 +++++-----
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart b/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
index db883d3..d1a3791 100644
--- a/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
+++ b/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
@@ -113,17 +113,19 @@ class CarapaceYamlGenerator implements UsageRepresentationGenerator {
       attributes += '!';
     }
 
+    final optionHelp = _formatYamlStringValue(option.helpText ?? '');
     _writeWithIndent(
       out,
-      '${names.join(', ')}$attributes: ${option.helpText ?? ''}',
+      '${names.join(', ')}$attributes: $optionHelp',
       indentLevel,
     );
 
     if (option case final FlagOption flagOption) {
       if (flagOption.negatable && !flagOption.hideNegatedUsage) {
+        final optionHelp = _formatYamlStringValue(option.helpText ?? '');
         _writeWithIndent(
           out,
-          '--no-${option.argName}$attributes: ${option.helpText ?? ''}',
+          '--no-${option.argName}$attributes: $optionHelp',
           indentLevel,
         );
       }
@@ -191,4 +193,10 @@ class CarapaceYamlGenerator implements UsageRepresentationGenerator {
         return [];
     }
   }
+
+  static String _formatYamlStringValue(final String value) {
+    // escape special characters
+    final str = value.replaceAll(r'\', r'\\').replaceAll(r'"', r'\"');
+    return '"$str"';
+  }
 }
diff --git a/packages/cli_tools/test/better_command_runner/completion_test.dart b/packages/cli_tools/test/better_command_runner/completion_test.dart
index 822ee56..c2fcf39 100644
--- a/packages/cli_tools/test/better_command_runner/completion_test.dart
+++ b/packages/cli_tools/test/better_command_runner/completion_test.dart
@@ -153,16 +153,16 @@ void main() {
             r'# yaml-language-server: $schema=https://carapace.sh/schemas/command.json',
             'name: test',
             'persistentFlags:',
-            '  -q, --quiet: Suppress all cli output. Is overridden by  -v, --verbose.',
-            '  -v, --verbose: Prints additional information useful for development. Overrides --q, --quiet.',
+            '  -q, --quiet: "Suppress all cli output. Is overridden by  -v, --verbose."',
+            '  -v, --verbose: "Prints additional information useful for development. Overrides --q, --quiet."',
             'commands:',
             '  - name: completion',
             '    commands:',
             '      - name: generate',
             '      flags:',
-            '        -t, --target=!: The target tool format',
-            '        -e, --exec-name=: Override the name of the executable',
-            '        -f, --file=: Write the specification to a file instead of stdout',
+            '        -t, --target=!: "The target tool format"',
+            '        -e, --exec-name=: "Override the name of the executable"',
+            '        -f, --file=: "Write the specification to a file instead of stdout"',
             '      completion:',
             '        flag:',
             '          target: ["completely", "carapace"]',

From da2a1219db8f5fae1e463bf3e761ccd878894a6a Mon Sep 17 00:00:00 2001
From: Christer <christer@serverpod.dev>
Date: Mon, 20 Oct 2025 16:54:06 +0200
Subject: [PATCH 2/2] fix(cli_tools): Fixes according to review

---
 .../completion/carapace_generator.dart                   | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart b/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
index d1a3791..5605635 100644
--- a/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
+++ b/packages/cli_tools/lib/src/better_command_runner/completion/carapace_generator.dart
@@ -122,7 +122,6 @@ class CarapaceYamlGenerator implements UsageRepresentationGenerator {
 
     if (option case final FlagOption flagOption) {
       if (flagOption.negatable && !flagOption.hideNegatedUsage) {
-        final optionHelp = _formatYamlStringValue(option.helpText ?? '');
         _writeWithIndent(
           out,
           '--no-${option.argName}$attributes: $optionHelp',
@@ -195,8 +194,12 @@ class CarapaceYamlGenerator implements UsageRepresentationGenerator {
   }
 
   static String _formatYamlStringValue(final String value) {
-    // escape special characters
-    final str = value.replaceAll(r'\', r'\\').replaceAll(r'"', r'\"');
+    final str = value
+        .replaceAll(r'\', r'\\')
+        .replaceAll(r'"', r'\"')
+        .replaceAll('\n', r'\n')
+        .replaceAll('\t', r'\t')
+        .replaceAll('\r', r'\r');
     return '"$str"';
   }
 }