@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/scripts/README.md

@@ -0,0 +1,89 @@
+---
+title: Tilt Library Build Caching
+status: backlog
+created: 2026-03-31
+updated: 2026-03-31
+---
+
+# Tilt Library Build Caching
+
+## Overview
+
+These scripts implement intelligent caching for library builds to avoid unnecessary rebuilds and republishes during `tilt up`.
+
+## How It Works
+
+### Check Script (`check-lib-publish.sh`)
+
+1. **Registry Check**: Queries Verdaccio to see if the package version is already published
+2. **Source Hash Check**: Computes a SHA-256 hash of all source files (src/, package.json, tsconfig.json)
+3. **Comparison**: Compares current hash with cached hash from last successful build
+4. **Decision**:
+   - If package published AND sources unchanged → **Skip rebuild** (exit 1)
+   - If package not published OR sources changed → **Rebuild needed** (exit 0)
+
+### Build Script (`build-and-publish-lib.sh`)
+
+1. Calls `check-lib-publish.sh` to determine if rebuild needed
+2. If skip indicated, exits early
+3. If rebuild needed:
+   - Runs full build pipeline (install, tsc, link, publish)
+   - Saves source hash to `.tilt-cache/source-hash.txt` on success
+   - Links package to consumer services if specified
+
+## Cache Location
+
+Each library maintains its own cache:
+```
+shared-platform-engineering/platform-logger/
+├── .tilt-cache/
+│   └── source-hash.txt  # SHA-256 hash of source files
+├── src/
+├── package.json
+└── tsconfig.json
+```
+
+## Benefits
+
+- **Faster `tilt up`**: Libraries only rebuild when sources actually change
+- **Idempotent**: Running `tilt up` multiple times doesn't cause unnecessary work
+- **Version Safety**: Warns if sources changed but version not bumped
+- **Verdaccio-aware**: Checks actual registry state, not just local build state
+
+## Manual Cache Clearing
+
+To force a rebuild of a specific library:
+```bash
+rm -rf shared-platform-engineering/platform-logger/.tilt-cache
+```
+
+To clear all library caches:
+```bash
+find . -type d -name '.tilt-cache' -path '*/shared-*' -exec rm -rf {} +
+```
+
+## Troubleshooting
+
+### Library not rebuilding when it should
+
+1. Check if version was bumped in package.json
+2. Verify source files are actually changing
+3. Clear cache and rebuild: `rm -rf <lib-path>/.tilt-cache && tilt up`
+
+### "Version already published" warning
+
+This means source files changed but package.json version wasn't bumped. Either:
+- Bump the version if this is a real change
+- Revert source changes if they were experimental
+- Manually unpublish from Verdaccio if needed
+
+## Implementation Details
+
+**Cache Key**: SHA-256 hash of concatenated contents of:
+- All files in `src/` directory
+- `package.json`
+- `tsconfig.json`
+
+**Registry Check**: HTTP GET to `<verdaccio-url>/<package-name>/<version>`
+- 200 = published
+- 404 = not published

package/engine/scripts/build-and-publish-lib.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# Library Build & Publish with Caching
+# =============================================================================
+# Intelligently builds and publishes libraries only when needed
+# =============================================================================
+
+set -euo pipefail
+
+LIB_PATH="${1:?Library path required}"
+REGISTRY="${2:-http://localhost:4873}"
+PACKAGE_NAME="${3:?Package name required}"
+CONSUMER_PATHS="${4:-}"  # Optional: comma-separated list of consumer paths
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+if [[ "${LIB_PATH}" = /* ]]; then
+  LIB_ABS_PATH="${LIB_PATH}"
+else
+  LIB_ABS_PATH="${WORKSPACE_ROOT}/${LIB_PATH}"
+fi
+
+CACHE_DIR="${LIB_ABS_PATH}/.tilt-cache"
+
+# Check if rebuild/republish is needed
+if ! "${SCRIPT_DIR}/check-lib-publish.sh" "${LIB_ABS_PATH}" "${REGISTRY}"; then
+  # Script exited with 1 (skip rebuild)
+  exit 0
+fi
+
+# Rebuild needed - run full pipeline
+cd "${LIB_ABS_PATH}"
+
+EFFECTIVE_REGISTRY="${REGISTRY%/}"
+if ! curl -sf --max-time 3 "${EFFECTIVE_REGISTRY}/-/ping" >/dev/null 2>&1; then
+  for fallback_registry in "http://localhost:4873" "http://verdaccio.localhost:4873"; do
+    if curl -sf --max-time 3 "${fallback_registry}/-/ping" >/dev/null 2>&1; then
+      echo "⚠️  Registry ${EFFECTIVE_REGISTRY} is unreachable, falling back to ${fallback_registry}"
+      EFFECTIVE_REGISTRY="${fallback_registry}"
+      break
+    fi
+  done
+fi
+
+echo "📦 Installing dependencies..."
+NPMRC_FOR_INSTALL=""
+if [[ "${EFFECTIVE_REGISTRY}" == *"host.docker.internal"* ]]; then
+  if [[ -f "${LIB_ABS_PATH}/autogenerated/.npmrc.docker.autogenerated" ]]; then
+    NPMRC_FOR_INSTALL="${LIB_ABS_PATH}/autogenerated/.npmrc.docker.autogenerated"
+  elif [[ -f "${LIB_ABS_PATH}/.npmrc.docker" ]]; then
+    NPMRC_FOR_INSTALL="${LIB_ABS_PATH}/.npmrc.docker"
+  fi
+fi
+
+if [[ -z "${NPMRC_FOR_INSTALL}" ]]; then
+  if [[ -f "${LIB_ABS_PATH}/autogenerated/.npmrc.autogenerated" ]]; then
+    NPMRC_FOR_INSTALL="${LIB_ABS_PATH}/autogenerated/.npmrc.autogenerated"
+  elif [[ -f "${LIB_ABS_PATH}/.npmrc" ]]; then
+    NPMRC_FOR_INSTALL="${LIB_ABS_PATH}/.npmrc"
+  elif [[ -f "${LIB_ABS_PATH}/.npmrc.docker" ]]; then
+    NPMRC_FOR_INSTALL="${LIB_ABS_PATH}/.npmrc.docker"
+  fi
+fi
+
+run_bun_install_with_retry() {
+  local npmrc_path="${1:-}"
+  local registry="${2:-}"
+  local attempt=1
+  local max_attempts=3
+  local exit_code=1
+  local install_env=()
+
+  if [[ -n "${registry}" ]]; then
+    install_env+=("npm_config_registry=${registry}")
+    if [[ "${PACKAGE_NAME}" == @*/* ]]; then
+      local package_scope="${PACKAGE_NAME%%/*}"
+      install_env+=("npm_config_${package_scope}:registry=${registry}")
+    fi
+  fi
+
+  while [[ ${attempt} -le ${max_attempts} ]]; do
+    set +e
+    if [[ -n "${npmrc_path}" ]]; then
+      env "${install_env[@]}" NPM_CONFIG_USERCONFIG="${npmrc_path}" bun install
+      exit_code=$?
+    else
+      env "${install_env[@]}" bun install
+      exit_code=$?
+    fi
+    set -e
+
+    if [[ ${exit_code} -eq 0 ]]; then
+      return 0
+    fi
+
+    if [[ ${attempt} -lt ${max_attempts} ]]; then
+      echo "⚠️  bun install failed (attempt ${attempt}/${max_attempts}), retrying..."
+      sleep $((attempt * 2))
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  return ${exit_code}
+}
+
+set +e
+run_bun_install_with_retry "${NPMRC_FOR_INSTALL}" "${EFFECTIVE_REGISTRY}"
+INSTALL_EXIT_CODE=$?
+set -e
+
+if [[ ${INSTALL_EXIT_CODE} -ne 0 ]]; then
+  RETRY_REGISTRY=""
+  RETRY_NPMRC=""
+  for fallback_registry in "http://localhost:4873" "http://verdaccio.localhost:4873" "https://registry.npmjs.org"; do
+    if [[ "${fallback_registry}" != "${EFFECTIVE_REGISTRY}" ]] && curl -sf --max-time 3 "${fallback_registry}/-/ping" >/dev/null 2>&1; then
+      RETRY_REGISTRY="${fallback_registry}"
+      break
+    fi
+  done
+
+  if [[ -n "${RETRY_REGISTRY}" ]]; then
+    if [[ "${RETRY_REGISTRY}" == *"host.docker.internal"* ]]; then
+      if [[ -f "${LIB_ABS_PATH}/autogenerated/.npmrc.docker.autogenerated" ]]; then
+        RETRY_NPMRC="${LIB_ABS_PATH}/autogenerated/.npmrc.docker.autogenerated"
+      elif [[ -f "${LIB_ABS_PATH}/.npmrc.docker" ]]; then
+        RETRY_NPMRC="${LIB_ABS_PATH}/.npmrc.docker"
+      fi
+    fi
+    if [[ -z "${RETRY_NPMRC}" ]]; then
+      if [[ -f "${LIB_ABS_PATH}/autogenerated/.npmrc.autogenerated" ]]; then
+        RETRY_NPMRC="${LIB_ABS_PATH}/autogenerated/.npmrc.autogenerated"
+      elif [[ -f "${LIB_ABS_PATH}/.npmrc" ]]; then
+        RETRY_NPMRC="${LIB_ABS_PATH}/.npmrc"
+      elif [[ -f "${LIB_ABS_PATH}/.npmrc.docker" ]]; then
+        RETRY_NPMRC="${LIB_ABS_PATH}/.npmrc.docker"
+      fi
+    fi
+
+    echo "⚠️  bun install failed, retrying with fallback registry ${RETRY_REGISTRY}"
+    run_bun_install_with_retry "${RETRY_NPMRC}" "${RETRY_REGISTRY}"
+    EFFECTIVE_REGISTRY="${RETRY_REGISTRY}"
+  else
+    exit ${INSTALL_EXIT_CODE}
+  fi
+fi
+
+echo "🔨 Building package..."
+if grep -q '"build":' package.json; then
+  bun run build
+else
+  if [ -f ".autogenerated/tsconfig.autogenerated.json" ]; then
+    bunx tsc -p .autogenerated/tsconfig.autogenerated.json --declaration --declarationMap --rootDir src --outDir dist
+  else
+    bunx tsc -p tsconfig.json --declaration --declarationMap --rootDir src --outDir dist
+  fi
+fi
+
+echo "🔗 Linking package..."
+bun link
+
+echo "📤 Publishing to registry..."
+# npm may prefer scoped registry config over --registry, so force both default
+# and scope-specific registry to avoid publishing to a different host.
+NPM_CONFIG_OVERRIDES=("npm_config_registry=${EFFECTIVE_REGISTRY}")
+if [[ "${PACKAGE_NAME}" == @*/* ]]; then
+  PACKAGE_SCOPE="${PACKAGE_NAME%%/*}"
+  NPM_CONFIG_OVERRIDES+=("npm_config_${PACKAGE_SCOPE}:registry=${EFFECTIVE_REGISTRY}")
+fi
+
+# Try to unpublish first (ignore errors)
+env "${NPM_CONFIG_OVERRIDES[@]}" npm unpublish --force --registry "${EFFECTIVE_REGISTRY}" >/dev/null 2>&1 || true
+env "${NPM_CONFIG_OVERRIDES[@]}" npm publish --registry "${EFFECTIVE_REGISTRY}" --fetch-retries=1 --fetch-timeout=10000 --fetch-retry-mintimeout=1000 --fetch-retry-maxtimeout=5000
+
+# Save source hash to mark successful build
+mkdir -p "${CACHE_DIR}"
+PACKAGE_JSON="${LIB_ABS_PATH}/package.json"
+TSCONFIG_PATH="${LIB_ABS_PATH}/.autogenerated/tsconfig.autogenerated.json"
+if [ -f "${TSCONFIG_PATH}" ]; then
+  find "${LIB_ABS_PATH}/src" "${PACKAGE_JSON}" "${TSCONFIG_PATH}" -type f 2>/dev/null | \
+    sort | \
+    xargs cat 2>/dev/null | \
+    shasum -a 256 | \
+    awk '{print $1}' > "${CACHE_DIR}/source-hash.txt"
+else
+  find "${LIB_ABS_PATH}/src" "${PACKAGE_JSON}" "${LIB_ABS_PATH}/tsconfig.json" -type f 2>/dev/null | \
+    sort | \
+    xargs cat 2>/dev/null | \
+    shasum -a 256 | \
+    awk '{print $1}' > "${CACHE_DIR}/source-hash.txt"
+fi
+
+# Link to consumers if specified
+if [[ -n "${CONSUMER_PATHS}" ]]; then
+  IFS=',' read -ra CONSUMERS <<< "${CONSUMER_PATHS}"
+  for consumer in "${CONSUMERS[@]}"; do
+    if [[ -n "${consumer}" ]]; then
+      echo "🔗 Linking to consumer: ${consumer}"
+      (cd "${WORKSPACE_ROOT}/${consumer}" && bun link "${PACKAGE_NAME}") || true
+    fi
+  done
+fi
+
+echo "✅ ${PACKAGE_NAME} build and publish complete"

package/engine/scripts/check-lib-publish.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+# =============================================================================
+# Library Build/Publish Cache Checker
+# =============================================================================
+# Checks if a library needs to be rebuilt and republished to Verdaccio.
+# The SOURCE HASH is the primary gate — if sources haven't changed since the
+# last successful build+publish, skip entirely (regardless of registry state).
+# Returns: 0 if rebuild needed, 1 if can skip
+# =============================================================================
+
+set -euo pipefail
+
+LIB_PATH="${1:?Library path required}"
+REGISTRY="${2:-http://localhost:4873}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+if [[ "${LIB_PATH}" = /* ]]; then
+  LIB_ABS_PATH="${LIB_PATH}"
+else
+  LIB_ABS_PATH="${WORKSPACE_ROOT}/${LIB_PATH}"
+fi
+
+CACHE_DIR="${LIB_ABS_PATH}/.tilt-cache"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Ensure cache directory exists
+mkdir -p "${CACHE_DIR}"
+
+# Read package.json to get name and version
+PACKAGE_JSON="${LIB_ABS_PATH}/package.json"
+if [[ ! -f "${PACKAGE_JSON}" ]]; then
+  echo -e "${YELLOW}⚠️  package.json not found at ${PACKAGE_JSON}${NC}"
+  exit 0  # Needs rebuild
+fi
+
+PACKAGE_NAME=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "${PACKAGE_JSON}" | sed 's/"name"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/')
+PACKAGE_VERSION=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "${PACKAGE_JSON}" | sed 's/"version"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/')
+
+# ---------------------------------------------------------------------------
+# PRIMARY CHECK: Source hash comparison (works offline, no registry needed)
+# ---------------------------------------------------------------------------
+SOURCE_HASH_FILE="${CACHE_DIR}/source-hash.txt"
+
+# Calculate hash of source files (src/, package.json, tsconfig.json)
+TSCONFIG_PATH="${LIB_ABS_PATH}/.autogenerated/tsconfig.autogenerated.json"
+if [ -f "${TSCONFIG_PATH}" ]; then
+  CURRENT_HASH=$(find "${LIB_ABS_PATH}/src" "${PACKAGE_JSON}" "${TSCONFIG_PATH}" -type f 2>/dev/null | \
+    sort | \
+    xargs cat 2>/dev/null | \
+    shasum -a 256 | \
+    awk '{print $1}')
+else
+  CURRENT_HASH=$(find "${LIB_ABS_PATH}/src" "${PACKAGE_JSON}" "${LIB_ABS_PATH}/tsconfig.json" -type f 2>/dev/null | \
+    sort | \
+    xargs cat 2>/dev/null | \
+    shasum -a 256 | \
+    awk '{print $1}')
+fi
+
+if [[ -f "${SOURCE_HASH_FILE}" ]]; then
+  CACHED_HASH=$(cat "${SOURCE_HASH_FILE}")
+
+  if [[ "${CURRENT_HASH}" == "${CACHED_HASH}" ]]; then
+    # Source unchanged since last successful build+publish — skip
+    echo -e "${GREEN}✓ ${PACKAGE_NAME}@${PACKAGE_VERSION} sources unchanged (hash match) - skipping build${NC}"
+    exit 1  # Skip rebuild
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Hash mismatch or no cached hash — rebuild needed
+# ---------------------------------------------------------------------------
+if [[ -f "${SOURCE_HASH_FILE}" ]]; then
+  echo -e "${YELLOW}⚠️  ${PACKAGE_NAME}@${PACKAGE_VERSION} sources changed — rebuilding${NC}"
+else
+  echo -e "${YELLOW}⚠️  ${PACKAGE_NAME}@${PACKAGE_VERSION} no cached hash found — initial build${NC}"
+fi
+
+echo "🔨 Building ${PACKAGE_NAME}@${PACKAGE_VERSION}..."
+exit 0  # Needs rebuild

package/engine/scripts/debug-container.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Flisk contributors
+# SPDX-License-Identifier: MIT
+# ====================================================================
+# Container Debug Helper Script
+# Provides easy access to debugging running or failed Docker containers
+# ====================================================================
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Container name filter: project name from .tdk/project.json (override with TDK_PROJECT_NAME)
+PROJECT_FILTER="${TDK_PROJECT_NAME:-$(sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' .tdk/project.json 2>/dev/null | head -1)}"
+PROJECT_FILTER="${PROJECT_FILTER:-tdk-project}"
+PROJECT_FILTER="${PROJECT_FILTER//-/[-_]}"
+
+# Help text
+show_help() {
+    cat << EOF
+${GREEN}Container Debug Helper${NC}
+
+${BLUE}Usage:${NC}
+  $0 [OPTIONS] [RESOURCE_NAME]
+
+${BLUE}Options:${NC}
+  -l, --list              List all running containers with their status
+  -s, --shell SERVICE     Start an interactive shell in SERVICE
+  -f, --failed            Show failed build containers
+  -c, --command CMD       Run a specific command in the container
+  -v, --verbose           Show verbose output
+  -h, --help              Show this help message
+
+${BLUE}Examples:${NC}
+  # List all running containers
+  $0 --list
+
+  # Open shell in identity service
+  $0 --shell identity-db-migrator
+
+  # Run a diagnostic command
+  $0 -s identity-db-migrator -c "bun install --verbose"
+
+  # Check network connectivity
+  $0 -s identity-db-migrator -c "nc -zv registry.npmjs.org 443"
+
+  # View package.json
+  $0 -s identity-db-migrator -c "cat package.json"
+
+${BLUE}Common Debug Commands:${NC}
+  # Network diagnostics
+  nc -zv registry.npmjs.org 443
+  nslookup registry.npmjs.org
+  curl -I https://registry.npmjs.org
+
+  # Bun diagnostics
+  bun --version
+  bun install --verbose --dry-run
+  cat .npmrc
+  cat bunfig.toml
+
+  # File system
+  ls -la node_modules
+  du -sh node_modules
+  df -h
+
+EOF
+}
+
+# List containers
+list_containers() {
+    echo -e "${GREEN}=== Running Containers ===${NC}"
+    docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER"
+    
+    echo ""
+    echo -e "${YELLOW}=== Recently Exited Containers ===${NC}"
+    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER" | grep -i "exited"
+}
+
+# Get container ID from service name
+get_container_id() {
+    local resource_name="$1"
+    local container_id=$(docker ps -aq --filter "name=${resource_name}" | head -n1)
+    
+    if [ -z "$container_id" ]; then
+        echo -e "${RED}Error: No container found for service '${resource_name}'${NC}" >&2
+        echo -e "${YELLOW}Tip: Run '$0 --list' to see available containers${NC}" >&2
+        return 1
+    fi
+    
+    echo "$container_id"
+}
+
+# Start interactive shell
+start_shell() {
+    local resource_name="$1"
+    local container_id=$(get_container_id "$resource_name") || return 1
+    
+    echo -e "${GREEN}Starting interactive shell in ${resource_name}...${NC}"
+    echo -e "${BLUE}Container ID: ${container_id}${NC}"
+    echo ""
+    
+    # Try sh first (alpine), then bash
+    if docker exec -it "$container_id" sh -c "command -v bash" >/dev/null 2>&1; then
+        docker exec -it "$container_id" bash
+    else
+        docker exec -it "$container_id" sh
+    fi
+}
+
+# Run specific command
+run_command() {
+    local resource_name="$1"
+    local command="$2"
+    local container_id=$(get_container_id "$resource_name") || return 1
+    
+    echo -e "${GREEN}Running command in ${resource_name}:${NC} ${command}"
+    echo -e "${BLUE}Container ID: ${container_id}${NC}"
+    echo ""
+    
+    docker exec -it "$container_id" sh -c "$command"
+}
+
+# Show failed containers
+show_failed() {
+    echo -e "${RED}=== Failed/Exited Containers ===${NC}"
+    docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep -iE "$PROJECT_FILTER" | grep -iE "(exited|error)"
+    
+    echo ""
+    echo -e "${YELLOW}To inspect logs of a failed container:${NC}"
+    echo "  docker logs <container_name>"
+    echo ""
+    echo -e "${YELLOW}To restart a failed container:${NC}"
+    echo "  docker start -ai <container_name>"
+}
+
+# Quick diagnostics menu
+diagnostics_menu() {
+    local resource_name="$1"
+    
+    echo -e "${GREEN}=== Quick Diagnostics Menu ===${NC}"
+    echo "1) Check network connectivity"
+    echo "2) View package.json and config files"
+    echo "3) Test bun installation (dry-run)"
+    echo "4) Check disk space and cache"
+    echo "5) View environment variables"
+    echo "6) Interactive shell"
+    echo "q) Quit"
+    echo ""
+    read -p "Select option: " choice
+    
+    case $choice in
+        1)
+            echo -e "${BLUE}Testing network connectivity...${NC}"
+            run_command "$resource_name" "nc -zv registry.npmjs.org 443 && nc -zv Flisk-verdaccio 4873"
+            ;;
+        2)
+            echo -e "${BLUE}Viewing configuration files...${NC}"
+            run_command "$resource_name" "echo '=== package.json ===' && cat package.json && echo '' && echo '=== .npmrc ===' && cat .npmrc && echo '' && echo '=== bunfig.toml ===' && cat bunfig.toml"
+            ;;
+        3)
+            echo -e "${BLUE}Testing bun installation (dry-run)...${NC}"
+            run_command "$resource_name" "bun install --verbose --dry-run"
+            ;;
+        4)
+            echo -e "${BLUE}Checking disk space and cache...${NC}"
+            run_command "$resource_name" "df -h && echo '' && echo '=== Cache ===' && ls -lh /cache/bun && echo '' && echo '=== node_modules ===' && ls -lh node_modules | head -20"
+            ;;
+        5)
+            echo -e "${BLUE}Environment variables:${NC}"
+            run_command "$resource_name" "env | sort"
+            ;;
+        6)
+            start_shell "$resource_name"
+            ;;
+        q|Q)
+            exit 0
+            ;;
+        *)
+            echo -e "${RED}Invalid option${NC}"
+            ;;
+    esac
+}
+
+# Main script logic
+main() {
+    local action=""
+    local resource_name=""
+    local command=""
+    local verbose=false
+    
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            -l|--list)
+                action="list"
+                shift
+                ;;
+            -s|--shell)
+                action="shell"
+                resource_name="$2"
+                shift 2
+                ;;
+            -f|--failed)
+                action="failed"
+                shift
+                ;;
+            -c|--command)
+                command="$2"
+                shift 2
+                ;;
+            -v|--verbose)
+                verbose=true
+                shift
+                ;;
+            -h|--help)
+                show_help
+                exit 0
+                ;;
+            *)
+                if [ -z "$resource_name" ]; then
+                    resource_name="$1"
+                    action="menu"
+                fi
+                shift
+                ;;
+        esac
+    done
+    
+    # Execute action
+    case $action in
+        list)
+            list_containers
+            ;;
+        shell)
+            if [ -n "$command" ]; then
+                run_command "$resource_name" "$command"
+            else
+                start_shell "$resource_name"
+            fi
+            ;;
+        failed)
+            show_failed
+            ;;
+        menu)
+            diagnostics_menu "$resource_name"
+            ;;
+        "")
+            echo -e "${YELLOW}No action specified. Use --help for usage information.${NC}"
+            list_containers
+            ;;
+        *)
+            echo -e "${RED}Unknown action: $action${NC}"
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"