Merge pull request #140 from awslabs/feat/package-namespace-migration

refactor: consolidate package namespace under src/orb and enhance SDK and API consistency

Author: fgogolli

.githooks/README.md

@@ -17,6 +17,9 @@ This configures git to use `.githooks/` instead of `.git/hooks/`.
 ### pre-commit
 Runs quality checks via `pre-commit run` (reads `.pre-commit-config.yaml`, skips manual-stage hooks).
 
+### pre-push
+Runs pre-push stage hooks from `.pre-commit-config.yaml` (bandit, safety, validate-imports, validate-cqrs, check-architecture, validate-workflows).
+
 ## Adding Custom Hooks
 
 Add a new file to `.githooks/` and it will be version controlled:

.githooks/pre-push

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+# Run pre-push checks (reads .pre-commit-config.yaml, pre-push stage hooks)
+pre-commit run --hook-stage pre-push

.github/workflows/dev-containers.yml

@@ -161,7 +161,7 @@ jobs:
         fi
 
     - name: Run Trivy security scan
-      uses: aquasecurity/trivy-action@0.34.0
+      uses: aquasecurity/trivy-action@0.34.2
       with:
         image-ref: "${{ needs.config.outputs.container-registry }}/${{ needs.config.outputs.container-image }}:${{ needs.config.outputs.package-version }}-python${{ matrix.python-version }}"
         format: 'sarif'

.github/workflows/package-testing.yml

@@ -84,10 +84,10 @@ jobs:
           
           # Test core imports always work
           try:
-              import run
-              from bootstrap import Application
-              from domain.base.exceptions import DomainException
-              from infrastructure.logging.logger import get_logger
+              import orb.run
+              from orb.bootstrap import Application
+              from orb.domain.base.exceptions import DomainException
+              from orb.infrastructure.logging.logger import get_logger
               print('PASS: Core imports successful')
           except ImportError as e:
               print(f'FAIL: Core import failed: {e}')
@@ -97,20 +97,20 @@ jobs:
       - name: Test CLI functionality
         run: |
           # Test basic CLI works
-          python -m run --help
-          python -m run --version
-          
+          python -m orb --help
+          python -m orb --version
+
           # Test commands that should work in all variants
-          python -m run templates list --help || echo "Templates command help failed (expected in some cases)"
+          python -m orb templates list --help || echo "Templates command help failed (expected in some cases)"
 
       - name: Test CLI Rich formatting
         if: matrix.variant.test_cli_rich
         run: |
           python -c "
           try:
-              from cli.formatters import format_generic_table
-              from cli.console import get_console
-              
+              from orb.cli.formatters import format_generic_table
+              from orb.cli.console import get_console
+
               # Test Rich table formatting
               test_data = [{'id': '1', 'name': 'test'}]
               result = format_generic_table(test_data, 'Test Items')
@@ -137,9 +137,9 @@ jobs:
               print('PASS: Rich correctly not available in minimal variant')
           
           # Test CLI still works with fallbacks
-          from cli.formatters import format_generic_table
-          from cli.console import get_console
-          
+          from orb.cli.formatters import format_generic_table
+          from orb.cli.console import get_console
+
           test_data = [{'id': '1', 'name': 'test'}]
           result = format_generic_table(test_data, 'Test Items')
           print('PASS: CLI fallback formatting works')
@@ -154,7 +154,7 @@ jobs:
         run: |
           python -c "
           try:
-              from api.server import create_fastapi_app
+              from orb.api.server import create_fastapi_app
               print('PASS: FastAPI imports successful')
               
               # Test app creation (basic test)
@@ -177,7 +177,7 @@ jobs:
           
           # Test that API server creation fails gracefully
           try:
-              from api.server import create_fastapi_app
+              from orb.api.server import create_fastapi_app
               try:
                   create_fastapi_app(None)
                   print('FAIL: API should have failed without FastAPI')
@@ -197,7 +197,7 @@ jobs:
         run: |
           python -c "
           try:
-              from monitoring.health import HealthCheck
+              from orb.monitoring.health import HealthCheck
               print('PASS: Monitoring imports successful')
               
               # Test basic monitoring functionality
@@ -225,7 +225,7 @@ jobs:
           
           # Monitoring should still import but with limited functionality
           try:
-              from monitoring.health import HealthCheck
+              from orb.monitoring.health import HealthCheck
               print('PASS: Monitoring module imports with limited functionality')
           except ImportError as e:
               print(f'FAIL: Monitoring module should import even without optional deps: {e}')
@@ -262,7 +262,7 @@ jobs:
           # Test CLI without Rich
           with patch.dict(sys.modules, {'rich': None, 'rich.console': None, 'rich.table': None}):
               try:
-                  from cli.console import get_console, print_success
+                  from orb.cli.console import get_console, print_success
                   console = get_console()
                   print('PASS: CLI console works without Rich')
               except Exception as e:
@@ -272,7 +272,7 @@ jobs:
           # Test API without FastAPI
           with patch.dict(sys.modules, {'fastapi': None}):
               try:
-                  from api.server import create_fastapi_app
+                  from orb.api.server import create_fastapi_app
                   try:
                       create_fastapi_app(None)
                       print('FAIL: API should fail without FastAPI')
@@ -322,13 +322,13 @@ jobs:
                   print(f'PASS: {dep} correctly not available')
           
           # Test that core functionality still works
-          import run
-          from bootstrap import Application
-          from domain.base.exceptions import DomainException
+          import orb.run
+          from orb.bootstrap import Application
+          from orb.domain.base.exceptions import DomainException
           print('PASS: Core functionality works without optional deps')
-          
+
           # Test CLI with fallbacks
-          from cli.console import get_console
+          from orb.cli.console import get_console
           console = get_console()
           console.print('Test message')
           print('PASS: CLI works with fallbacks')
@@ -360,7 +360,7 @@ jobs:
           
           # Test API error message
           try:
-              from api.server import create_fastapi_app
+              from orb.api.server import create_fastapi_app
               try:
                   create_fastapi_app(None)
                   print('FAIL: API should have failed')
@@ -404,10 +404,10 @@ jobs:
           # Test all functionality works together
           python -c "
           # Test all imports work
-          from cli.formatters import format_generic_table
-          from cli.console import get_console
-          from api.server import create_fastapi_app
-          from monitoring.health import HealthCheck
+          from orb.cli.formatters import format_generic_table
+          from orb.cli.console import get_console
+          from orb.api.server import create_fastapi_app
+          from orb.monitoring.health import HealthCheck
           
           print('PASS: All modules import successfully')
           
@@ -426,8 +426,8 @@ jobs:
 
       - name: Test CLI commands
         run: |
-          python -m run --help
-          python -m run --version
+          python -m orb --help
+          python -m orb --version
           echo "PASS: CLI commands work"
 
   summary:

.github/workflows/reusable-security.yml

@@ -74,7 +74,7 @@ jobs:
       # Trivy Filesystem Scan
       - name: Run Trivy filesystem vulnerability scanner
         if: inputs.scan-type == 'trivy-fs'
-        uses: aquasecurity/trivy-action@0.34.0
+        uses: aquasecurity/trivy-action@0.34.2
         with:
           scan-type: 'fs'
           scan-ref: '.'

.github/workflows/test-matrix.yml

@@ -106,38 +106,40 @@ jobs:
         run: |
           python -c "
           import sys
-          
+          variant = '${{ matrix.package-variant }}'
+
           # Test basic imports (should always work)
           try:
-              import orb_py
-              print('✓ Basic orb_py import works')
+              import orb
+              print('✓ Basic orb import works')
           except ImportError as e:
-              print(f'✗ Basic orb_py import failed: {e}')
+              print(f'✗ Basic orb import failed: {e}')
               sys.exit(1)
 
-          # Test CLI imports
-          try:
-              from cli.formatters import format_table
-              print('✓ CLI formatters import works')
-          except ImportError as e:
-              if '${{ matrix.package-variant }}' in ['.', '.[api]', '.[monitoring]']:
-                  print(f'✓ Expected CLI import failure for ${{ matrix.package-variant }}: {e}')
-              else:
-                  print(f'✗ Unexpected CLI import failure: {e}')
+          # Test CLI flag: RICH_AVAILABLE reflects whether rich is installed
+          from orb.cli.console import RICH_AVAILABLE
+          if variant in ['.[cli]', '.[all]']:
+              if not RICH_AVAILABLE:
+                  print(f'✗ Expected RICH_AVAILABLE=True for {variant} but got False')
                   sys.exit(1)
+              print(f'✓ RICH_AVAILABLE=True as expected for {variant}')
+          else:
+              print(f'✓ RICH_AVAILABLE={RICH_AVAILABLE} (rich not required for {variant})')
 
-          # Test API imports
+          # Test API imports: fastapi is only available with .[api] or .[all]
           try:
-              from interface.serve_command_handler import handle_serve_command
-              print('✓ API handler import works')
+              from orb.api.routers.machines import router
+              if variant in ['.', '.[cli]', '.[monitoring]']:
+                  print(f'✗ Expected API import to fail for {variant} but it succeeded')
+                  sys.exit(1)
+              print(f'✓ API router import works for {variant}')
           except ImportError as e:
-              if '${{ matrix.package-variant }}' in ['.', '.[cli]', '.[monitoring]']:
-                  print(f'✓ Expected API import failure for ${{ matrix.package-variant }}: {e}')
-              else:
-                  print(f'✗ Unexpected API import failure: {e}')
+              if variant in ['.[api]', '.[all]']:
+                  print(f'✗ Unexpected API import failure for {variant}: {e}')
                   sys.exit(1)
-          
-          print('✓ All import tests passed for ${{ matrix.package-variant }}')
+              print(f'✓ Expected API import failure for {variant}')
+
+          print(f'✓ All import tests passed for {variant}')
           "
 
   e2e-tests:

.gitignore

@@ -120,10 +120,15 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 .mypy_cache/
+pytest-of-*/
+
+# CLI tool caches
+*_cache_*/
 
 # Documentation
 docs-backup/
 site/
+docs/site/
 
 # Internal
 memory-bank/

.project.yml

@@ -7,7 +7,7 @@ project:
   pypi_name: orb-py # PyPI distribution name
   short_name: orb # CLI command name
   version: 1.1.2
-  description: "Cloud provider integration plugin for IBM Spectrum Symphony Host Factory"
+  description: "Open Resource Broker (ORB) — dynamic cloud resource provisioning via CLI and REST API"
   author: "AWS Professional Services"
   email: "aws-proserve@amazon.com"
   license: "Apache-2.0"
@@ -20,6 +20,7 @@ repository:
   registry: ghcr.io # Container registry
 build:
   platforms: [linux/amd64, linux/arm64] # Container platforms
+  package_root: src/orb
 ci:
   test_timeout: 300 # Test timeout in seconds
   coverage_threshold: 70 # Minimum coverage percentage

Dockerfile

@@ -59,7 +59,7 @@ RUN uv pip install --no-cache /tmp/*.whl \
 
 # Copy only runtime files needed
 COPY config/ ./config/
-COPY src/infrastructure/scheduler/hostfactory/scripts/ ./scripts/
+COPY src/orb/infrastructure/scheduler/hostfactory/scripts/ ./scripts/
 COPY deployment/docker/docker-entrypoint.sh ./docker-entrypoint.sh
 
 # Set permissions and environment in single layer