From c9ccdd98254025ac313f27cb9408d3ee2b8d29fd Mon Sep 17 00:00:00 2001
From: maxpetrusenkoagent <max.petrusenko.agent@gmail.com>
Date: Tue, 9 Jun 2026 12:27:03 -0400
Subject: [PATCH] fix: add ios qa daemon help

Adds a no-side-effect --help path for gstack-ios-qa-daemon so first-run users can inspect usage without starting the daemon. Covers the behavior with a regression test.
---
 bin/gstack-ios-qa-daemon       | 33 +++++++++++++++++++++++++++++++++
 test/ios-qa-daemon-cli.test.ts | 25 +++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 test/ios-qa-daemon-cli.test.ts

diff --git a/bin/gstack-ios-qa-daemon b/bin/gstack-ios-qa-daemon
index b0ca2c6af..a328fca6a 100755
--- a/bin/gstack-ios-qa-daemon
+++ b/bin/gstack-ios-qa-daemon
@@ -22,6 +22,39 @@
 
 set -euo pipefail
 
+print_usage() {
+  cat <<'EOF'
+Usage:
+  gstack-ios-qa-daemon [--tailnet]
+  gstack-ios-qa-daemon --help
+
+Mac-side broker for /ios-qa and /ios-design-review. By default it binds a
+loopback listener for a USB-connected iPhone running the in-app StateServer.
+Pass --tailnet to also open the Tailscale listener after the local tailscaled
+identity probe succeeds.
+
+Options:
+  --tailnet   Enable the authenticated tailnet listener in addition to loopback.
+  -h, --help  Print this help and exit without starting the daemon.
+
+Environment:
+  GSTACK_IOS_DAEMON_PORT       Loopback listener port. Default: 9099.
+  GSTACK_IOS_TARGET_UDID       Target iOS device UDID. Optional.
+  GSTACK_IOS_TARGET_BUNDLE_ID  Bundle ID hosting StateServer. Default: com.gstack.iosqa.fixture.
+
+Readiness:
+  The daemon prints "READY: port=<n> pid=<pid>" once the listener is bound.
+  Probe local health with: curl -sf http://127.0.0.1:${GSTACK_IOS_DAEMON_PORT:-9099}/healthz
+EOF
+}
+
+case "${1:-}" in
+  -h|--help)
+    print_usage
+    exit 0
+    ;;
+esac
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 GSTACK_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 ENTRY="$GSTACK_DIR/ios-qa/daemon/src/index.ts"
diff --git a/test/ios-qa-daemon-cli.test.ts b/test/ios-qa-daemon-cli.test.ts
new file mode 100644
index 000000000..288972328
--- /dev/null
+++ b/test/ios-qa-daemon-cli.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+
+const ROOT = join(import.meta.dir, '..');
+const DAEMON_BIN = join(ROOT, 'bin/gstack-ios-qa-daemon');
+
+describe('gstack-ios-qa-daemon CLI', () => {
+  test('--help prints usage and exits without starting the daemon', () => {
+    const result = spawnSync('bash', [DAEMON_BIN, '--help'], {
+      cwd: ROOT,
+      encoding: 'utf-8',
+      timeout: 2_000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('Usage:');
+    expect(result.stdout).toContain('gstack-ios-qa-daemon');
+    expect(result.stdout).toContain('--tailnet');
+    expect(result.stdout).toContain('GSTACK_IOS_DAEMON_PORT');
+    expect(result.stdout).toContain('/healthz');
+    expect(result.stderr).toBe('');
+  });
+});