feat: add apex launcher, test runner, and cli smoke test

apex

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""apex launcher — stdlib only. Puts commons/ (+ vendor/ + proprietaries/) on sys.path."""
+import os
+import sys
+
+_here = os.path.dirname(os.path.realpath(__file__))     # commons dir (or standalone repo root)
+sys.path.insert(0, _here)                               # make `engine` importable
+_vendor = os.path.join(_here, "vendor")
+if os.path.isdir(_vendor):
+    sys.path.insert(0, _vendor)
+if os.path.basename(_here) == "commons":                # node checkout: expose proprietaries/lib
+    _prop = os.path.join(os.path.dirname(_here), "proprietaries")
+    if os.path.isdir(_prop):
+        sys.path.insert(0, _prop)
+
+from engine.cli import main  # noqa: E402
+raise SystemExit(main(sys.argv[1:]))

tests/run.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Run the full engine test suite (stdlib unittest — no pytest).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+exec python3 -m unittest discover -s tests -p 'test_*.py' -v

tests/test_cli.py

@@ -0,0 +1,22 @@
+# tests/test_cli.py
+import os, subprocess, sys, unittest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+
+def run(*args):
+    return subprocess.run([sys.executable, os.path.join(ROOT, "apex"), *args],
+                          text=True, capture_output=True)
+
+class TestCli(unittest.TestCase):
+    def test_help_lists_and_exits_zero(self):
+        r = run("--help")
+        self.assertEqual(r.returncode, 0)
+        self.assertIn("Available actions", r.stdout)
+
+    def test_unknown_action_exits_one(self):
+        r = run("no/such")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("Unknown action", r.stderr)
+
+if __name__ == "__main__":
+    unittest.main()