railtracks-cli 1.1.2__tar.gz

railtracks_cli-1.1.2/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: railtracks-cli
+Version: 1.1.2
+Summary: railtracks - A Python development server with file watching and JSON API
+Author-email: Logan Underwood <logan@railtown.ai>, Levi Varsanyi <levi@railtown.ai>, Jaime Bueza <jaime@railtown.ai>, Amir Refaee <amir@railtown.ai>, Aryan Ballani <aryan@railtown.ai>, Tristan Brown <tristan@railtown.ai>
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+License-File: LICENSE
+Requires-Dist: railtracks
+Requires-Dist: watchdog >= 3.0.0
+Project-URL: railtown, https://railtown.ai
+Project-URL: railtracks, https://railtracks.org
+Project-URL: repository, https://github.com/RailtownAI/railtracks
+Project-URL: ui-repository, https://github.com/RailtownAI/railtracks-visualizer
+
+# Railtracks CLI
+
+A simple CLI to help developers visualize and debug their agents.
+
+## What is Railtracks CLI?
+
+Railtracks CLI is a development tool that provides:
+
+- **Local Development Server**: A web-based visualizer for your railtracks projects
+- **File Watching**: Automatic detection of JSON file changes in your project
+- **JSON API**: RESTful endpoints to interact with your project data
+- **Modern UI**: A downloadable frontend interface for project visualization
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+pip install railtracks-cli
+```
+
+### 2. Initialize Your Project
+
+First, initialize the railtracks environment in your project directory:
+
+```bash
+railtracks init
+```
+
+This command will:
+
+- Create a `.railtracks` directory in your project
+- Add `.railtracks` to your `.gitignore` file
+- Download and extract the latest frontend UI
+
+### 3. Start the Development Server
+
+```bash
+railtracks viz
+```
+
+This starts the development server at `http://localhost:3030` with:
+
+- File watching for JSON changes
+- API endpoints for data access
+- Portable Web-based visualizer interface that can be opened in any web environment (web, mobile, vs extension, chrome extension, etc)
+
+## Project Structure
+
+After initialization, your project will have this structure:
+
+```
+your-project/
+├── .railtracks/          # Railtracks working directory
+│   ├── ui/              # Frontend interface files
+│   └── *.json           # Your project JSON files
+├── .gitignore           # Updated to exclude .railtracks
+└── your-source-files/   # Your actual project files
+```
+
+## File Watching
+
+The CLI automatically watches the `.railtracks` directory for JSON file changes:
+
+- **Real-time Detection**: Monitors file modifications with debouncing
+- **JSON Validation**: Validates JSON syntax when files are accessed
+- **Console Logging**: Reports file changes in the terminal
+

railtracks_cli-1.1.2/README.md

@@ -0,0 +1,67 @@
+# Railtracks CLI
+
+A simple CLI to help developers visualize and debug their agents.
+
+## What is Railtracks CLI?
+
+Railtracks CLI is a development tool that provides:
+
+- **Local Development Server**: A web-based visualizer for your railtracks projects
+- **File Watching**: Automatic detection of JSON file changes in your project
+- **JSON API**: RESTful endpoints to interact with your project data
+- **Modern UI**: A downloadable frontend interface for project visualization
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+pip install railtracks-cli
+```
+
+### 2. Initialize Your Project
+
+First, initialize the railtracks environment in your project directory:
+
+```bash
+railtracks init
+```
+
+This command will:
+
+- Create a `.railtracks` directory in your project
+- Add `.railtracks` to your `.gitignore` file
+- Download and extract the latest frontend UI
+
+### 3. Start the Development Server
+
+```bash
+railtracks viz
+```
+
+This starts the development server at `http://localhost:3030` with:
+
+- File watching for JSON changes
+- API endpoints for data access
+- Portable Web-based visualizer interface that can be opened in any web environment (web, mobile, vs extension, chrome extension, etc)
+
+## Project Structure
+
+After initialization, your project will have this structure:
+
+```
+your-project/
+├── .railtracks/          # Railtracks working directory
+│   ├── ui/              # Frontend interface files
+│   └── *.json           # Your project JSON files
+├── .gitignore           # Updated to exclude .railtracks
+└── your-source-files/   # Your actual project files
+```
+
+## File Watching
+
+The CLI automatically watches the `.railtracks` directory for JSON file changes:
+
+- **Real-time Detection**: Monitors file modifications with debouncing
+- **JSON Validation**: Validates JSON syntax when files are accessed
+- **Console Logging**: Reports file changes in the terminal

railtracks_cli-1.1.2/build_cli.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+Build script for the railtracks CLI package in the monorepo.
+This script helps build and install the CLI package locally for development.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_command(cmd, cwd=None):
+    """Run a command and return the result."""
+    print(f"Running: {cmd}")
+    if cwd:
+        print(f"Working directory: {cwd}")
+
+    result = subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        print(f"Error: {result.stderr}")
+        return False
+
+    print(f"Success: {result.stdout}")
+    return True
+
+
+def main():
+    """Build the CLI package."""
+    # Get the project root directory
+    project_root = Path(__file__).parent.parent
+    cli_dir = project_root / "railtracks-cli"
+
+    if not cli_dir.exists():
+        print(f"Error: CLI directory not found at {cli_dir}")
+        sys.exit(1)
+
+    print("Building railtracks CLI package...")
+
+    # Build the CLI package
+    if not run_command("python -m build", cwd=cli_dir):
+        print("Failed to build CLI package")
+        sys.exit(1)
+
+    print("CLI package built successfully!")
+    print("\nTo install the CLI package locally for development:")
+    print("pip install -e railtracks-cli/")
+    print("\nTo install the main package with CLI:")
+    print("pip install -e .[cli]")
+
+
+if __name__ == "__main__":
+    main()

railtracks_cli-1.1.2/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "railtracks-cli"
+authors = [
+    { name = "Logan Underwood", email = "logan@railtown.ai" },
+    { name = "Levi Varsanyi", email = "levi@railtown.ai" },
+    { name = "Jaime Bueza", email = "jaime@railtown.ai" },
+    { name = "Amir Refaee", email = "amir@railtown.ai" },
+    { name = "Aryan Ballani", email = "aryan@railtown.ai" },
+    { name = "Tristan Brown", email = "tristan@railtown.ai" }
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+classifiers = ["License :: OSI Approved :: MIT License"]
+dynamic = ["version", "description"]
+
+dependencies = [
+    "railtracks",
+    "watchdog >= 3.0.0"
+]
+
+[project.urls]
+railtracks = "https://railtracks.org"
+repository = "https://github.com/RailtownAI/railtracks"
+ui-repository = "https://github.com/RailtownAI/railtracks-visualizer"
+railtown = "https://railtown.ai"
+
+[tool.flit.module]
+name = "railtracks_cli"
+
+[project.scripts]
+railtracks = "railtracks_cli:main"

railtracks_cli-1.1.2/run_tests.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+
+"""
+Simple test runner for railtracks-cli tests
+"""
+
+import sys
+import unittest
+from pathlib import Path
+
+
+def run_tests():
+    """Run all tests in the tests directory"""
+    # Add src to path so tests can import railtracks_cli
+    src_path = Path(__file__).parent / "src"
+    sys.path.insert(0, str(src_path))
+
+    # Discover and run tests
+    loader = unittest.TestLoader()
+    start_dir = Path(__file__).parent / "tests"
+    suite = loader.discover(str(start_dir), pattern="test_*.py")
+
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(suite)
+
+    # Return exit code based on test results
+    return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(run_tests())

railtracks_cli-1.1.2/src/railtracks_cli/__init__.py

@@ -0,0 +1,589 @@
+#!/usr/bin/env python3
+
+"""
+railtracks - A Python development server with file watching and JSON API
+Usage: railtracks [command]
+
+Commands:
+  init    Initialize railtracks environment (setup directories, download UI)
+  viz     Start the railtracks development server
+
+- Checks to see if there is a .railtracks directory
+- If not, it creates one (and adds it to the .gitignore)
+- If there is a build directory, it runs the build command
+- If there is a .railtracks directory, it starts the server
+
+For testing purposes, you can add `alias railtracks="python railtracks.py"` to your .bashrc or .zshrc
+"""
+
+import json
+import mimetypes
+import os
+import queue
+import sys
+import tempfile
+import threading
+import time
+import traceback
+import urllib.request
+import webbrowser
+import zipfile
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlparse
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+__version__ = "1.1.2"
+
+# TODO: Once we are releasing to PyPi change this to the release asset instead
+latest_ui_url = "https://railtownazureb2c.blob.core.windows.net/cdn/rc-viz/latest.zip"
+
+cli_name = "railtracks"
+cli_directory = ".railtracks"
+DEFAULT_PORT = 3030
+DEBOUNCE_INTERVAL = 0.5  # seconds
+
+# Simple streaming for single-user dev tool
+current_stream_queue = None
+stream_queue_lock = threading.Lock()
+
+
+def get_script_directory():
+    """Get the directory where this script is located"""
+    return Path(__file__).parent.absolute()
+
+
+def print_status(message):
+    print(f"[{cli_name}] {message}")
+
+
+def print_success(message):
+    print(f"[{cli_name}] {message}")
+
+
+def print_warning(message):
+    print(f"[{cli_name}] {message}")
+
+
+def print_error(message):
+    print(f"[{cli_name}] {message}")
+
+
+def set_stream_queue(stream_queue):
+    """Set the current stream queue (single client)"""
+    global current_stream_queue
+    with stream_queue_lock:
+        current_stream_queue = stream_queue
+    print_status("Stream client connected")
+
+
+def clear_stream_queue():
+    """Clear the current stream queue"""
+    global current_stream_queue
+    with stream_queue_lock:
+        current_stream_queue = None
+    print_status("Stream client disconnected")
+
+
+def send_to_stream(message):
+    """Send message to the current stream client (if any)"""
+    global current_stream_queue
+    with stream_queue_lock:
+        if current_stream_queue:
+            try:
+                current_stream_queue.put_nowait(message)
+            except queue.Full:
+                print_status("Stream queue full, clearing connection")
+                current_stream_queue = None
+
+
+def create_railtracks_dir():
+    """Create .railtracks directory if it doesn't exist and add to .gitignore"""
+    railtracks_dir = Path(cli_directory)
+    if not railtracks_dir.exists():
+        print_status(f"Creating {cli_directory} directory...")
+        railtracks_dir.mkdir(exist_ok=True)
+        print_success(f"Created {cli_directory} directory")
+
+    # Check if cli_directory is in .gitignore
+    gitignore_path = Path(".gitignore")
+    if gitignore_path.exists():
+        with open(gitignore_path) as f:
+            gitignore_content = f.read()
+
+        if cli_directory not in gitignore_content:
+            print_status(f"Adding {cli_directory} to .gitignore...")
+            with open(gitignore_path, "a") as f:
+                f.write(f"\n{cli_directory}\n")
+            print_success(f"Added {cli_directory} to .gitignore")
+    else:
+        print_status("Creating .gitignore file...")
+        with open(gitignore_path, "w") as f:
+            f.write(f"{cli_directory}\n")
+        print_success(f"Created .gitignore with {cli_directory}")
+
+
+def download_and_extract_ui():
+    """Download the latest frontend UI and extract it to .railtracks/ui"""
+    ui_url = latest_ui_url
+    ui_dir = Path(f"{cli_directory}/ui")
+
+    print_status("Downloading latest frontend UI...")
+
+    try:
+        # Create temporary file for download
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as temp_file:
+            temp_zip_path = temp_file.name
+
+        # Download the zip file
+        print_status(f"Downloading from: {ui_url}")
+        urllib.request.urlretrieve(ui_url, temp_zip_path)
+
+        # Create ui directory if it doesn't exist
+        ui_dir.mkdir(parents=True, exist_ok=True)
+
+        # Extract the zip file
+        print_status("Extracting UI files...")
+        with zipfile.ZipFile(temp_zip_path, "r") as zip_ref:
+            zip_ref.extractall(ui_dir)
+
+        # Clean up temporary file
+        os.unlink(temp_zip_path)
+
+        print_success("Frontend UI downloaded and extracted successfully")
+        print_status(f"UI files available in: {ui_dir}")
+
+    except urllib.error.URLError as e:
+        print_error(f"Failed to download UI: {e}")
+        print_error("Please check your internet connection and try again")
+        sys.exit(1)
+    except zipfile.BadZipFile as e:
+        print_error(f"Failed to extract UI zip file: {e}")
+        print_error("The downloaded file may be corrupted")
+        sys.exit(1)
+    except Exception as e:
+        print_error(f"Unexpected error during UI download/extraction: {e}")
+        sys.exit(1)
+
+
+def init_railtracks():
+    """Initialize the railtracks environment"""
+    print_status("Initializing railtracks environment...")
+
+    # Setup directories
+    create_railtracks_dir()
+
+    # Download and extract UI
+    download_and_extract_ui()
+
+    print_success("railtracks initialization completed!")
+    print_status("You can now run 'railtracks viz' to start the server")
+
+
+class FileChangeHandler(FileSystemEventHandler):
+    """Handle file system events in the .railtracks directory"""
+
+    def __init__(self):
+        self.last_modified = {}
+
+    def on_modified(self, event):
+        if event.is_directory:
+            return
+
+        file_path = Path(event.src_path)
+        if file_path.suffix.lower() == ".json":
+            current_time = time.time()
+            last_time = self.last_modified.get(str(file_path), 0)
+
+            # Debounce rapid file changes
+            if current_time - last_time > DEBOUNCE_INTERVAL:
+                self.last_modified[str(file_path)] = current_time
+                print_status(f"JSON file modified: {file_path.name}")
+
+                # Send to stream client
+                stream_message = {
+                    "type": "file_updated",
+                    "filename": file_path.name,
+                    "timestamp": current_time,
+                }
+                send_to_stream(json.dumps(stream_message))
+
+
+class RailtracksHTTPHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for the railtracks server"""
+
+    def __init__(self, *args, **kwargs):
+        self.ui_dir = Path(f"{cli_directory}/ui")
+        self.railtracks_dir = Path(cli_directory)
+        try:
+            super().__init__(*args, **kwargs)
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+            # Client disconnected during initialization - this is normal for SSE
+            pass
+
+    def do_GET(self):  # noqa: N802
+        """Handle GET requests"""
+        parsed_url = urlparse(self.path)
+        path = parsed_url.path
+
+        # API endpoints
+        if path == "/api/files":
+            self.handle_api_files()
+        elif path.startswith("/api/json/"):
+            self.handle_api_json(path)
+        elif path == "/stream":
+            self.handle_stream()
+        else:
+            # Serve static files from build directory
+            self.serve_static_file(path)
+
+    def do_OPTIONS(self):  # noqa: N802
+        """Handle OPTIONS requests for CORS preflight"""
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.end_headers()
+
+    def do_POST(self):  # noqa: N802
+        """Handle POST requests"""
+        parsed_url = urlparse(self.path)
+        path = parsed_url.path
+
+        if path == "/api/refresh":
+            self.handle_refresh()
+        else:
+            self.send_error(404, "Not Found")
+
+    def handle_api_files(self):
+        """Handle /api/files endpoint - list JSON files in .railtracks directory"""
+        try:
+            json_files = []
+            if self.railtracks_dir.exists():
+                for file_path in self.railtracks_dir.glob("*.json"):
+                    json_files.append(
+                        {
+                            "name": file_path.name,
+                            "size": file_path.stat().st_size,
+                            "modified": file_path.stat().st_mtime,
+                        }
+                    )
+
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            self.wfile.write(json.dumps(json_files).encode())
+
+        except Exception as e:
+            print_error(f"Error handling /api/files: {e}")
+            self.send_error(500, "Internal Server Error")
+
+    def handle_api_json(self, path):
+        """Handle /api/json/{filename} endpoint - load specific JSON file"""
+        try:
+            # Extract filename from path
+            filename = path.replace("/api/json/", "")
+            if not filename.endswith(".json"):
+                filename += ".json"
+
+            file_path = self.railtracks_dir / filename
+
+            if not file_path.exists():
+                self.send_error(404, f"File {filename} not found")
+                return
+
+            # Read and parse JSON file
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+                # Validate JSON
+                json.loads(content)
+
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            self.wfile.write(content.encode())
+
+        except json.JSONDecodeError as e:
+            print_error(f"Invalid JSON in {filename}: {e}")
+            self.send_error(400, f"Invalid JSON: {e}")
+        except Exception as e:
+            print_error(f"Error handling /api/json/{filename}: {e}")
+            self.send_error(500, "Internal Server Error")
+
+    def handle_refresh(self):
+        """Handle /api/refresh endpoint - trigger frontend refresh"""
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(json.dumps({"status": "refresh_triggered"}).encode())
+        print_status("Frontend refresh triggered")
+
+    def handle_stream(self):
+        """Handle /stream endpoint - HTTP streaming for file updates (MCP-style)"""
+        try:
+            # Create queue for this connection
+            stream_queue = queue.Queue()
+            set_stream_queue(stream_queue)
+
+            # Send streaming headers (newline-delimited JSON)
+            self.send_response(200)
+            self.send_header("Content-Type", "application/x-ndjson")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "keep-alive")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+
+            # Send initial connection message
+            initial_message = {
+                "type": "connected",
+                "message": "Stream connection established",
+                "timestamp": time.time(),
+            }
+            self.write_json_line(initial_message)
+
+            # Keep connection alive and send messages
+            try:
+                while True:
+                    try:
+                        # Wait for message with timeout
+                        message = stream_queue.get(timeout=30)
+                        parsed_message = json.loads(message)
+                        self.write_json_line(parsed_message)
+                    except queue.Empty:
+                        # Send keepalive
+                        keepalive = {"type": "keepalive", "timestamp": time.time()}
+                        self.write_json_line(keepalive)
+                    except (BrokenPipeError, ConnectionResetError, OSError):
+                        # Client disconnected
+                        break
+            except Exception as e:
+                print_error(f"Stream connection error: {e}")
+            finally:
+                # Clean up
+                clear_stream_queue()
+
+        except Exception as e:
+            print_error(f"Error handling stream connection: {e}")
+            clear_stream_queue()
+            try:
+                self.send_error(500, "Internal Server Error")
+            except (BrokenPipeError, ConnectionResetError, OSError):
+                pass  # Connection might already be closed
+
+    def write_json_line(self, data):
+        """Write a JSON line to the streaming response (NDJSON format)"""
+        try:
+            json_line = json.dumps(data) + "\n"
+            self.wfile.write(json_line.encode())
+            self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            # Client disconnected - this is normal
+            pass
+
+    def serve_static_file(self, path):
+        """Serve static files from .railtracks/ui directory"""
+        try:
+            # Default to index.html for root path
+            if path == "/":
+                file_path = self.ui_dir / "index.html"
+            else:
+                file_path = self.ui_dir / path.lstrip("/")
+
+            if not file_path.exists():
+                # For SPA routing, fallback to index.html
+                file_path = self.ui_dir / "index.html"
+
+            if not file_path.exists():
+                self.send_error(404, "File not found")
+                return
+
+            # Determine content type
+            content_type, _ = mimetypes.guess_type(str(file_path))
+            if content_type is None:
+                content_type = "application/octet-stream"
+
+            # Read and serve file
+            with open(file_path, "rb") as f:
+                content = f.read()
+
+            self.send_response(200)
+            self.send_header("Content-Type", content_type)
+            self.end_headers()
+            self.wfile.write(content)
+
+        except Exception as e:
+            print_error(f"Error serving static file {path}: {e}")
+            self.send_error(500, "Internal Server Error")
+
+    def log_message(self, format, *args):
+        """Override to use our colored logging and suppress connection errors"""
+        message = format % args
+        # Suppress common connection error messages that are normal for SSE
+        if any(
+            error in message.lower()
+            for error in [
+                "connection aborted",
+                "connection reset",
+                "broken pipe",
+                "an established connection was aborted",
+            ]
+        ):
+            return
+        print_status(f"{self.address_string()} - {message}")
+
+    def handle_error(self, request, client_address):
+        """Override to suppress connection errors"""
+        # Get the exception info
+        exc_type, exc_value, exc_traceback = sys.exc_info()
+
+        # Suppress common connection errors that are normal for SSE
+        if exc_type in (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+            return
+
+        # For other errors, use default handling but with our logging
+        print_error(f"Error handling request from {client_address}")
+        print_error(f"{exc_type.__name__}: {exc_value}")
+
+        # Only print full traceback for unexpected errors
+        if exc_type not in (
+            ConnectionAbortedError,
+            ConnectionResetError,
+            BrokenPipeError,
+        ):
+            traceback.print_exc()
+
+
+class RailtracksServer:
+    """Main server class"""
+
+    def __init__(self, port=DEFAULT_PORT):
+        self.port = port
+        self.server = None
+        self.observer = None
+        self.running = False
+
+    def start_file_watcher(self):
+        """Start watching the .railtracks directory"""
+        railtracks_dir = Path(cli_directory)
+        if not railtracks_dir.exists():
+            railtracks_dir.mkdir(exist_ok=True)
+
+        event_handler = FileChangeHandler()
+        self.observer = Observer()
+        self.observer.schedule(event_handler, str(railtracks_dir), recursive=True)
+        self.observer.start()
+        print_status(f"Watching for JSON file changes in: {railtracks_dir}")
+
+    def start_http_server(self):
+        """Start the HTTP server"""
+
+        # Create a custom handler class with the ui and railtracks directories
+        class Handler(RailtracksHTTPHandler):
+            def __init__(self, *args, **kwargs):
+                self.ui_dir = Path(f"{cli_directory}/ui")
+                self.railtracks_dir = Path(cli_directory)
+                try:
+                    super().__init__(*args, **kwargs)
+                except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+                    # Client disconnected during initialization - this is normal for SSE
+                    pass
+
+        self.server = ThreadingHTTPServer(("localhost", self.port), Handler)
+        print_success(f"🚀 railtracks server running at http://localhost:{self.port}")
+        print_status(f"📁 Serving files from: {cli_directory}/ui/")
+        print_status(f"👀 Watching for changes in: {cli_directory}/")
+        print_status("📋 API endpoints:")
+        print_status("   GET  /api/files - List JSON files")
+        print_status("   GET  /api/json/filename - Load JSON file")
+        print_status("   POST /api/refresh - Trigger frontend refresh")
+        print_status("   GET  /stream - HTTP streaming for file updates")
+        print_status("Press Ctrl+C to stop the server")
+
+        # Open browser after a short delay to ensure server is ready
+        def open_browser():
+            time.sleep(1)  # Give server a moment to fully start
+            url = f"http://localhost:{self.port}"
+            print_status(f"Opening browser to {url}")
+            try:
+                webbrowser.open(url)
+            except Exception as e:
+                print_warning(f"Could not open browser automatically: {e}")
+                print_status(f"Please manually open: {url}")
+
+        browser_thread = threading.Thread(target=open_browser)
+        browser_thread.daemon = True
+        browser_thread.start()
+
+        self.server.serve_forever()
+
+    def start(self):
+        """Start both the file watcher and HTTP server"""
+        self.running = True
+
+        # Start file watcher in a separate thread
+        watcher_thread = threading.Thread(target=self.start_file_watcher)
+        watcher_thread.daemon = True
+        watcher_thread.start()
+
+        # Start HTTP server in main thread
+        try:
+            self.start_http_server()
+        except KeyboardInterrupt:
+            self.stop()
+
+    def stop(self):
+        """Stop the server and cleanup"""
+        if self.running:
+            print_status("Shutting down railtracks...")
+            self.running = False
+
+            if self.server:
+                self.server.shutdown()
+
+            if self.observer:
+                self.observer.stop()
+                self.observer.join()
+
+            print_success("railtracks stopped.")
+
+
+def main():
+    """Main function"""
+    if len(sys.argv) < 2:
+        print(f"Usage: {cli_name} [command]")
+        print("")
+        print("Commands:")
+        print(
+            f"  init    Initialize {cli_name} environment (setup directories, download portable UI)"
+        )
+        print(f"  viz     Start the {cli_name} development server")
+        print("")
+        print("Examples:")
+        print(f"  {cli_name} init    # Initialize development environment")
+        print(f"  {cli_name} viz     # Start visualizer web app")
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "init":
+        init_railtracks()
+    elif command == "viz":
+        # Setup directories
+        create_railtracks_dir()
+
+        # Start server
+        server = RailtracksServer()
+        server.start()
+    else:
+        print(f"Unknown command: {command}")
+        print("Available commands: init, viz")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

railtracks_cli-1.1.2/src/railtracks_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for railtracks CLI when run as a module"""
+
+from railtracks_cli import main
+
+if __name__ == "__main__":
+    main()

railtracks_cli-1.1.2/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tests for railtracks-cli package
+"""

railtracks_cli-1.1.2/tests/test_init.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+
+"""
+Basic unit tests for railtracks CLI functionality
+"""
+
+import json
+import os
+import queue
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, mock_open, patch
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+import railtracks_cli
+
+from railtracks_cli import (
+    DEBOUNCE_INTERVAL,
+    FileChangeHandler,
+    clear_stream_queue,
+    create_railtracks_dir,
+    get_script_directory,
+    print_error,
+    print_status,
+    print_success,
+    print_warning,
+    send_to_stream,
+    set_stream_queue,
+)
+
+
+class TestUtilityFunctions(unittest.TestCase):
+    """Test basic utility functions"""
+
+    def test_get_script_directory(self):
+        """Test get_script_directory returns a valid Path"""
+        result = get_script_directory()
+        self.assertIsInstance(result, Path)
+        self.assertTrue(result.exists())
+        self.assertTrue(result.is_dir())
+
+    @patch('builtins.print')
+    def test_print_functions(self, mock_print):
+        """Test all print functions format messages correctly"""
+        test_message = "test message"
+
+        print_status(test_message)
+        mock_print.assert_called_with("[railtracks] test message")
+
+        print_success(test_message)
+        mock_print.assert_called_with("[railtracks] test message")
+
+        print_warning(test_message)
+        mock_print.assert_called_with("[railtracks] test message")
+
+        print_error(test_message)
+        mock_print.assert_called_with("[railtracks] test message")
+
+
+class TestStreamQueue(unittest.TestCase):
+    """Test stream queue functionality"""
+
+    def setUp(self):
+        """Clear stream queue before each test"""
+        clear_stream_queue()
+
+    def tearDown(self):
+        """Clear stream queue after each test"""
+        clear_stream_queue()
+
+    def test_set_and_clear_stream_queue(self):
+        """Test setting and clearing stream queue"""
+        # Initially should be None
+        self.assertIsNone(railtracks_cli.current_stream_queue)
+
+        # Set a queue
+        test_queue = queue.Queue()
+        set_stream_queue(test_queue)
+
+        # Should be set now
+        self.assertIsNotNone(railtracks_cli.current_stream_queue)
+
+        # Clear it
+        clear_stream_queue()
+
+        # Should be None again
+        self.assertIsNone(railtracks_cli.current_stream_queue)
+
+    def test_send_to_stream_no_queue(self):
+        """Test sending to stream when no queue is set"""
+        # Should not raise an exception
+        send_to_stream("test message")
+
+    def test_send_to_stream_with_queue(self):
+        """Test sending to stream with active queue"""
+        test_queue = queue.Queue()
+        set_stream_queue(test_queue)
+
+        test_message = "test message"
+        send_to_stream(test_message)
+
+        # Should have received the message
+        self.assertFalse(test_queue.empty())
+        received = test_queue.get_nowait()
+        self.assertEqual(received, test_message)
+
+    def test_send_to_stream_full_queue(self):
+        """Test sending to stream when queue is full"""
+        # Create a queue with maxsize 1
+        test_queue = queue.Queue(maxsize=1)
+        set_stream_queue(test_queue)
+
+        # Fill the queue
+        test_queue.put_nowait("existing message")
+
+        # Try to send another message - should clear the queue
+        send_to_stream("new message")
+
+        # Queue should have been cleared
+        self.assertIsNone(railtracks_cli.current_stream_queue)
+
+
+class TestCreateRailtracksDir(unittest.TestCase):
+    """Test create_railtracks_dir function"""
+
+    def setUp(self):
+        """Set up temporary directory for testing"""
+        self.test_dir = tempfile.mkdtemp()
+        self.original_cwd = os.getcwd()
+        os.chdir(self.test_dir)
+
+    def tearDown(self):
+        """Clean up temporary directory"""
+        os.chdir(self.original_cwd)
+        shutil.rmtree(self.test_dir)
+
+    @patch('railtracks_cli.print_status')
+    @patch('railtracks_cli.print_success')
+    def test_create_railtracks_dir_new(self, mock_success, mock_status):
+        """Test creating .railtracks directory when it doesn't exist"""
+        # Ensure .railtracks doesn't exist
+        railtracks_path = Path(".railtracks")
+        self.assertFalse(railtracks_path.exists())
+
+        create_railtracks_dir()
+
+        # Should exist now
+        self.assertTrue(railtracks_path.exists())
+        self.assertTrue(railtracks_path.is_dir())
+
+        # Should have called print functions
+        mock_status.assert_called()
+        mock_success.assert_called()
+
+    @patch('railtracks_cli.print_status')
+    @patch('railtracks_cli.print_success')
+    def test_create_railtracks_dir_existing(self, mock_success, mock_status):
+        """Test when .railtracks directory already exists"""
+        # Create .railtracks directory first
+        railtracks_path = Path(".railtracks")
+        railtracks_path.mkdir()
+
+        create_railtracks_dir()
+
+        # Should still exist
+        self.assertTrue(railtracks_path.exists())
+        self.assertTrue(railtracks_path.is_dir())
+
+    @patch('railtracks_cli.print_status')
+    @patch('railtracks_cli.print_success')
+    def test_create_railtracks_dir_gitignore_new(self, mock_success, mock_status):
+        """Test creating .gitignore with .railtracks entry"""
+        create_railtracks_dir()
+
+        # Should create .gitignore
+        gitignore_path = Path(".gitignore")
+        self.assertTrue(gitignore_path.exists())
+
+        # Should contain .railtracks
+        with open(gitignore_path) as f:
+            content = f.read()
+        self.assertIn(".railtracks", content)
+
+    @patch('railtracks_cli.print_status')
+    @patch('railtracks_cli.print_success')
+    def test_create_railtracks_dir_gitignore_existing(self, mock_success, mock_status):
+        """Test adding .railtracks to existing .gitignore"""
+        # Create existing .gitignore
+        gitignore_path = Path(".gitignore")
+        with open(gitignore_path, "w") as f:
+            f.write("*.pyc\n__pycache__/\n")
+
+        create_railtracks_dir()
+
+        # Should contain both old and new entries
+        with open(gitignore_path) as f:
+            content = f.read()
+        self.assertIn("*.pyc", content)
+        self.assertIn(".railtracks", content)
+
+    @patch('railtracks_cli.print_status')
+    def test_create_railtracks_dir_gitignore_already_present(self, mock_status):
+        """Test when .railtracks is already in .gitignore"""
+        # Create .gitignore with .railtracks already present
+        gitignore_path = Path(".gitignore")
+        with open(gitignore_path, "w") as f:
+            f.write("*.pyc\n.railtracks\n__pycache__/\n")
+
+        original_content = gitignore_path.read_text()
+
+        create_railtracks_dir()
+
+        # Content should be unchanged
+        new_content = gitignore_path.read_text()
+        self.assertEqual(original_content, new_content)
+
+
+class TestFileChangeHandler(unittest.TestCase):
+    """Test FileChangeHandler debouncing logic"""
+
+    def setUp(self):
+        """Set up handler for testing"""
+        self.handler = FileChangeHandler()
+
+    @patch('railtracks_cli.send_to_stream')
+    @patch('railtracks_cli.print_status')
+    def test_file_change_handler_json_file(self, mock_print, mock_stream):
+        """Test handler processes JSON file changes"""
+        # Create a mock event
+        mock_event = MagicMock()
+        mock_event.is_directory = False
+        mock_event.src_path = "/test/path/file.json"
+
+        self.handler.on_modified(mock_event)
+
+        # Should have printed status and sent to stream
+        mock_print.assert_called_once()
+        mock_stream.assert_called_once()
+
+    @patch('railtracks_cli.send_to_stream')
+    @patch('railtracks_cli.print_status')
+    def test_file_change_handler_non_json_file(self, mock_print, mock_stream):
+        """Test handler ignores non-JSON files"""
+        # Create a mock event for non-JSON file
+        mock_event = MagicMock()
+        mock_event.is_directory = False
+        mock_event.src_path = "/test/path/file.txt"
+
+        self.handler.on_modified(mock_event)
+
+        # Should not have printed or sent to stream
+        mock_print.assert_not_called()
+        mock_stream.assert_not_called()
+
+    @patch('railtracks_cli.send_to_stream')
+    @patch('railtracks_cli.print_status')
+    def test_file_change_handler_directory(self, mock_print, mock_stream):
+        """Test handler ignores directory changes"""
+        # Create a mock event for directory
+        mock_event = MagicMock()
+        mock_event.is_directory = True
+        mock_event.src_path = "/test/path/directory"
+
+        self.handler.on_modified(mock_event)
+
+        # Should not have printed or sent to stream
+        mock_print.assert_not_called()
+        mock_stream.assert_not_called()
+
+    @patch('railtracks_cli.send_to_stream')
+    @patch('railtracks_cli.print_status')
+    @patch('time.time')
+    def test_file_change_handler_debouncing(self, mock_time, mock_print, mock_stream):
+        """Test debouncing prevents rapid duplicate events"""
+        # Set up time mock to simulate rapid changes
+        mock_time.side_effect = [1.0, 1.1, 1.6]  # Second call within debounce, third outside
+
+        mock_event = MagicMock()
+        mock_event.is_directory = False
+        mock_event.src_path = "/test/path/file.json"
+
+        # First call should process
+        self.handler.on_modified(mock_event)
+        self.assertEqual(mock_print.call_count, 1)
+        self.assertEqual(mock_stream.call_count, 1)
+
+        # Second call within debounce interval should be ignored
+        self.handler.on_modified(mock_event)
+        self.assertEqual(mock_print.call_count, 1)  # Still 1
+        self.assertEqual(mock_stream.call_count, 1)  # Still 1
+
+        # Third call outside debounce interval should process
+        self.handler.on_modified(mock_event)
+        self.assertEqual(mock_print.call_count, 2)
+        self.assertEqual(mock_stream.call_count, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()