stackport 0.1.8__tar.gz → 0.2.0__tar.gz

{stackport-0.1.8/stackport.egg-info → stackport-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackport
-Version: 0.1.8
+Version: 0.2.0
 Summary: Universal AWS resource browser for local emulators
 Author: Davi Reis Vieira
 License: MIT
@@ -24,6 +24,9 @@ License-File: LICENSE
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: boto3>=1.35.0
+Requires-Dist: click>=8.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: python-multipart>=0.0.26
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: httpx>=0.27.0; extra == "dev"
@@ -31,7 +34,7 @@ Requires-Dist: moto[dynamodb,iam,lambda,s3,sqs]>=5.0; extra == "dev"
 Dynamic: license-file
 
 <p align="center">
-  <img src="docs/images/stackport_logo.svg" alt="StackPort — Universal AWS Resource Browser" width="150"/>
+  <img src="https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/stackport_logo.svg" alt="StackPort — Universal AWS Resource Browser" width="150"/>
 </p>
 
 <h1 align="center">StackPort</h1>
@@ -50,13 +53,13 @@ Dynamic: license-file
 ## Screenshots
 
 **Dashboard** — Service overview with resource counts and health status
-![StackPort Dashboard](docs/images/dashboard.jpeg?v=1)
+![StackPort Dashboard](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/dashboard.jpeg)
 
 **DynamoDB Browser** — Generic resource table with search, pagination, and detail view
-![DynamoDB Resources](docs/images/dynamo.jpeg?v=1)
+![DynamoDB Resources](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/dynamo.jpeg)
 
 **S3 Browser** — File browser with folder navigation and object preview
-![S3 Browser](docs/images/s3.jpeg?v=1)
+![S3 Browser](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/s3.jpeg)
 
 ## Features
 
@@ -120,6 +123,7 @@ AWS_ENDPOINT_URL=http://my-emulator:4566 stackport
 | `AWS_ACCESS_KEY_ID` | `test` | AWS access key |
 | `AWS_SECRET_ACCESS_KEY` | `test` | AWS secret key |
 | `STACKPORT_PORT` | `8080` | StackPort server port |
+| `STACKPORT_S3_MAX_UPLOAD_MB` | `100` | Max upload size for a single S3 object, in whole **mebibytes (MiB)** (× 1024²). Example: `1000` for about 1000 MiB. Omit for the default (100 MiB). |
 | `STACKPORT_SERVICES` | *(35 services)* | Comma-separated services to probe |
 | `LOG_LEVEL` | `INFO` | Python log level (DEBUG shows healthcheck logs) |
 
@@ -140,6 +144,22 @@ cd ui && npm install && npm run dev
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
 
+## Star History
+
+<a href="https://star-history.com/#DaviReisVieira/stackport&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date" width="100%" />
+ </picture>
+</a>
+
+## Contributors
+
+<a href="https://github.com/DaviReisVieira/stackport/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=DaviReisVieira/stackport" alt="Contributors" />
+</a>
+
 ## License
 
 MIT

{stackport-0.1.8 → stackport-0.2.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/images/stackport_logo.svg" alt="StackPort — Universal AWS Resource Browser" width="150"/>
+  <img src="https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/stackport_logo.svg" alt="StackPort — Universal AWS Resource Browser" width="150"/>
 </p>
 
 <h1 align="center">StackPort</h1>
@@ -18,13 +18,13 @@
 ## Screenshots
 
 **Dashboard** — Service overview with resource counts and health status
-![StackPort Dashboard](docs/images/dashboard.jpeg?v=1)
+![StackPort Dashboard](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/dashboard.jpeg)
 
 **DynamoDB Browser** — Generic resource table with search, pagination, and detail view
-![DynamoDB Resources](docs/images/dynamo.jpeg?v=1)
+![DynamoDB Resources](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/dynamo.jpeg)
 
 **S3 Browser** — File browser with folder navigation and object preview
-![S3 Browser](docs/images/s3.jpeg?v=1)
+![S3 Browser](https://raw.githubusercontent.com/DaviReisVieira/stackport/main/docs/images/s3.jpeg)
 
 ## Features
 
@@ -88,6 +88,7 @@ AWS_ENDPOINT_URL=http://my-emulator:4566 stackport
 | `AWS_ACCESS_KEY_ID` | `test` | AWS access key |
 | `AWS_SECRET_ACCESS_KEY` | `test` | AWS secret key |
 | `STACKPORT_PORT` | `8080` | StackPort server port |
+| `STACKPORT_S3_MAX_UPLOAD_MB` | `100` | Max upload size for a single S3 object, in whole **mebibytes (MiB)** (× 1024²). Example: `1000` for about 1000 MiB. Omit for the default (100 MiB). |
 | `STACKPORT_SERVICES` | *(35 services)* | Comma-separated services to probe |
 | `LOG_LEVEL` | `INFO` | Python log level (DEBUG shows healthcheck logs) |
 
@@ -108,6 +109,22 @@ cd ui && npm install && npm run dev
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
 
+## Star History
+
+<a href="https://star-history.com/#DaviReisVieira/stackport&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=DaviReisVieira/stackport&type=Date" width="100%" />
+ </picture>
+</a>
+
+## Contributors
+
+<a href="https://github.com/DaviReisVieira/stackport/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=DaviReisVieira/stackport" alt="Contributors" />
+</a>
+
 ## License
 
 MIT

stackport-0.2.0/backend/aws_client.py

@@ -0,0 +1,31 @@
+import functools
+
+import boto3
+
+from backend.config import (
+    AWS_ACCESS_KEY_ID,
+    AWS_REGION,
+    AWS_SECRET_ACCESS_KEY,
+    DEFAULT_ENDPOINT,
+)
+
+
+@functools.lru_cache(maxsize=128)
+def get_client(service_name: str, endpoint_url: str | None = None):
+    """Return a boto3 client for the given service and endpoint.
+
+    Args:
+        service_name: AWS service name (e.g., "s3", "dynamodb")
+        endpoint_url: Endpoint URL to use. If None, uses DEFAULT_ENDPOINT.
+
+    Returns:
+        Configured boto3 client
+    """
+    url = endpoint_url if endpoint_url is not None else DEFAULT_ENDPOINT
+    return boto3.client(
+        service_name,
+        endpoint_url=url,
+        region_name=AWS_REGION,
+        aws_access_key_id=AWS_ACCESS_KEY_ID,
+        aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
+    )

{stackport-0.1.8 → stackport-0.2.0}/backend/cache.py

@@ -1,11 +1,14 @@
 import threading
 import time
 
+from backend.config import STACKPORT_CACHE_TTL
+
 
 class TTLCache:
-    def __init__(self):
+    def __init__(self, default_ttl: int = STACKPORT_CACHE_TTL):
         self._store: dict = {}
         self._lock = threading.Lock()
+        self._default_ttl = default_ttl
 
     def get(self, key: str):
         with self._lock:
@@ -16,9 +19,15 @@ class TTLCache:
                 del self._store[key]
         return None
 
-    def set(self, key: str, value, ttl: float = 5):
+    def set(self, key: str, value, ttl: float | None = None):
+        if ttl is None:
+            ttl = self._default_ttl
         with self._lock:
             self._store[key] = (value, time.time() + ttl)
 
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._store.pop(key, None)
+
 
 cache = TTLCache()

stackport-0.2.0/backend/cli.py

@@ -0,0 +1,259 @@
+"""CLI commands for StackPort."""
+
+import csv
+import json
+import logging
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import click
+import uvicorn
+
+from backend.aws_client import get_client
+from backend.config import AWS_ENDPOINT_URL, AWS_REGION, LOG_LEVEL, STACKPORT_PORT, STACKPORT_SERVICES
+from backend.routes.resources import DESCRIBE_REGISTRY, _extract_id, _serialize
+from backend.routes.stats import SERVICE_REGISTRY, _METHOD_KWARGS, _count_items, _probe_service
+
+logger = logging.getLogger(__name__)
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="stackport")
+@click.pass_context
+def cli(ctx):
+    """StackPort - Universal AWS resource browser for local emulators."""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(serve)
+
+
+@cli.command()
+@click.option("--port", default=STACKPORT_PORT, help="HTTP port")
+def serve(port):
+    """Start the StackPort web server (default command)."""
+    uvicorn.run("backend.main:app", host="0.0.0.0", port=port, log_level=LOG_LEVEL.lower(), reload=False)
+
+
+@cli.command()
+@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
+@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--output", type=click.Choice(["json", "table"]), default="table", help="Output format")
+def status(endpoint, region, output):
+    """Show all services with availability and resource counts."""
+    # Override endpoint/region if provided
+    if endpoint != AWS_ENDPOINT_URL:
+        import os
+
+        os.environ["AWS_ENDPOINT_URL"] = endpoint
+    if region != AWS_REGION:
+        import os
+
+        os.environ["AWS_REGION"] = region
+
+    enabled_services = [s.strip() for s in STACKPORT_SERVICES.split(",") if s.strip()]
+    services = {}
+
+    try:
+        with ThreadPoolExecutor(max_workers=min(len(enabled_services), 10)) as executor:
+            futures = {executor.submit(_probe_service, svc): svc for svc in enabled_services}
+            for future in as_completed(futures):
+                svc_name, result = future.result()
+                services[svc_name] = result
+    except Exception as exc:
+        click.echo(f"Error probing services: {exc}", err=True)
+        sys.exit(2)
+
+    sorted_services = dict(sorted(services.items()))
+
+    if output == "json":
+        click.echo(json.dumps(sorted_services, indent=2))
+    else:
+        # Table format
+        click.echo(f"{'SERVICE':<25} {'STATUS':<12} {'RESOURCES'}")
+        click.echo("-" * 60)
+        for svc_name, result in sorted_services.items():
+            status_str = result["status"]
+            resources = result.get("resources", {})
+            total = sum(resources.values())
+            resource_summary = ", ".join(f"{rt}={c}" for rt, c in resources.items() if c > 0) if resources else "-"
+            if len(resource_summary) > 30:
+                resource_summary = f"{total} total"
+            click.echo(f"{svc_name:<25} {status_str:<12} {resource_summary}")
+
+    sys.exit(0)
+
+
+@cli.command()
+@click.argument("service")
+@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
+@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--output", type=click.Choice(["json", "table", "csv"]), default="table", help="Output format")
+def list(service, endpoint, region, output):
+    """List resources for a service."""
+    # Override endpoint/region if provided
+    if endpoint != AWS_ENDPOINT_URL:
+        import os
+
+        os.environ["AWS_ENDPOINT_URL"] = endpoint
+    if region != AWS_REGION:
+        import os
+
+        os.environ["AWS_REGION"] = region
+
+    registry_entries = SERVICE_REGISTRY.get(service)
+    if not registry_entries:
+        valid_services = ", ".join(sorted(SERVICE_REGISTRY.keys()))
+        click.echo(f"Error: Unknown service '{service}'.", err=True)
+        click.echo(f"Valid services: {valid_services}", err=True)
+        sys.exit(1)
+
+    resources = {}
+    for resource_type, boto3_service, method_name, response_key in registry_entries:
+        try:
+            client = get_client(boto3_service)
+            method = getattr(client, method_name)
+            kwargs = _METHOD_KWARGS.get((boto3_service, method_name), {})
+            resp = method(**kwargs)
+            items = resp.get(response_key, [])
+            # Handle nested structures (e.g., cloudfront DistributionList.Items)
+            if isinstance(items, dict) and "Items" in items:
+                items = items.get("Items", []) or []
+            resources[resource_type] = items
+        except Exception as exc:
+            logger.debug("Failed to list %s/%s: %s", service, resource_type, exc, exc_info=True)
+            resources[resource_type] = []
+
+    if output == "json":
+        serialized = {rt: [_serialize(item) if isinstance(item, dict) else item for item in items] for rt, items in resources.items()}
+        click.echo(json.dumps({"service": service, "resources": serialized}, indent=2))
+    elif output == "csv":
+        writer = csv.writer(sys.stdout)
+        writer.writerow(["service", "resource_type", "resource_id", "name"])
+        for resource_type, items in resources.items():
+            for item in items:
+                resource_id = _extract_id(item)
+                name = item.get("Name", item.get("FunctionName", item.get("TableName", resource_id))) if isinstance(item, dict) else resource_id
+                writer.writerow([service, resource_type, resource_id, name])
+    else:
+        # Table format
+        for resource_type, items in resources.items():
+            if items:
+                click.echo(f"\n{resource_type.upper()} ({len(items)}):")
+                click.echo("-" * 60)
+                for item in items[:20]:  # Limit to first 20 for readability
+                    resource_id = _extract_id(item)
+                    if isinstance(item, dict):
+                        name = item.get("Name", item.get("FunctionName", item.get("TableName", "")))
+                        if name and name != resource_id:
+                            click.echo(f"  {resource_id} ({name})")
+                        else:
+                            click.echo(f"  {resource_id}")
+                    else:
+                        click.echo(f"  {item}")
+                if len(items) > 20:
+                    click.echo(f"  ... and {len(items) - 20} more")
+
+    sys.exit(0)
+
+
+@cli.command()
+@click.argument("service")
+@click.argument("resource_type")
+@click.argument("resource_id")
+@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
+@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--output", type=click.Choice(["json", "table"]), default="json", help="Output format")
+def describe(service, resource_type, resource_id, endpoint, region, output):
+    """Describe a specific resource."""
+    # Override endpoint/region if provided
+    if endpoint != AWS_ENDPOINT_URL:
+        import os
+
+        os.environ["AWS_ENDPOINT_URL"] = endpoint
+    if region != AWS_REGION:
+        import os
+
+        os.environ["AWS_REGION"] = region
+
+    # Special case for WAFv2
+    if (service, resource_type) == ("wafv2", "web_acls"):
+        try:
+            client = get_client("wafv2")
+            acls = client.list_web_acls(Scope="REGIONAL").get("WebACLs", [])
+            match = next((a for a in acls if a.get("Name") == resource_id), None)
+            if not match:
+                click.echo(f"Error: Web ACL '{resource_id}' not found", err=True)
+                sys.exit(1)
+            resp = client.get_web_acl(Name=resource_id, Scope="REGIONAL", Id=match["Id"])
+            resp.pop("ResponseMetadata", None)
+            detail = _serialize(resp.get("WebACL", resp))
+        except Exception as exc:
+            click.echo(f"Error describing {service}/{resource_type}/{resource_id}: {exc}", err=True)
+            sys.exit(1)
+    else:
+        lookup = DESCRIBE_REGISTRY.get((service, resource_type))
+        if not lookup:
+            click.echo(f"Error: No detail lookup registered for {service}/{resource_type}", err=True)
+            sys.exit(1)
+
+        boto3_service, method_name, id_param, response_key = lookup
+
+        # Some APIs take list parameters
+        _LIST_PARAMS = {
+            "InstanceIds",
+            "VpcIds",
+            "SubnetIds",
+            "GroupIds",
+            "VolumeIds",
+            "repositoryNames",
+            "clusters",
+            "AlarmNames",
+            "LoadBalancerArns",
+        }
+
+        try:
+            client = get_client(boto3_service)
+            method = getattr(client, method_name)
+            if id_param in _LIST_PARAMS:
+                resp = method(**{id_param: [resource_id]})
+            else:
+                resp = method(**{id_param: resource_id})
+
+            resp.pop("ResponseMetadata", None)
+
+            if response_key is not None:
+                detail = resp.get(response_key, resp)
+            else:
+                detail = resp
+
+            detail = _serialize(detail)
+        except Exception as exc:
+            click.echo(f"Error describing {service}/{resource_type}/{resource_id}: {exc}", err=True)
+            sys.exit(1)
+
+    if output == "json":
+        click.echo(json.dumps(detail, indent=2))
+    else:
+        # Table format - simple key-value pairs
+        if isinstance(detail, dict):
+            for key, value in detail.items():
+                click.echo(f"{key}: {value}")
+        elif isinstance(detail, list) and len(detail) > 0:
+            # If detail is a list, show first item
+            for key, value in detail[0].items():
+                click.echo(f"{key}: {value}")
+        else:
+            click.echo(json.dumps(detail, indent=2))
+
+    sys.exit(0)
+
+
+@cli.command()
+@click.argument("service")
+@click.option("--endpoint", default=AWS_ENDPOINT_URL, help="AWS endpoint URL", envvar="AWS_ENDPOINT_URL")
+@click.option("--region", default=AWS_REGION, help="AWS region", envvar="AWS_REGION")
+@click.option("--format", "format_", type=click.Choice(["json", "csv"]), default="json", help="Output format")
+@click.pass_context
+def export(ctx, service, endpoint, region, format_):
+    """Export all resources for a service."""
+    # Reuse list command logic
+    ctx.invoke(list, service=service, endpoint=endpoint, region=region, output=format_)

stackport-0.2.0/backend/config.py

@@ -0,0 +1,84 @@
+import logging
+import os
+from collections.abc import Mapping
+
+logger = logging.getLogger(__name__)
+
+AWS_ENDPOINT_URL: str = os.environ.get("AWS_ENDPOINT_URL", "http://localhost:4566")
+AWS_REGION: str = os.environ.get("AWS_REGION", "us-east-1")
+AWS_ACCESS_KEY_ID: str = os.environ.get("AWS_ACCESS_KEY_ID", "test")
+AWS_SECRET_ACCESS_KEY: str = os.environ.get("AWS_SECRET_ACCESS_KEY", "test")
+STACKPORT_PORT: int = int(os.environ.get("STACKPORT_PORT", "8080"))
+STACKPORT_SERVICES: str = os.environ.get(
+    "STACKPORT_SERVICES",
+    "s3,sqs,sns,dynamodb,lambda,iam,logs,ssm,secretsmanager,kinesis,events,ec2,"
+    "route53,kms,cloudformation,stepfunctions,rds,ecs,monitoring,ses,acm,wafv2,"
+    "ecr,elasticache,glue,athena,apigateway,firehose,cognito-idp,cognito-identity,"
+    "elasticmapreduce,elasticloadbalancing,elasticfilesystem,cloudfront,appsync",
+)
+LOG_LEVEL: str = os.environ.get("LOG_LEVEL", "INFO").upper()
+
+# Probe and cache configuration
+STACKPORT_PROBE_TIMEOUT: int = int(os.environ.get("STACKPORT_PROBE_TIMEOUT", "5"))
+STACKPORT_CACHE_TTL: int = int(os.environ.get("STACKPORT_CACHE_TTL", "5"))
+STACKPORT_PROBE_WORKERS: int = int(os.environ.get("STACKPORT_PROBE_WORKERS", "10"))
+
+_MIB: int = 1024 * 1024
+
+# Default max upload: 100 MiB (whole mebibytes; STACKPORT_S3_MAX_UPLOAD_MB).
+_DEFAULT_S3_MAX_UPLOAD_MB: int = 100
+_DEFAULT_S3_MAX_UPLOAD_BYTES: int = _DEFAULT_S3_MAX_UPLOAD_MB * _MIB
+
+
+def _parse_s3_max_upload_bytes_from_env(environ: Mapping[str, str]) -> int:
+    """Resolve max single-object upload size for the S3 write API.
+
+    Uses ``STACKPORT_S3_MAX_UPLOAD_MB`` only: positive integer **mebibytes** (MiB,
+    × 1024²). When unset or empty, default is 100 MiB.
+    """
+    raw_mb = environ.get("STACKPORT_S3_MAX_UPLOAD_MB")
+    if raw_mb is None or not str(raw_mb).strip():
+        return _DEFAULT_S3_MAX_UPLOAD_BYTES
+    try:
+        mb = int(str(raw_mb).strip(), 10)
+    except ValueError:
+        logger.warning(
+            "Invalid STACKPORT_S3_MAX_UPLOAD_MB %r; using default %s MiB",
+            raw_mb,
+            _DEFAULT_S3_MAX_UPLOAD_MB,
+        )
+        return _DEFAULT_S3_MAX_UPLOAD_BYTES
+    if mb <= 0:
+        logger.warning(
+            "STACKPORT_S3_MAX_UPLOAD_MB must be positive; using default %s MiB",
+            _DEFAULT_S3_MAX_UPLOAD_MB,
+        )
+        return _DEFAULT_S3_MAX_UPLOAD_BYTES
+    return mb * _MIB
+
+
+def _parse_s3_max_upload_bytes() -> int:
+    return _parse_s3_max_upload_bytes_from_env(os.environ)
+
+
+# Max single-object upload size for S3 write API (configurable; default 100 MiB).
+S3_MAX_UPLOAD_BYTES: int = _parse_s3_max_upload_bytes()
+
+
+def _parse_endpoints() -> dict[str, str]:
+    """Parse STACKPORT_ENDPOINTS env var into dict."""
+    endpoints_str = os.environ.get("STACKPORT_ENDPOINTS", "")
+    if not endpoints_str:
+        # Backward compatibility: single endpoint
+        return {"default": AWS_ENDPOINT_URL}
+
+    endpoints = {}
+    for pair in endpoints_str.split(","):
+        if "=" in pair:
+            name, url = pair.split("=", 1)
+            endpoints[name.strip()] = url.strip()
+    return endpoints
+
+
+ENDPOINTS: dict[str, str] = _parse_endpoints()
+DEFAULT_ENDPOINT: str = next(iter(ENDPOINTS.values()))

{stackport-0.1.8 → stackport-0.2.0}/backend/main.py

@@ -1,14 +1,17 @@
+import asyncio
 import logging
 import os
+from contextlib import asynccontextmanager
 
 import uvicorn
-from fastapi import FastAPI
+from fastapi import FastAPI, WebSocket
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
 from backend.config import LOG_LEVEL, STACKPORT_PORT
-from backend.routes import dynamodb, ec2, iam, lambda_svc, logs, resources, s3, secretsmanager, sqs, stats
+from backend.routes import dynamodb, ec2, endpoints, iam, lambda_svc, logs, resources, s3, secretsmanager, sqs, stats, tags
+from backend.websocket import probe_loop, websocket_endpoint
 
 
 class HealthcheckFilter(logging.Filter):
@@ -30,7 +33,16 @@ logger = logging.getLogger(__name__)
 # Suppress noisy healthcheck access logs at non-DEBUG levels
 logging.getLogger("uvicorn.access").addFilter(HealthcheckFilter())
 
-app = FastAPI(title="StackPort", docs_url="/api/docs")
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: launch the WebSocket probe loop
+    task = asyncio.create_task(probe_loop())
+    yield
+    # Shutdown: cancel the background task
+    task.cancel()
+
+
+app = FastAPI(title="StackPort", docs_url="/api/docs", lifespan=lifespan)
 
 app.add_middleware(
     CORSMiddleware,
@@ -40,6 +52,7 @@ app.add_middleware(
 )
 
 app.include_router(stats.router, prefix="/api")
+app.include_router(endpoints.router, prefix="/api")
 app.include_router(s3.router, prefix="/api/s3")
 app.include_router(dynamodb.router, prefix="/api/dynamodb")
 app.include_router(lambda_svc.router, prefix="/api/lambda", tags=["lambda"])
@@ -48,8 +61,16 @@ app.include_router(iam.router, prefix="/api/iam", tags=["iam"])
 app.include_router(ec2.router, prefix="/api/ec2", tags=["ec2"])
 app.include_router(logs.router, prefix="/api/logs", tags=["logs"])
 app.include_router(secretsmanager.router, prefix="/api/secretsmanager", tags=["secretsmanager"])
+app.include_router(tags.router, prefix="/api", tags=["tags"])
 app.include_router(resources.router, prefix="/api")
 
+
+# WebSocket endpoint for real-time updates
+@app.websocket("/ws")
+async def ws(websocket: WebSocket):
+    await websocket_endpoint(websocket)
+
+
 # Serve UI static files — mount assets under /assets, SPA fallback for everything else
 ui_dist = os.path.join(os.path.dirname(__file__), "..", "ui", "dist")
 if os.path.isdir(ui_dist):
@@ -66,7 +87,10 @@ if os.path.isdir(ui_dist):
 
 
 def cli():
-    uvicorn.run("backend.main:app", host="0.0.0.0", port=STACKPORT_PORT, log_level=LOG_LEVEL.lower(), reload=False)
+    """Entry point for stackport CLI."""
+    from backend.cli import cli as click_app
+
+    click_app()
 
 
 if __name__ == "__main__":

stackport-0.2.0/backend/routes/common.py

@@ -0,0 +1,25 @@
+"""Common route dependencies and utilities."""
+
+from fastapi import Query
+
+from backend.config import DEFAULT_ENDPOINT, ENDPOINTS
+
+
+def get_endpoint_url(endpoint: str | None = Query(None, description="Endpoint name or URL")) -> str:
+    """Extract and validate endpoint from query params.
+
+    Args:
+        endpoint: Endpoint name (e.g., "local") or direct URL. If None, uses default.
+
+    Returns:
+        Endpoint URL to use for AWS API calls
+    """
+    if endpoint is None:
+        return DEFAULT_ENDPOINT
+
+    # Check if it's a known endpoint name
+    if endpoint in ENDPOINTS:
+        return ENDPOINTS[endpoint]
+
+    # Otherwise treat as direct URL (for flexibility)
+    return endpoint

stackport-0.2.0/backend/routes/endpoints.py

@@ -0,0 +1,33 @@
+"""Endpoints management routes."""
+
+import logging
+
+from fastapi import APIRouter
+
+from backend.aws_client import get_client
+from backend.config import ENDPOINTS
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/endpoints")
+def list_endpoints():
+    """List configured endpoints with health status."""
+    results = []
+
+    for name, url in ENDPOINTS.items():
+        health = "unknown"
+        try:
+            # Quick health check - try to list S3 buckets
+            s3 = get_client("s3", url)
+            s3.list_buckets()
+            health = "healthy"
+        except Exception:
+            logger.debug("Endpoint %s (%s) unhealthy", name, url, exc_info=True)
+            health = "unhealthy"
+
+        results.append({"name": name, "url": url, "health": health})
+
+    return {"endpoints": results}