argsbarg 7.0.10 → 7.0.11

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.11] - 2026-09-16
+
+### Fixed
+
+- **Help table box sizing and wrapping** — fixed an off-by-two sizing bug in TTY help rendering where table rows wrapped their description column based on `hw - 2` instead of the inner content width `hw - 4`. This caused long table lines to exceed the terminal width and the box borders by up to 2 columns, resulting in the trailing border character `│` wrapping onto a new line in terminals matching `stdout.columns`.
+
 ## [7.0.10] - 2026-09-16
 
 ### Added
@@ -1010,7 +1016,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.10...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.11...HEAD
+[7.0.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.11
 [7.0.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.10
 [7.0.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.9
 [7.0.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.0.10",
+  "version": "7.0.11",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/help.test.ts

@@ -12,6 +12,7 @@ import {
   cliPositionalLabel,
   cliResolveNotes,
   schemaToYamlLines,
+  visibleWidth,
 } from "./help.ts";
 import { testProgram } from "./test/fixtures.ts";
 
@@ -214,6 +215,41 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("Output Schema");
   });
 
+  /** Tests that TTY help table boxes constrain line lengths to terminal width without wrapping border characters. */
+  test("TTY help table boxes fit terminal width without overflow", () => {
+    const origColumns = process.stdout.columns;
+    try {
+      process.stdout.columns = 120;
+      const root = testProgram({
+        key: "doc",
+        version: "1.0.0",
+        description: "Test application.",
+        commands: [
+          {
+            key: "query",
+            description:
+              "Query the body tape. Prints apply-shaped YAML `{ documentId, tabs: [{ tabId, ops: [], nodes }] }` (or JSON with --json). Fill ops and pipe to apply.",
+            handler: () => {},
+          },
+          {
+            key: "markdown-insert",
+            description:
+              "Insert markdown into a Google Doc tab as native DOM elements (headings, lists, code, tables).",
+            handler: () => {},
+          },
+        ],
+      });
+      const help = cliHelpRender(cliPresentationRoot(root), [], false, { isTTY: true });
+      const boxLines = help.split("\n").filter((l) => l.includes("╭") || l.includes("│") || l.includes("╰"));
+      expect(boxLines.length).toBeGreaterThan(0);
+      for (const line of boxLines) {
+        expect(visibleWidth(line)).toBe(120);
+      }
+    } finally {
+      process.stdout.columns = origColumns;
+    }
+  });
+
   /** Tests that non-TTY help automatically includes output schema in YAML by default. */
   test("non-TTY help automatically includes output schema in YAML by default", () => {
     const root = testProgram({

package/src/help.ts

@@ -82,7 +82,7 @@ function isOutputTTY(useStderr: boolean): boolean {
 // ── Width Helpers ─────────────────────────────────────────────────────────────
 
 /** Counts display columns, skipping ANSI SGR sequences. */
-function visibleWidth(s: string): number {
+export function visibleWidth(s: string): number {
   let w = 0;
   let i = 0;
   while (i < s.length) {
@@ -230,19 +230,26 @@ interface HelpRow {
 }
 
 /** Renders a free-text or notes box with a Unicode border and `title` header. */
-function renderTextBox(title: string, lines: string[], hw: number, color: boolean): string[] {
+function renderTextBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Lines of text to display inside the box. */
+  lines: string[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (lines.length === 0) return [];
 
   const titleLead = color
     ? style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ")
     : `${kBoxH} ${title} `;
 
-  let contentWidth = visibleWidth(titleLead) + 1;
+  let contentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
   for (const line of lines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.max(hw - 2, contentWidth);
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));
@@ -265,7 +272,16 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
 }
 
 /** Renders a two-column label/description table in a box (options, subcommands, positionals). */
-function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boolean): string[] {
+function renderTableBox(
+  /** Section title to render in the top border. */
+  title: string,
+  /** Table rows containing labels and descriptions to format. */
+  rows: HelpRow[],
+  /** Available terminal column width. */
+  hw: number,
+  /** Whether ANSI color styling is enabled. */
+  color: boolean,
+): string[] {
   if (rows.length === 0) return [];
 
   let labelWidth = 0;
@@ -273,10 +289,15 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     labelWidth = Math.max(labelWidth, visibleWidth(row.label));
   }
 
-  const titleChunk = `${kBoxH} ${title} `;
-  const minimumContentWidth = Math.max(visibleWidth(titleChunk) + 1, labelWidth + 2 + 18);
-  let contentWidth = Math.max(hw - 2, minimumContentWidth);
-  const descWidth = Math.max(1, contentWidth - labelWidth - 2);
+  let titleLead: string;
+  if (color) {
+    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
+  } else {
+    titleLead = `${kBoxH} ${title} `;
+  }
+
+  const targetContentWidth = Math.max(visibleWidth(titleLead) + 1, hw - 4);
+  const descWidth = Math.max(1, targetContentWidth - labelWidth - 2);
 
   const bodyLines: string[] = [];
   for (const row of rows) {
@@ -289,18 +310,10 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     }
   }
 
-  let titleLead: string;
-  if (color) {
-    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
-  } else {
-    titleLead = `${kBoxH} ${title} `;
-  }
-
-  contentWidth = Math.max(contentWidth, visibleWidth(titleLead) + 1);
+  let contentWidth = targetContentWidth;
   for (const line of bodyLines) {
     contentWidth = Math.max(contentWidth, visibleWidth(line));
   }
-  contentWidth = Math.min(contentWidth, hw - 4);
 
   const borderWidth = contentWidth + 2;
   const headerFill = Math.max(1, borderWidth - visibleWidth(titleLead));