fix: switch app.py and export.py to argparse, add --port/--host/--base-dir, fix default host, validate --since (#4)

wpak-ai · cursoragent · wpak-ai · commit 242d81c18ce6 · 2026-02-25T13:54:55.000-05:00
Closes #4 - app.py: replace manual sys.argv loop with argparse - app.py: fix default host 0.0.0.0 → 127.0.0.1 (localhost only) - app.py: add --port (default 3000), --host, --base-dir flags - app.py: wire --base-dir to set_workspace_path_override - app.py: startup message now dynamic (http://{host}:{port}) - scripts/export.py: replace manual parse_args() with argparse - scripts/export.py: add --base-dir flag (overrides WORKSPACE_PATH env) - scripts/export.py: --since now uses choices=["all","last"] for validation - tests/test_cli_args.py: 34 unittest tests covering all three bugs Co-authored-by: Cursor <cursoragent@cursor.com>
diff --git a/app.py b/app.py
@@ -62,24 +62,33 @@ def favicon():
 
 
 if __name__ == "__main__":
+    import argparse
     import sys
 
-    exclusion_path = None
-    argv = sys.argv[1:]
-    i = 0
-    while i < len(argv):
-        if argv[i] in ("--exclude-rules", "-e") and i + 1 < len(argv):
-            exclusion_path = argv[i + 1]
-            i += 2
-            continue
-        i += 1
-
-    app = create_app(exclusion_rules_path=exclusion_path)
-    print("Cursor Chat Browser (Python) running at http://localhost:3000")
-    # use_reloader=False avoids a Windows socket issue with Flask's stat reloader
+    parser = argparse.ArgumentParser(description="Cursor Chat Browser (Python)")
+    parser.add_argument("--port", type=int, default=3000)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--base-dir", default=None,
+                        help="Override Cursor workspaceStorage path")
+    parser.add_argument(
+        "--exclude-rules", "-e",
+        default=None,
+        metavar="PATH",
+        help="Path to exclusion rules file (sensitive projects/chats are omitted). "
+             "If omitted, uses ~/.cursor-chat-browser/exclusion-rules.txt if present.",
+    )
+    args = parser.parse_args()
+
+    if args.base_dir:
+        from utils.workspace_path import set_workspace_path_override
+        set_workspace_path_override(args.base_dir)
+
+    app = create_app(exclusion_rules_path=args.exclude_rules)
+    print(f"Cursor Chat Browser (Python) running at http://{args.host}:{args.port}")
+    # Disable reloader on Windows to avoid a socket conflict with Flask's stat reloader.
     app.run(
-        host="0.0.0.0",
-        port=3000,
+        host=args.host,
+        port=args.port,
         debug=True,
         use_reloader=(sys.platform != "win32"),
     )
diff --git a/scripts/export.py b/scripts/export.py
@@ -211,50 +211,44 @@ def get_workspace_folder_paths(wd) -> list:
     return _shared_get_workspace_folder_paths(wd)
 
 
-HELP_TEXT = """\
-Export Cursor chat history to Markdown files.
-
-By default exports ALL chats (including composer logs) as a zip archive
-into the current directory. Use the flags below to narrow the export.
-
-Usage:
-  python scripts/export.py [OPTIONS]
-
-Options:
-  --since all|last   Export all chats or only those updated since last export.
-                     Default: all
-  --out DIR          Output directory. Default: current working directory (.)
-  --no-zip           Write individual Markdown files instead of a zip archive.
-  --no-composer      Exclude composer logs (export only chat logs).
-  --exclude-rules P  Path to exclusion rules file (sensitive projects/chats are omitted).
-                     If omitted, uses ~/.cursor-chat-browser/exclusion-rules.txt if present.
-  --help             Show this help message and exit.
-"""
-
-
 def parse_args():
-    args = sys.argv[1:]
-    out = {"since": "all", "out_dir": ".", "include_composer": True, "zip": True, "exclusion_rules_path": None}
-    i = 0
-    while i < len(args):
-        if args[i] in ("--help", "-h"):
-            print(HELP_TEXT)
-            sys.exit(0)
-        elif args[i] == "--since" and i + 1 < len(args):
-            i += 1
-            out["since"] = args[i]
-        elif args[i] == "--out" and i + 1 < len(args):
-            i += 1
-            out["out_dir"] = args[i]
-        elif args[i] in ("--exclude-rules", "-e") and i + 1 < len(args):
-            i += 1
-            out["exclusion_rules_path"] = args[i]
-        elif args[i] == "--no-composer":
-            out["include_composer"] = False
-        elif args[i] == "--no-zip":
-            out["zip"] = False
-        i += 1
-    return out
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Export Cursor chat history to Markdown files.",
+        epilog=(
+            "By default exports ALL chats (including composer logs) as a zip archive\n"
+            "into the current directory. Use the flags below to narrow the export.\n\n"
+            "Env: WORKSPACE_PATH overrides the Cursor workspaceStorage path."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--since", choices=["all", "last"], default="all",
+                        help="Export all chats or only those updated since last export. Default: all")
+    parser.add_argument("--out", default=".",
+                        help="Output directory. Default: current working directory (.)")
+    parser.add_argument("--no-zip", action="store_true", default=False,
+                        help="Write individual Markdown files instead of a zip archive.")
+    parser.add_argument("--no-composer", action="store_true", default=False,
+                        help="Exclude composer logs (export only chat logs).")
+    parser.add_argument("--base-dir", default=None,
+                        help="Override Cursor workspaceStorage path (also settable via WORKSPACE_PATH env var).")
+    parser.add_argument(
+        "--exclude-rules", "-e",
+        default=None,
+        metavar="PATH",
+        dest="exclude_rules",
+        help="Path to exclusion rules file (sensitive projects/chats are omitted). "
+             "If omitted, uses ~/.cursor-chat-browser/exclusion-rules.txt if present.",
+    )
+    args = parser.parse_args()
+    return {
+        "since": args.since,
+        "out_dir": args.out,
+        "include_composer": not args.no_composer,
+        "zip": not args.no_zip,
+        "exclusion_rules_path": args.exclude_rules,
+        "base_dir": args.base_dir,
+    }
 
 
 def main():
@@ -263,6 +257,8 @@ def main():
     out_dir = os.path.abspath(opts["out_dir"])
     use_zip = opts["zip"]
     exclusion_rules = load_rules(resolve_exclusion_rules_path(opts.get("exclusion_rules_path")))
+    if opts.get("base_dir"):
+        os.environ["WORKSPACE_PATH"] = opts["base_dir"]
     workspace_path = resolve_workspace_path()
     global_path = os.path.normpath(os.path.join(workspace_path, "..", "globalStorage", "state.vscdb"))
 
diff --git a/tests/test_cli_args.py b/tests/test_cli_args.py
@@ -0,0 +1,250 @@
+"""
+Regression tests for CLI argument parity between cursor-chat-browser-python and
+claude-code-chat-browser.
+
+Every flag/default documented here must stay in sync with claude-code-chat-browser
+so that users switching between the two tools experience zero CLI friction.
+
+Run:
+    python -m unittest tests.test_cli_args -v
+"""
+
+import sys
+import os
+import unittest
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, REPO_ROOT)
+
+# Import the argparse-based parse_args from the export script
+from scripts.export import parse_args as _raw_parse_args
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _parse_export(argv):
+    """Call scripts/export.py parse_args() with a custom sys.argv."""
+    original = sys.argv
+    sys.argv = ["export.py"] + list(argv)
+    try:
+        return _raw_parse_args()
+    finally:
+        sys.argv = original
+
+
+def _build_app_parser():
+    """Reconstruct the argparse parser from app.py without importing Flask."""
+    import argparse
+    parser = argparse.ArgumentParser(description="Cursor Chat Browser (Python)")
+    parser.add_argument("--port", type=int, default=3000)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--base-dir", default=None)
+    parser.add_argument("--exclude-rules", "-e", default=None,
+                        metavar="PATH", dest="exclude_rules")
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# export.py argument tests
+# ---------------------------------------------------------------------------
+
+class TestExportArgs(unittest.TestCase):
+
+    # -- --since ----------------------------------------------------------------
+
+    def test_since_default_is_all(self):
+        opts = _parse_export([])
+        self.assertEqual(opts["since"], "all")
+
+    def test_since_all(self):
+        opts = _parse_export(["--since", "all"])
+        self.assertEqual(opts["since"], "all")
+
+    def test_since_last(self):
+        opts = _parse_export(["--since", "last"])
+        self.assertEqual(opts["since"], "last")
+
+    def test_since_invalid_raises(self):
+        with self.assertRaises(SystemExit):
+            _parse_export(["--since", "yesterday"])
+
+    # -- --out ------------------------------------------------------------------
+
+    def test_out_default_is_dot(self):
+        opts = _parse_export([])
+        self.assertEqual(opts["out_dir"], ".")
+
+    def test_out_explicit(self):
+        opts = _parse_export(["--out", "/tmp/exports"])
+        self.assertEqual(opts["out_dir"], "/tmp/exports")
+
+    # -- --no-zip ---------------------------------------------------------------
+
+    def test_no_zip_default_false(self):
+        opts = _parse_export([])
+        self.assertTrue(opts["zip"])
+
+    def test_no_zip_flag(self):
+        opts = _parse_export(["--no-zip"])
+        self.assertFalse(opts["zip"])
+
+    # -- --no-composer ----------------------------------------------------------
+
+    def test_no_composer_default_true(self):
+        opts = _parse_export([])
+        self.assertTrue(opts["include_composer"])
+
+    def test_no_composer_flag(self):
+        opts = _parse_export(["--no-composer"])
+        self.assertFalse(opts["include_composer"])
+
+    # -- --exclude-rules / -e  --------------------------------------------------
+
+    def test_exclude_rules_default_none(self):
+        opts = _parse_export([])
+        self.assertIsNone(opts["exclusion_rules_path"])
+
+    def test_exclude_rules_long_form(self):
+        opts = _parse_export(["--exclude-rules", "/path/to/rules.txt"])
+        self.assertEqual(opts["exclusion_rules_path"], "/path/to/rules.txt")
+
+    def test_exclude_rules_short_form(self):
+        opts = _parse_export(["-e", "/path/to/rules.txt"])
+        self.assertEqual(opts["exclusion_rules_path"], "/path/to/rules.txt")
+
+    # -- --base-dir -------------------------------------------------------------
+
+    def test_base_dir_default_none(self):
+        opts = _parse_export([])
+        self.assertIsNone(opts["base_dir"])
+
+    def test_base_dir_explicit(self):
+        opts = _parse_export(["--base-dir", "/custom/workspace"])
+        self.assertEqual(opts["base_dir"], "/custom/workspace")
+
+    # -- --help / -h ------------------------------------------------------------
+
+    def test_help_exits_zero(self):
+        with self.assertRaises(SystemExit) as ctx:
+            _parse_export(["--help"])
+        self.assertEqual(ctx.exception.code, 0)
+
+    def test_help_short_exits_zero(self):
+        with self.assertRaises(SystemExit) as ctx:
+            _parse_export(["-h"])
+        self.assertEqual(ctx.exception.code, 0)
+
+
+# ---------------------------------------------------------------------------
+# app.py argument tests
+# ---------------------------------------------------------------------------
+
+class TestAppArgs(unittest.TestCase):
+
+    def setUp(self):
+        self.parser = _build_app_parser()
+
+    # -- --host / --port --------------------------------------------------------
+
+    def test_host_default_is_localhost(self):
+        """Default host must be 127.0.0.1, matching claude."""
+        args = self.parser.parse_args([])
+        self.assertEqual(args.host, "127.0.0.1")
+
+    def test_host_override(self):
+        args = self.parser.parse_args(["--host", "0.0.0.0"])
+        self.assertEqual(args.host, "0.0.0.0")
+
+    def test_port_default(self):
+        args = self.parser.parse_args([])
+        self.assertEqual(args.port, 3000)
+
+    def test_port_override(self):
+        args = self.parser.parse_args(["--port", "8080"])
+        self.assertEqual(args.port, 8080)
+
+    # -- --base-dir -------------------------------------------------------------
+
+    def test_base_dir_default_none(self):
+        args = self.parser.parse_args([])
+        self.assertIsNone(args.base_dir)
+
+    def test_base_dir_override(self):
+        args = self.parser.parse_args(["--base-dir", "/custom/workspace"])
+        self.assertEqual(args.base_dir, "/custom/workspace")
+
+    # -- --exclude-rules / -e ---------------------------------------------------
+
+    def test_exclude_rules_default_none(self):
+        args = self.parser.parse_args([])
+        self.assertIsNone(args.exclude_rules)
+
+    def test_exclude_rules_long_form(self):
+        args = self.parser.parse_args(["--exclude-rules", "/tmp/rules.txt"])
+        self.assertEqual(args.exclude_rules, "/tmp/rules.txt")
+
+    def test_exclude_rules_short_form(self):
+        args = self.parser.parse_args(["-e", "/tmp/rules.txt"])
+        self.assertEqual(args.exclude_rules, "/tmp/rules.txt")
+
+    # -- source assertions ------------------------------------------------------
+
+    def test_app_py_uses_argparse(self):
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn("argparse", src)
+        self.assertIn("add_argument", src)
+
+    def test_app_py_has_port_flag(self):
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn('"--port"', src)
+
+    def test_app_py_has_host_flag(self):
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn('"--host"', src)
+
+    def test_app_py_has_base_dir_flag(self):
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn('"--base-dir"', src)
+
+    def test_app_py_startup_message_is_dynamic(self):
+        """Startup message must use {args.host}/{args.port}, not be hardcoded."""
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn("args.host", src)
+        self.assertIn("args.port", src)
+
+    def test_app_py_use_reloader_is_platform_aware(self):
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn("sys.platform", src)
+        self.assertIn("win32", src)
+        self.assertNotIn("use_reloader=False", src)
+
+    def test_export_py_has_base_dir_flag(self):
+        export_path = os.path.join(REPO_ROOT, "scripts", "export.py")
+        with open(export_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn('"--base-dir"', src)
+
+    def test_export_py_has_since_choices(self):
+        """--since must use choices=["all","last"] for validated parity with claude."""
+        export_path = os.path.join(REPO_ROOT, "scripts", "export.py")
+        with open(export_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        self.assertIn('choices=["all", "last"]', src)
+
+
+if __name__ == "__main__":
+    unittest.main()
