Require -- separator for passing command arguments (#42)

* Initial plan

* Add support for -- separator to pass command arguments

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* Add proper shell argument escaping to preserve argument boundaries

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* Address code review comments: improve regex escaping and use ES6 imports

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* Remove legacy quoted syntax, require -- separator for all commands

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

README.md

@@ -37,26 +37,28 @@ sudo awf --help
 # Simple HTTP request
 sudo awf \
   --allow-domains github.com,api.github.com \
-  'curl https://api.github.com'
+  -- curl https://api.github.com
 
 # With GitHub Copilot CLI
 sudo -E awf \
   --allow-domains github.com,api.github.com,googleapis.com \
-  'copilot --prompt "List my repositories"'
+  -- copilot --prompt "List my repositories"
 
 # Docker-in-Docker (spawned containers inherit firewall)
 sudo awf \
   --allow-domains api.github.com,registry-1.docker.io,auth.docker.io \
-  'docker run --rm curlimages/curl -fsS https://api.github.com/zen'
+  -- docker run --rm curlimages/curl -fsS https://api.github.com/zen
 ```
 
+**Note:** Always use the `--` separator to pass commands and arguments. This ensures proper argument handling and avoids shell escaping issues.
+
 ## Domain Whitelisting
 
 Domains automatically match all subdomains:
 
 ```bash
 # github.com matches api.github.com, raw.githubusercontent.com, etc.
-sudo awf --allow-domains github.com "curl https://api.github.com"  # ✓ works
+sudo awf --allow-domains github.com -- curl https://api.github.com  # ✓ works
 ```
 
 Common domain lists:

src/cli.test.ts

@@ -1,7 +1,6 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables } from './cli';
+import { parseEnvironmentVariables, parseDomains, escapeShellArg, joinShellArgs } from './cli';
 import { redactSecrets } from './redact-secrets';
-import { parseDomains } from './cli';
 
 describe('cli', () => {
   describe('domain parsing', () => {
@@ -212,7 +211,7 @@ describe('cli', () => {
         )
         .option('--log-level <level>', 'Log level: debug, info, warn, error', 'info')
         .option('--keep-containers', 'Keep containers running after command exits', false)
-        .argument('<command>', 'Copilot command to execute');
+        .argument('[args...]', 'Command and arguments to execute');
 
       expect(program.name()).toBe('awf');
       expect(program.description()).toBe('Network firewall for agentic workflows with domain whitelisting');
@@ -238,6 +237,86 @@ describe('cli', () => {
     });
   });
 
+  describe('argument parsing with variadic args', () => {
+    it('should handle multiple arguments after -- separator', () => {
+      const program = new Command();
+      let capturedArgs: string[] = [];
+
+      program
+        .argument('[args...]', 'Command and arguments')
+        .action((args: string[]) => {
+          capturedArgs = args;
+        });
+
+      program.parse(['node', 'awf', '--', 'curl', 'https://api.github.com']);
+
+      expect(capturedArgs).toEqual(['curl', 'https://api.github.com']);
+    });
+
+    it('should handle arguments with flags after -- separator', () => {
+      const program = new Command();
+      let capturedArgs: string[] = [];
+
+      program
+        .argument('[args...]', 'Command and arguments')
+        .action((args: string[]) => {
+          capturedArgs = args;
+        });
+
+      program.parse(['node', 'awf', '--', 'curl', '-H', 'Authorization: Bearer token', 'https://api.github.com']);
+
+      expect(capturedArgs).toEqual(['curl', '-H', 'Authorization: Bearer token', 'https://api.github.com']);
+    });
+
+    it('should handle complex command with multiple flags', () => {
+      const program = new Command();
+      let capturedArgs: string[] = [];
+
+      program
+        .argument('[args...]', 'Command and arguments')
+        .action((args: string[]) => {
+          capturedArgs = args;
+        });
+
+      program.parse(['node', 'awf', '--', 'npx', '@github/copilot', '--prompt', 'hello world', '--log-level', 'debug']);
+
+      expect(capturedArgs).toEqual(['npx', '@github/copilot', '--prompt', 'hello world', '--log-level', 'debug']);
+    });
+  });
+
+  describe('shell argument escaping', () => {
+    it('should not escape simple arguments', () => {
+      expect(escapeShellArg('curl')).toBe('curl');
+      expect(escapeShellArg('https://api.github.com')).toBe('https://api.github.com');
+      expect(escapeShellArg('/usr/bin/node')).toBe('/usr/bin/node');
+      expect(escapeShellArg('--log-level=debug')).toBe('--log-level=debug');
+    });
+
+    it('should escape arguments with spaces', () => {
+      expect(escapeShellArg('hello world')).toBe("'hello world'");
+      expect(escapeShellArg('Authorization: Bearer token')).toBe("'Authorization: Bearer token'");
+    });
+
+    it('should escape arguments with special characters', () => {
+      expect(escapeShellArg('test$var')).toBe("'test$var'");
+      expect(escapeShellArg('test`cmd`')).toBe("'test`cmd`'");
+      expect(escapeShellArg('test;echo')).toBe("'test;echo'");
+    });
+
+    it('should escape single quotes in arguments', () => {
+      expect(escapeShellArg("it's")).toBe("'it'\\''s'");
+      expect(escapeShellArg("don't")).toBe("'don'\\''t'");
+    });
+
+    it('should join multiple arguments with proper escaping', () => {
+      expect(joinShellArgs(['curl', 'https://api.github.com'])).toBe('curl https://api.github.com');
+      expect(joinShellArgs(['curl', '-H', 'Authorization: Bearer token', 'https://api.github.com']))
+        .toBe("curl -H 'Authorization: Bearer token' https://api.github.com");
+      expect(joinShellArgs(['echo', 'hello world', 'test']))
+        .toBe("echo 'hello world' test");
+    });
+  });
+
   describe('work directory generation', () => {
     it('should generate unique work directories', () => {
       const dir1 = `/tmp/awf-${Date.now()}`;

src/cli.ts

@@ -32,6 +32,32 @@ export function parseDomains(input: string): string[] {
     .filter(d => d.length > 0);
 }
 
+/**
+ * Escapes a shell argument by wrapping it in single quotes and escaping any single quotes within it
+ * @param arg - Argument to escape
+ * @returns Escaped argument safe for shell execution
+ */
+export function escapeShellArg(arg: string): string {
+  // If the argument doesn't contain special characters, return as-is
+  // Character class includes: letters, digits, underscore, dash, dot (literal), slash, equals, colon
+  if (/^[a-zA-Z0-9_\-\./=:]+$/.test(arg)) {
+    return arg;
+  }
+  // Otherwise, wrap in single quotes and escape any single quotes inside
+  // The pattern '\\'' works by: ending the single-quoted string ('),
+  // adding an escaped single quote (\'), then starting a new single-quoted string (')
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Joins an array of shell arguments into a single command string, properly escaping each argument
+ * @param args - Array of arguments
+ * @returns Command string with properly escaped arguments
+ */
+export function joinShellArgs(args: string[]): string {
+  return args.map(escapeShellArg).join(' ');
+}
+
 /**
  * Result of parsing environment variables
  */
@@ -116,8 +142,17 @@ program
     'Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST)',
     false
   )
-  .argument('<command>', 'Copilot command to execute (wrap in quotes)')
-  .action(async (copilotCommand: string, options) => {
+  .argument('[args...]', 'Command and arguments to execute (use -- to separate from options)')
+  .action(async (args: string[], options) => {
+    // Require -- separator for passing command arguments
+    if (args.length === 0) {
+      console.error('Error: No command specified. Use -- to separate command from options.');
+      console.error('Example: awf --allow-domains github.com -- curl https://api.github.com');
+      process.exit(1);
+    }
+    
+    // Join arguments with proper shell escaping to preserve argument boundaries
+    const copilotCommand = joinShellArgs(args);
     // Parse and validate options
     const logLevel = options.logLevel as LogLevel;
     if (!['debug', 'info', 'warn', 'error'].includes(logLevel)) {