Merge 0.10.4

Author: dahlia

CHANGES.md

@@ -37,6 +37,34 @@ To be released.
 [#120]: https://github.com/dahlia/optique/issues/120
 
 
+Version 0.10.4
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed `formatMessage()` to correctly handle a `lineBreak()` term that is
+    immediately followed by a newline character in the source template literal.
+    Previously, the newline after `${lineBreak()}` was normalized to a space
+    (as single `\n` characters in text terms are), producing a spurious leading
+    space at the start of the next line.  The newline immediately following a
+    `lineBreak()` term is now dropped instead of being converted to a space.
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as “selected”
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+[#121]: https://github.com/dahlia/optique/issues/121
+
+
 Version 0.10.3
 --------------
 
@@ -948,6 +976,25 @@ to generate Unix man pages that stay synchronized with parser definitions.
 [#77]: https://github.com/dahlia/optique/issues/77
 
 
+Version 0.9.10
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as “selected”
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+
 Version 0.9.9
 -------------
 
@@ -1471,6 +1518,25 @@ remotes) using [isomorphic-git].  [[#71], [#72]]
 [#72]: https://github.com/dahlia/optique/pull/72
 
 
+Version 0.8.16
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as “selected”
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+
 Version 0.8.15
 --------------
 
@@ -1903,6 +1969,25 @@ parsing strategies.
 [LogTape]: https://logtape.org/
 
 
+Version 0.7.18
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as “selected”
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+
 Version 0.7.17
 --------------
 

docs/concepts/messages.md

@@ -560,6 +560,13 @@ Examples:
   zsh:  eval "$(mycli completion zsh)"
 ~~~~
 
+Note that `lineBreak()` absorbs the newline that immediately follows it in a
+template literal.  In the example above, each `${lineBreak()}` is followed by
+a real newline character in the source, but that newline is dropped rather than
+being normalized to a space.  This means you can write multi-line template
+literals naturally—breaking the source line right after `${lineBreak()}`—and
+the output will not gain a spurious leading space on the next line.
+
 ### Single newlines (`\n`)
 
 Single newlines in `text()` terms are treated as soft breaks and converted to

docs/concepts/runners.md

@@ -1172,40 +1172,30 @@ Choose your execution strategy based on your application's needs.
 For guidance on whether to use `Program` objects or pass metadata directly,
 see [*Bundling parsers with metadata*](#bundling-parsers-with-metadata).
 
-### Use *@optique/run* when:
-
- -  Building CLI applications for Node.js, Bun, or Deno
- -  You want automatic `process.argv` parsing and `process.exit()` handling
- -  You need automatic terminal capability detection (colors, width)
- -  You prefer a simple, batteries-included approach
-
-### Use *@optique/core* instead when:
-
- -  Building web applications or libraries
- -  You need full control over argument sources and error handling
- -  Working in environments without `process` (browsers, web workers)
- -  Building reusable parser components
-
 ### Use `parse()` when:
 
  -  *Testing parsers*: You need to inspect parsing results in tests
  -  *Complex integration*: Parsing is part of a larger application flow
  -  *Custom error handling*: You need application-specific error recovery
  -  *Multiple attempts*: You want to try different parsers or arguments
+ -  *Reusable components*: Building parser components for use in libraries
+ -  *Environment constraints*: Running without `process` (browsers, web workers)
 
 ### Use `runParser()` from `@optique/core/facade` when:
 
  -  *Framework integration*: Working with web frameworks or custom runtimes
  -  *Library development*: Building CLI libraries for other applications
  -  *Custom I/O*: You need non-standard input/output handling
  -  *Controlled exit*: The application manages its own lifecycle
+ -  *Non-CLI contexts*: Building tools that embed a CLI interface in a larger app
 
 ### Use `run()` from `@optique/run` when:
 
- -  *Standalone CLIs*: Building command-line applications
+ -  *Standalone CLIs*: Building command-line applications for Node.js, Bun, or Deno
  -  *Rapid prototyping*: You want to get a CLI running quickly
  -  *Standard behavior*: Your application follows typical CLI conventions
- -  *Node.js/Bun/Deno*: You're running in a standard JavaScript runtime
+ -  *Batteries-included*: You want automatic argument extraction, terminal
+    detection, and process exit handling
 
 The progression from `parse()` to *@optique/run*'s `run()` trades control for
 convenience. Start with the highest-level approach that meets your needs, then

examples/gitique/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { or } from "@optique/core/constructs";
 import { defineProgram } from "@optique/core/program";
-import { commandLine, message, url } from "@optique/core/message";
+import { commandLine, lineBreak, message, url } from "@optique/core/message";
 import { printError, run } from "@optique/run";
 import { addCommand, executeAdd } from "./commands/add.ts";
 import { commitCommand, executeCommit } from "./commands/commit.ts";
@@ -48,21 +48,28 @@ const program = defineProgram({
     author: message`Hong Minhee ${url("https://hongminhee.org/")}`,
     examples: message`Common commands:
 
-  ${commandLine("gitique add .")}                     Stage all changes
-
-  ${commandLine('gitique commit -m "message"')}       Create a commit
-
-  ${commandLine("gitique status")}                    Show working tree status
-
-  ${commandLine("gitique log --oneline")}             View commit history
-
-  ${commandLine("gitique diff --cached")}             Show staged changes
+${
+      commandLine("gitique add .")
+    }                     Stage all changes${lineBreak()}
+${
+      commandLine('gitique commit -m "message"')
+    }       Create a commit${lineBreak()}
+${
+      commandLine("gitique status")
+    }                    Show working tree status${lineBreak()}
+${
+      commandLine("gitique log --oneline")
+    }             View commit history${lineBreak()}
+${
+      commandLine("gitique diff --cached")
+    }             Show staged changes${lineBreak()}
 
 Shell completion:
 
-  ${commandLine("gitique completion bash > ~/.bashrc.d/gitique.bash")}
-
-  ${commandLine("gitique completion zsh > ~/.zsh/completions/_gitique")}`,
+${
+      commandLine("gitique completion bash > ~/.bashrc.d/gitique.bash")
+    }${lineBreak()}
+${commandLine("gitique completion zsh > ~/.zsh/completions/_gitique")}`,
     footer: message`For more information, visit ${
       url("https://github.com/dahlia/optique")
     }.`,

packages/core/src/message.test.ts

@@ -921,6 +921,74 @@ describe("formatMessage - explicit line breaks", () => {
     // Multiple double newlines still create single paragraph break
     assert.equal(formatted, "Line 1\n\nLine 2");
   });
+
+  it("should strip leading newline from text immediately after lineBreak()", () => {
+    // When lineBreak() is followed by a text term starting with \n (as happens in
+    // template literals like `${lineBreak()}\nContent`), the leading \n must be
+    // dropped to avoid yielding an extra space.
+    const msg: Message = [
+      { type: "text", text: "Before" },
+      lineBreak(),
+      { type: "text", text: "\nAfter" },
+    ];
+    const formatted = formatMessage(msg, { quotes: false });
+
+    assert.equal(formatted, "Before\nAfter");
+  });
+
+  it("should strip leading newline but preserve remaining indentation after lineBreak()", () => {
+    // The leading \n must be stripped, but subsequent whitespace (indentation)
+    // must be preserved.
+    const msg: Message = [
+      { type: "text", text: "Before" },
+      lineBreak(),
+      { type: "text", text: "\n  indented" },
+    ];
+    const formatted = formatMessage(msg, { quotes: false });
+
+    assert.equal(formatted, "Before\n  indented");
+  });
+
+  it("should not add extra space between lineBreak() and commandLine() in template literal", () => {
+    // Regression test: template literals produce a text("\n") between lineBreak()
+    // and the next interpolated value.  That \n was being normalized to a space,
+    // creating a spurious leading space on the next line.
+    const msg = message`Common:${lineBreak()}
+${commandLine("myapp add .")}         Stage changes${lineBreak()}
+${commandLine("myapp status")}        Show status`;
+    const formatted = formatMessage(msg, { quotes: false });
+
+    const lines = formatted.split("\n");
+    assert.equal(lines.length, 3);
+    assert.equal(lines[0], "Common:");
+    assert.ok(
+      lines[1].startsWith("myapp add ."),
+      `Expected line to start with "myapp add .", got: ${
+        JSON.stringify(lines[1])
+      }`,
+    );
+    assert.ok(
+      lines[2].startsWith("myapp status"),
+      `Expected line to start with "myapp status", got: ${
+        JSON.stringify(lines[2])
+      }`,
+    );
+  });
+
+  it("should preserve paragraph break (\\n\\n) following lineBreak()", () => {
+    // A double newline after lineBreak() is an intentional paragraph separator
+    // and must NOT be stripped.  Only a lone \n (soft-break artifact) is absorbed.
+    const msg: Message = [
+      { type: "text", text: "Line 1" },
+      lineBreak(),
+      { type: "text", text: "\n\nSection header" },
+    ];
+    const formatted = formatMessage(msg, { quotes: false });
+
+    // lineBreak() yields one \n; the \n\n yields another \n (paragraph break);
+    // total: two \n before "Section header".
+    assert.equal(formatted, "Line 1\n\nSection header");
+  });
 });
 
 describe("valueSet", () => {

packages/core/src/message.ts

@@ -509,14 +509,30 @@ export function formatMessage(
 
   function* stream(): Generator<{ text: string; width: number }> {
     const wordPattern = /\s*\S+\s*/g;
+    let prevWasLineBreak = false;
     for (const term of msg) {
+      // Capture and reset before processing each term so non-text terms
+      // (e.g. optionName, commandLine) also clear the flag.
+      const isAfterLineBreak = prevWasLineBreak;
+      prevWasLineBreak = false;
+
       if (term.type === "text") {
+        // Strip a lone leading \n immediately following a lineBreak() term.
+        // In template literals such as `${lineBreak()}\nContent`, the parser
+        // produces a text("\n…") term; that \n is a source-formatting artifact
+        // that should be dropped rather than normalized to a space.
+        // Only a lone \n is stripped; \n\n (paragraph break) is intentional
+        // and must be preserved so the double-newline → hard-break logic works.
+        const rawText = isAfterLineBreak
+          ? term.text.replace(/^\n(?!\n)/, "")
+          : term.text;
+
         // Handle explicit line breaks:
         // - Single \n: treated as space (soft break, word wrap friendly)
         // - Double \n\n or more: treated as hard line break (paragraph break)
-        if (term.text.includes("\n\n")) {
+        if (rawText.includes("\n\n")) {
           // Split on double newlines to find paragraph breaks
-          const paragraphs = term.text.split(/\n\n+/);
+          const paragraphs = rawText.split(/\n\n+/);
           for (
             let paragraphIndex = 0;
             paragraphIndex < paragraphs.length;
@@ -538,7 +554,7 @@ export function formatMessage(
           }
         } else {
           // Text without double newlines: replace single \n with space
-          const normalizedText = term.text.replace(/\n/g, " ");
+          const normalizedText = rawText.replace(/\n/g, " ");
 
           // Handle whitespace-only text specially to preserve spaces
           if (normalizedText.trim() === "" && normalizedText.length > 0) {
@@ -627,6 +643,7 @@ export function formatMessage(
       } else if (term.type === "lineBreak") {
         // Explicit hard line break
         yield { text: "\n", width: -1 };
+        prevWasLineBreak = true;
       } else if (term.type === "url") {
         const urlString = term.url.href;
         const displayText = useQuotes ? `<${urlString}>` : urlString;