feat(cli): organize help text with logical option groups

src/cli.test.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, emitApiProxyTargetWarnings } from './cli';
+import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, emitApiProxyTargetWarnings, formatItem, program } from './cli';
 import { redactSecrets } from './redact-secrets';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -48,14 +48,14 @@
 
     afterEach(() => {
       // Clean up the test directory
       if (fs.existsSync(testDir)) {
         fs.rmSync(testDir, { recursive: true, force: true });
       }
     });
 
     it('should parse domains from file with one domain per line', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com\napi.github.com\nnpmjs.org');
 
       const result = parseDomainsFile(filePath);
 
@@ -64,7 +64,7 @@
 
     it('should parse comma-separated domains from file', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com, api.github.com, npmjs.org');
 
       const result = parseDomainsFile(filePath);
 
@@ -73,7 +73,7 @@
 
     it('should handle mixed formats (lines and commas)', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com\napi.github.com, npmjs.org\nexample.com');
 
       const result = parseDomainsFile(filePath);
 
@@ -82,7 +82,7 @@
 
     it('should skip empty lines', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com\n\n\napi.github.com\n\nnpmjs.org');
 
       const result = parseDomainsFile(filePath);
 
@@ -91,7 +91,7 @@
 
     it('should skip lines with only whitespace', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com\n   \n\t\napi.github.com');
 
       const result = parseDomainsFile(filePath);
 
@@ -100,7 +100,7 @@
 
     it('should skip comments starting with #', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, '# This is a comment\ngithub.com\n# Another comment\napi.github.com');
 
       const result = parseDomainsFile(filePath);
 
@@ -109,7 +109,7 @@
 
     it('should handle inline comments (after domain)', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com # GitHub main domain\napi.github.com # API endpoint');
 
       const result = parseDomainsFile(filePath);
 
@@ -118,7 +118,7 @@
 
     it('should handle domains with inline comments in comma-separated format', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, 'github.com, api.github.com # GitHub domains\nnpmjs.org');
 
       const result = parseDomainsFile(filePath);
 
@@ -133,7 +133,7 @@
 
     it('should return empty array for file with only comments and whitespace', () => {
       const filePath = path.join(testDir, 'domains.txt');
       fs.writeFileSync(filePath, '# Comment 1\n\n# Comment 2\n   \n');
 
       const result = parseDomainsFile(filePath);
 
@@ -1732,4 +1732,55 @@
     });
   });
 
+  describe('formatItem', () => {
+    it('should format item with description on same line when term fits', () => {
+      const result = formatItem('-v', 'verbose output', 20, 2, 2, 80);
+      expect(result).toBe('  -v                    verbose output');
+    });
+
+    it('should format item with description on next line when term is long', () => {
+      const result = formatItem('--very-long-option-name-here', 'desc', 10, 2, 2, 80);
+      expect(result).toContain('--very-long-option-name-here');
+      expect(result).toContain('\n');
+      expect(result).toContain('desc');
+    });
+
+    it('should format item without description', () => {
+      const result = formatItem('--flag', '', 20, 2, 2, 80);
+      expect(result).toBe('  --flag');
+    });
+  });
+
+  describe('help text formatting', () => {
+    it('should include section headers in help output', () => {
+      const help = program.helpInformation();
+      expect(help).toContain('Domain Filtering:');
+      expect(help).toContain('Image Management:');
+      expect(help).toContain('Container Configuration:');
+      expect(help).toContain('Network & Security:');
+      expect(help).toContain('API Proxy:');
+      expect(help).toContain('Logging & Debug:');
+    });
+
+    it('should include usage line', () => {
+      const help = program.helpInformation();
+      expect(help).toContain('Usage: awf');
+    });
+
+    it('should include program description', () => {
+      const help = program.helpInformation();
+      expect(help).toContain('Network firewall for agentic workflows');
+    });
+
+    it('should include arguments section', () => {
+      const help = program.helpInformation();
+      expect(help).toContain('Arguments:');
+    });
+
+    it('should include options section', () => {
+      const help = program.helpInformation();
+      expect(help).toContain('Options:');
+    });
+  });
+
 });