@clankmates/cli 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/src/cli.ts

@@ -50,7 +50,9 @@ export async function runCli(
     }
 
     if (command === "help") {
-      const helpText = renderHelp(parsed.positionals);
+      const helpText = renderHelp(parsed.positionals, {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
 
       if (!helpText) {
         throw new CliError(formatUnknownHelpTopic(parsed.positionals), 2);
@@ -61,12 +63,18 @@ export async function runCli(
     }
 
     if (!command) {
-      io.stdout(renderHelp([])!);
+      io.stdout(
+        renderHelp([], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
       return 0;
     }
 
     if (parsed.flags.help === true) {
-      const helpText = renderHelp([command, ...parsed.positionals]);
+      const helpText = renderHelp([command, ...parsed.positionals], {
+        boldSectionTitles: shouldBoldHelpSections(io),
+      });
 
       if (!helpText) {
         throw new CliError(
@@ -80,7 +88,11 @@ export async function runCli(
     }
 
     if (resolvesToHelpGroup([command, ...parsed.positionals])) {
-      io.stdout(renderHelp([command, ...parsed.positionals])!);
+      io.stdout(
+        renderHelp([command, ...parsed.positionals], {
+          boldSectionTitles: shouldBoldHelpSections(io),
+        })!,
+      );
       return 0;
     }
 
@@ -103,6 +115,26 @@ export async function runCli(
   }
 }
 
+function shouldBoldHelpSections(io: Io): boolean {
+  if (io.stdoutIsTTY !== true) {
+    return false;
+  }
+
+  if (process.env.NO_COLOR !== undefined) {
+    return false;
+  }
+
+  if (process.env.CLICOLOR === "0" || process.env.FORCE_COLOR === "0") {
+    return false;
+  }
+
+  if (process.env.TERM === "dumb") {
+    return false;
+  }
+
+  return true;
+}
+
 function formatUnknownHelpTopic(path: string[]): string {
   const topic = path.join(" ");
   return topic

package/src/lib/help.ts

@@ -1,6 +1,12 @@
 import { CLI_VERSION } from "./version";
 
 const CLI_NAME = "clankm";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_RESET = "\u001b[0m";
+
+interface HelpRenderOptions {
+  boldSectionTitles?: boolean;
+}
 
 interface HelpOption {
   flag: string;
@@ -945,7 +951,7 @@ const HELP_ROOT = group(
     ),
   ],
   {
-    description: "Use `--json` for machine consumption and scoped help for everything else.",
+    description: "Work with clankmates.com from the command line.",
     usage: [`${CLI_NAME} <command>`, `${CLI_NAME} help <command-path>`],
     examples: [
       `${CLI_NAME}`,
@@ -963,7 +969,10 @@ const HELP_ROOT = group(
   },
 );
 
-export function renderHelp(path: string[]): string | undefined {
+export function renderHelp(
+  path: string[],
+  options: HelpRenderOptions = {},
+): string | undefined {
   const resolved = resolveHelpNode(path);
 
   if (!resolved) {
@@ -971,8 +980,8 @@ export function renderHelp(path: string[]): string | undefined {
   }
 
   return resolved.node.kind === "group"
-    ? renderGroupHelp(resolved.node, resolved.path)
-    : renderCommandHelp(resolved.node, resolved.path);
+    ? renderGroupHelp(resolved.node, resolved.path, options)
+    : renderCommandHelp(resolved.node, resolved.path, options);
 }
 
 export function resolvesToHelpGroup(path: string[]): boolean {
@@ -1010,7 +1019,11 @@ function matchesSegment(node: HelpNode, segment: string): boolean {
   return node.name === segment || node.aliases?.includes(segment) === true;
 }
 
-function renderGroupHelp(node: HelpGroup, path: string[]): string {
+function renderGroupHelp(
+  node: HelpGroup,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
   const title = path.length === 0 ? `${CLI_NAME} ${CLI_VERSION}` : `${CLI_NAME} ${path.join(" ")}`;
   const sections: string[] = [title];
 
@@ -1021,26 +1034,32 @@ function renderGroupHelp(node: HelpGroup, path: string[]): string {
   }
 
   if (node.usage && node.usage.length > 0) {
-    sections.push(renderUsageSection(node.usage));
+    sections.push(renderUsageSection(node.usage, options));
   }
 
   if (node.aliases && node.aliases.length > 0) {
-    sections.push(renderLineListSection("Aliases", node.aliases));
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
   }
 
   const childHeading = path.length === 0 ? "Commands" : "Subcommands";
-  sections.push(renderEntrySection(childHeading, node.children));
+  sections.push(renderEntrySection(childHeading, node.children, options));
 
   if (node.options && node.options.length > 0) {
-    sections.push(renderOptionSection(path.length === 0 ? "Global Flags" : "Options", node.options));
+    sections.push(
+      renderOptionSection(
+        path.length === 0 ? "Global Flags" : "Options",
+        node.options,
+        options,
+      ),
+    );
   }
 
   if (node.examples && node.examples.length > 0) {
-    sections.push(renderLineListSection("Examples", node.examples, true));
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
   }
 
   if (node.notes && node.notes.length > 0) {
-    sections.push(renderLineListSection("Notes", node.notes));
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
   }
 
   if (path.length === 0) {
@@ -1052,43 +1071,56 @@ function renderGroupHelp(node: HelpGroup, path: string[]): string {
   return sections.join("\n\n");
 }
 
-function renderCommandHelp(node: HelpCommand, path: string[]): string {
+function renderCommandHelp(
+  node: HelpCommand,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
   const title = `${CLI_NAME} ${path.join(" ")}`;
   const sections: string[] = [title, node.description ?? node.summary];
 
   if (node.aliases && node.aliases.length > 0) {
-    sections.push(renderLineListSection("Aliases", node.aliases));
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
   }
 
   if (node.usage && node.usage.length > 0) {
-    sections.push(renderUsageSection(node.usage));
+    sections.push(renderUsageSection(node.usage, options));
   }
 
   if (node.options && node.options.length > 0) {
-    sections.push(renderOptionSection("Options", node.options));
+    sections.push(renderOptionSection("Options", node.options, options));
   }
 
   if (node.examples && node.examples.length > 0) {
-    sections.push(renderLineListSection("Examples", node.examples, true));
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
   }
 
   if (node.notes && node.notes.length > 0) {
-    sections.push(renderLineListSection("Notes", node.notes));
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
   }
 
   return sections.join("\n\n");
 }
 
-function renderUsageSection(usage: string[]): string {
-  return ["Usage:", ...usage.map((line) => `  ${line}`)].join("\n");
+function renderUsageSection(
+  usage: string[],
+  options: HelpRenderOptions,
+): string {
+  return [formatSectionTitle("USAGE", options), ...usage.map((line) => `  ${line}`)].join(
+    "\n",
+  );
 }
 
-function renderEntrySection(title: string, entries: HelpNode[]): string {
-  const labels = entries.map((entry) => formatEntryLabel(entry));
+function renderEntrySection(
+  title: string,
+  entries: HelpNode[],
+  options: HelpRenderOptions,
+): string {
+  const labels = entries.map((entry) => `${formatEntryLabel(entry)}:`);
   const width = labels.reduce((current, label) => Math.max(current, label.length), 0);
 
   return [
-    `${title}:`,
+    formatSectionTitle(title, options),
     ...entries.map((entry, index) => {
       const label = labels[index]!.padEnd(width, " ");
       return `  ${label}  ${entry.summary}`;
@@ -1096,11 +1128,15 @@ function renderEntrySection(title: string, entries: HelpNode[]): string {
   ].join("\n");
 }
 
-function renderOptionSection(title: string, options: HelpOption[]): string {
+function renderOptionSection(
+  title: string,
+  options: HelpOption[],
+  renderOptions: HelpRenderOptions,
+): string {
   const width = options.reduce((current, entry) => Math.max(current, entry.flag.length), 0);
 
   return [
-    `${title}:`,
+    formatSectionTitle(title, renderOptions),
     ...options.map((entry) => `  ${entry.flag.padEnd(width, " ")}  ${entry.description}`),
   ].join("\n");
 }
@@ -1109,9 +1145,10 @@ function renderLineListSection(
   title: string,
   lines: string[],
   code = false,
+  options: HelpRenderOptions,
 ): string {
   return [
-    `${title}:`,
+    formatSectionTitle(title, options),
     ...lines.map((line) => `  ${code ? line : line}`),
   ].join("\n");
 }
@@ -1121,3 +1158,11 @@ function formatEntryLabel(entry: HelpNode): string {
     ? `${entry.name}, ${entry.aliases.join(", ")}`
     : entry.name;
 }
+
+function formatSectionTitle(
+  title: string,
+  options: HelpRenderOptions = {},
+): string {
+  const heading = title.toUpperCase();
+  return options.boldSectionTitles ? `${ANSI_BOLD}${heading}${ANSI_RESET}` : heading;
+}

package/src/lib/output.ts

@@ -3,12 +3,16 @@ import type { OutputMode } from "../types/api";
 export interface Io {
   stdout: (message: string) => void;
   stderr: (message: string) => void;
+  stdoutIsTTY?: boolean;
+  stderrIsTTY?: boolean;
 }
 
 export function defaultIo(): Io {
   return {
     stdout: (message) => process.stdout.write(`${message}\n`),
-    stderr: (message) => process.stderr.write(`${message}\n`)
+    stderr: (message) => process.stderr.write(`${message}\n`),
+    stdoutIsTTY: process.stdout.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
   };
 }