walheim 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b943785b380c1a8fcd220c0f9c4716a6e9fe5d255b31e7b874115f0b0c8734a
-  data.tar.gz: a5d62f283a0da1189b07129512a0f7698b3c4811f653f5735576139fa76c4f0f
+  metadata.gz: c859436cfcc9582a4a875cf547855472d592b37e391f58abadd0003943272d1d
+  data.tar.gz: 15b5ad58f1c94475882e31c41c203f6a8446a63629ed7543957fc3244282be2b
 SHA512:
-  metadata.gz: 3b01e7611db7c3f589c3c0043ed8762f1fac6768c884f177c045a188ff16440b0f5ac4184b31ad681febdf2b79d7db247856c191fd9bb074cdfe4884bc4521aa
-  data.tar.gz: 5374cfd930d9ddb54117209f2ac9eefa1436dbc293db46d2ef8f1307dd91b6bba72b82ce918ef8511569720d9992662fa59c0103e2bdf0bc0544db021a72f71d
+  metadata.gz: b4c2b0a0ff5d4e6ca42d2ac2159c85689fc7faca2f633061d11b8d3cb8a2cf3bf2d4e9d07c35ca6d2abfb9768fbdcaacd49a0ccb673ba0b0cab55da3ec80c5ba
+  data.tar.gz: 2c1c9369e7372cf6c21d1771870e805e43f10a8a082dc886d4a18e6f7ad70bd272e50bb3463c6cafeb8a37acf5a351b0d7efe5ba12b070c6ae45092d92e4d375

data/README.md

@@ -1,5 +1,7 @@
 # Walheim
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/walheimlab/walheim-rb)
+
 A kubectl-style CLI for managing Docker-based homelab infrastructure across multiple machines.
 
 ## Overview

data/lib/walheim/cli/base_command.rb

@@ -16,22 +16,30 @@ module Walheim
       end
 
       # 2. Check operation support
+      handler_class = handler_info[:handler]
       unless Walheim::HandlerRegistry.supports_operation?(kind, operation)
         warn "Error: #{operation} not supported for #{kind}"
         exit 1
       end
 
-      # 3. Resolve data directory from context
+      # 3. Get operation metadata
+      op_metadata = handler_class.operation_info[operation]
+      unless op_metadata
+        warn "Error: operation metadata missing for #{operation}"
+        exit 1
+      end
+
+      # 4. Resolve data directory from context
       data_dir = resolve_data_dir(options, parent_options)
 
-      # 4. Initialize handler
-      handler = handler_info[:handler].new(data_dir: data_dir)
+      # 5. Initialize handler
+      handler = handler_class.new(data_dir: data_dir)
 
-      # 5. Validate namespace requirements
-      validate_namespace_options!(operation, kind, name, options) if handler.is_a?(Walheim::NamespacedResource)
+      # 6. Validate namespace requirements
+      validate_namespace_requirements!(operation, kind, name, options, op_metadata) if handler.is_a?(Walheim::NamespacedResource)
 
-      # 6. Dispatch to handler
-      dispatch_to_handler(handler, operation, name, options, handler_info)
+      # 7. Dispatch to handler using metadata
+      dispatch_operation(handler, operation, name, options, handler_info, op_metadata)
     end
 
     def self.resolve_data_dir(options, parent_options)
@@ -70,101 +78,97 @@ module Walheim
       end
     end
 
-    def self.validate_namespace_options!(operation, kind, _name, options)
-      # Operations that require namespace or --all
-      requires_namespace = %i[get apply delete start pause stop logs import]
-      return unless requires_namespace.include?(operation)
+    def self.validate_namespace_requirements!(operation, kind, _name, options, op_metadata)
+      dispatch_meta = op_metadata[:dispatch] || {}
+      namespace_handling = dispatch_meta[:namespace_handling]
 
-      # get can use --all
-      if operation == :get
+      case namespace_handling
+      when :optional_with_all
+        # Operations like get can use --all or -n
         return if options[:all] || options[:namespace]
 
         warn "Error: either -n {namespace} or --all/-A flag is required"
-        warn "Usage: whctl get #{kind} -n {namespace}"
-        warn "Usage: whctl get #{kind} --all"
+        warn "Usage: whctl #{operation} #{kind} -n {namespace}"
+        warn "Usage: whctl #{operation} #{kind} --all"
         exit 1
-      end
-
-      # Other operations require namespace
-      return if options[:namespace]
+      when :required
+        # Operations require namespace
+        return if options[:namespace]
 
-      warn "Error: -n {namespace} is required"
-      warn "Usage: whctl #{operation} #{kind} {name} -n {namespace}"
-      exit 1
-    end
-
-    def self.dispatch_to_handler(handler, operation, name, options, handler_info)
-      case operation
-      when :get
-        dispatch_get(handler, name, options, handler_info)
-      when :apply
-        dispatch_apply(handler, name, options, handler_info)
-      when :delete
-        handler.delete(namespace: options[:namespace], name: name)
-      when :create
-        # Special case: create namespace
-        handler.create(name: name, username: options[:username], hostname: options[:hostname])
-      when :import
-        # Special case: import app
-        compose_manifest = Walheim::Helpers.read_yaml_input(options[:file])
-        handler.import(namespace: options[:namespace], name: name, compose_manifest: compose_manifest)
-      when :start, :pause, :stop
-        handler.send(operation, namespace: options[:namespace], name: name)
-      when :logs
-        log_opts = {}
-        log_opts[:follow] = options[:follow] if options[:follow]
-        log_opts[:tail] = options[:tail] if options[:tail]
-        log_opts[:timestamps] = options[:timestamps] if options[:timestamps]
-        handler.logs(namespace: options[:namespace], name: name, **log_opts)
+        warn "Error: -n {namespace} is required"
+        warn "Usage: whctl #{operation} #{kind} {name} -n {namespace}"
+        exit 1
+      when nil
+        # No namespace validation needed
+        nil
       else
-        warn "Error: operation #{operation} not implemented"
+        warn "Error: unknown namespace_handling: #{namespace_handling}"
         exit 1
       end
     end
 
-    def self.dispatch_get(handler, name, options, handler_info)
-      if handler.is_a?(Walheim::ClusterResource)
-        result = handler.get(name: name)
-        Walheim::Helpers.print_cluster_resources_table(result, handler_info[:name])
-      else
-        result = if options[:all]
-                   handler.get(namespace: nil, name: nil)
+    def self.dispatch_operation(handler, operation, name, options, handler_info, op_metadata)
+      dispatch_meta = op_metadata[:dispatch] || {}
+      method_name = dispatch_meta[:method] || operation
+
+      # Build method parameters
+      params = build_method_params(name, options, dispatch_meta)
+
+      # Call handler method
+      result = handler.send(method_name, **params)
+
+      # Handle output formatting
+      handle_output(result, handler, handler_info, options, dispatch_meta)
+    end
+
+    def self.build_method_params(name, options, dispatch_meta)
+      params = {}
+
+      # Add positional params (like :name)
+      positional_params = dispatch_meta[:params] || []
+      positional_params.each do |param_name|
+        case param_name
+        when :name
+          params[:name] = name
         else
-                   handler.get(namespace: options[:namespace], name: name)
+          params[param_name] = options[param_name]
         end
-        Walheim::Helpers.print_resources_table(result, options[:all], handler_info[:name])
       end
-    end
 
-    def self.dispatch_apply(handler, name, options, _handler_info)
-      # Extract from manifest if -f provided
-      if options[:file]
-        manifest_data = Walheim::Helpers.read_yaml_input(options[:file])
+      # Add named params from options
+      named_params = dispatch_meta[:named_params] || {}
+      named_params.each do |param_name, option_key|
+        option_value = options[option_key]
 
-        if handler.is_a?(Walheim::NamespacedResource)
-          namespace = manifest_data["metadata"]["namespace"]
-          name = manifest_data["metadata"]["name"]
+        # Handle file readers
+        if dispatch_meta[:file_reader] == param_name && option_value
+          option_value = Walheim::Helpers.read_yaml_input(option_value)
+        end
 
-          unless namespace && name
-            warn "Error: Manifest must contain metadata.namespace and metadata.name"
-            exit 1
-          end
+        # Always include declared parameters (handlers expect them as keyword args)
+        params[param_name] = option_value
+      end
+
+      params
+    end
 
-          handler.apply(namespace: namespace, name: name, manifest_source: options[:file])
+    def self.handle_output(result, handler, handler_info, options, dispatch_meta)
+      output_type = dispatch_meta[:output]
+
+      case output_type
+      when :table
+        # Table output for get operations
+        if handler.is_a?(Walheim::ClusterResource)
+          Walheim::Helpers.print_cluster_resources_table(result, handler_info[:name])
         else
-          # Cluster resource
-          name = manifest_data["metadata"]["name"]
-          unless name
-            warn "Error: Manifest must contain metadata.name"
-            exit 1
-          end
-          handler.apply(name: name, manifest_source: options[:file])
+          Walheim::Helpers.print_resources_table(result, options[:all], handler_info[:name])
         end
-      elsif handler.is_a?(Walheim::NamespacedResource)
-        # Apply from existing manifest in data dir
-        handler.apply(namespace: options[:namespace], name: name)
+      when nil
+        # No output handling needed (handler prints directly)
+        nil
       else
-        handler.apply(name: name)
+        warn "Error: unknown output type: #{output_type}"
+        exit 1
       end
     end
   end

data/lib/walheim/cli.rb

@@ -7,6 +7,11 @@ require_relative "cli/resource_command"
 
 module Walheim
   class CLI < Thor
+    # Exit with non-zero status on errors
+    def self.exit_on_failure?
+      true
+    end
+
     # Global flags
     class_option :context,
                  type: :string,
@@ -34,6 +39,45 @@ module Walheim
       puts "whctl version #{Walheim::VERSION}"
     end
 
+    # Exec command - custom implementation to support variadic arguments
+    desc "exec app NAME [--] COMMAND...", "Execute command in app container"
+    method_option :namespace,
+                  type: :string,
+                  aliases: [ :n ],
+                  desc: "Target namespace",
+                  required: true
+    method_option :service,
+                  type: :string,
+                  aliases: [ :s ],
+                  desc: "Target service (defaults to first)"
+    method_option :interactive,
+                  type: :boolean,
+                  aliases: [ :it ],
+                  desc: "Allocate pseudo-TTY and keep stdin open",
+                  default: false
+    def exec(kind, name, *command)
+      # Validate kind is 'app' or 'apps'
+      unless %w[app apps].include?(kind.downcase)
+        warn "Error: exec only supports 'app' kind, got '#{kind}'"
+        exit 1
+      end
+
+      # Resolve data directory from context
+      data_dir = BaseCommand.send(:resolve_data_dir, options, self.class.class_options.transform_keys(&:to_sym).transform_values { |v| options[v.name] rescue nil })
+
+      # Initialize Apps handler
+      handler = Resources::Apps.new(data_dir: data_dir)
+
+      # Call exec_command method
+      handler.exec_command(
+        namespace: options[:namespace],
+        name: name,
+        service: options[:service],
+        interactive: options[:interactive],
+        command: command
+      )
+    end
+
     # Override help to maintain kubectl-style help
     def self.help(shell, subcommand = false)
       list = printable_commands(true, subcommand)

data/lib/walheim/namespaced_resource.rb

@@ -7,7 +7,7 @@ module Walheim
   # Examples: Apps, Secrets, ConfigMaps
   # These resources live under namespaces/{namespace}/{kind}/{name}/
   class NamespacedResource < Resource
-    # Override operation_info to add namespace flags
+    # Override operation_info to add namespace flags and dispatch params
     def self.operation_info
       ops = super
 
@@ -31,6 +31,17 @@ module Walheim
       ops[:apply][:options].merge!(namespace: namespace_options[:namespace])
       ops[:delete][:options].merge!(namespace: namespace_options[:namespace])
 
+      # Add namespace parameter to dispatch
+      ops[:get][:dispatch][:named_params] = { namespace: :namespace }
+      ops[:get][:dispatch][:namespace_handling] = :optional_with_all
+
+      ops[:apply][:dispatch][:named_params] ||= {}
+      ops[:apply][:dispatch][:named_params][:namespace] = :namespace
+      ops[:apply][:dispatch][:namespace_handling] = :required
+
+      ops[:delete][:dispatch][:named_params] = { namespace: :namespace }
+      ops[:delete][:dispatch][:namespace_handling] = :required
+
       ops
     end
 

data/lib/walheim/resource.rb

@@ -35,7 +35,7 @@ module Walheim
       {} # Default: no summary fields
     end
 
-    # Operation metadata - defines how operations appear in help
+    # Operation metadata - defines how operations appear in help and how they're dispatched
     # Subclasses can override to add custom operations
     def self.operation_info
       {
@@ -46,19 +46,35 @@ module Walheim
             "get #{kind_info[:plural]} --all/-A",
             "get #{kind_info[:singular]} {name} -n {namespace}"
           ],
-          options: {}  # Subclasses will override
+          options: {},  # Subclasses will override
+          dispatch: {
+            method: :get,
+            params: [ :name ],
+            output: :table
+          }
         },
         apply: {
           description: "Create or update a resource",
           usage: [ "apply #{kind_info[:singular]} {name} -n {namespace}" ],
           options: {
             file: { type: :string, aliases: [ :f ], desc: "Manifest file (use - for stdin)" }
+          },
+          dispatch: {
+            method: :apply,
+            params: [ :name ],
+            named_params: {
+              manifest_source: :file
+            }
           }
         },
         delete: {
           description: "Delete a resource",
           usage: [ "delete #{kind_info[:singular]} {name} -n {namespace}" ],
-          options: {}  # Subclasses will override
+          options: {},  # Subclasses will override
+          dispatch: {
+            method: :delete,
+            params: [ :name ]
+          }
         }
       }
     end

data/lib/walheim/resources/apps.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "shellwords"
+require "parallel"
 require_relative "../namespaced_resource"
 require_relative "../sync"
 require_relative "../handler_registry"
@@ -35,8 +37,14 @@ module Resources
           # Extract first service's image from compose spec
           manifest.dig("spec", "compose", "services")&.values&.first&.dig("image") || "N/A"
         },
-        status: lambda { |_manifest|
-          # Could check if app is running, for now just show 'Configured'
+        ready: lambda { |manifest|
+          # Actual ready count is fetched and cached by get() method
+          # This lambda is a placeholder
+          "-"
+        },
+        status: lambda { |manifest|
+          # Actual status is fetched and cached by get() method
+          # This lambda reads from the cache
           "Configured"
         }
       }
@@ -46,7 +54,7 @@ module Resources
       # Start with base operations
       ops = super
 
-      namespace_opt = { type: :string, aliases: [ :n ], desc: "Target namespace", required: true }
+      namespace_opt = { type: :string, aliases: [ :n ], desc: "Target namespace" }
 
       # Add apps-specific operations
       ops.merge({
@@ -56,22 +64,50 @@ module Resources
                     options: {
                       namespace: namespace_opt,
                       file: { type: :string, aliases: [ :f ], desc: "docker-compose.yml path", required: true }
+                    },
+                    dispatch: {
+                      method: :import,
+                      params: [ :name ],
+                      named_params: {
+                        namespace: :namespace,
+                        compose_manifest: :file
+                      },
+                      namespace_handling: :required,
+                      file_reader: :compose_manifest # Read YAML from file option
                     }
                   },
                   start: {
                     description: "Compile, sync, and start app on host",
                     usage: [ "start app {name} -n {namespace}" ],
-                    options: { namespace: namespace_opt }
+                    options: { namespace: namespace_opt },
+                    dispatch: {
+                      method: :start,
+                      params: [ :name ],
+                      named_params: { namespace: :namespace },
+                      namespace_handling: :required
+                    }
                   },
                   pause: {
                     description: "Stop app containers (keep files)",
                     usage: [ "pause app {name} -n {namespace}" ],
-                    options: { namespace: namespace_opt }
+                    options: { namespace: namespace_opt },
+                    dispatch: {
+                      method: :pause,
+                      params: [ :name ],
+                      named_params: { namespace: :namespace },
+                      namespace_handling: :required
+                    }
                   },
                   stop: {
                     description: "Stop app and remove files from host",
                     usage: [ "stop app {name} -n {namespace}" ],
-                    options: { namespace: namespace_opt }
+                    options: { namespace: namespace_opt },
+                    dispatch: {
+                      method: :stop,
+                      params: [ :name ],
+                      named_params: { namespace: :namespace },
+                      namespace_handling: :required
+                    }
                   },
                   logs: {
                     description: "View logs from remote containers",
@@ -86,6 +122,39 @@ module Resources
                       follow: { type: :boolean, desc: "Follow log output" },
                       tail: { type: :numeric, desc: "Number of lines from end" },
                       timestamps: { type: :boolean, desc: "Show timestamps" }
+                    },
+                    dispatch: {
+                      method: :logs,
+                      params: [ :name ],
+                      named_params: {
+                        namespace: :namespace,
+                        follow: :follow,
+                        tail: :tail,
+                        timestamps: :timestamps
+                      },
+                      namespace_handling: :required
+                    }
+                  },
+                  pull: {
+                    description: "Pull latest images without restarting",
+                    usage: [ "pull app {name} -n {namespace}" ],
+                    options: { namespace: namespace_opt },
+                    dispatch: {
+                      method: :pull,
+                      params: [ :name ],
+                      named_params: { namespace: :namespace },
+                      namespace_handling: :required
+                    }
+                  },
+                  describe: {
+                    description: "Show running status of app containers",
+                    usage: [ "describe app {name} -n {namespace}" ],
+                    options: { namespace: namespace_opt },
+                    dispatch: {
+                      method: :describe,
+                      params: [ :name ],
+                      named_params: { namespace: :namespace },
+                      namespace_handling: :required
                     }
                   }
                 })
@@ -233,6 +302,307 @@ module Resources
       exec(ssh_command)
     end
 
+    def pull(namespace:, name:)
+      # Get namespace config
+      namespace_config = load_namespace_config(namespace)
+      username = namespace_config["username"]
+      hostname = namespace_config["hostname"]
+
+      remote_host = username ? "#{username}@#{hostname}" : hostname
+      remote_dir = "/data/walheim/apps/#{name}"
+
+      # Check if remote directory exists
+      check_command = "ssh #{remote_host} 'test -d #{remote_dir}'"
+      dir_exists = system(check_command)
+
+      unless dir_exists
+        warn "Error: app '#{name}' not found on #{remote_host}"
+        warn "Deploy the app first using 'whctl apply app #{name} -n #{namespace}'"
+        exit 1
+      end
+
+      # Pull latest images
+      puts "Pulling latest images for '#{name}' on #{remote_host}"
+      ssh_command = "ssh #{remote_host} 'cd #{remote_dir} && docker compose pull'"
+      result = system(ssh_command)
+
+      unless result
+        warn "Error: docker compose pull failed"
+        exit 1
+      end
+
+      puts "Successfully pulled latest images for app '#{name}' in namespace '#{namespace}'"
+      puts "Use 'whctl start app #{name} -n #{namespace}' to apply the pulled images"
+    end
+
+    def describe(namespace:, name:)
+      # Get namespace config
+      namespace_config = load_namespace_config(namespace)
+      username = namespace_config["username"]
+      hostname = namespace_config["hostname"]
+
+      remote_host = username ? "#{username}@#{hostname}" : hostname
+      remote_dir = "/data/walheim/apps/#{name}"
+
+      # Check if remote directory exists
+      check_command = "ssh #{remote_host} 'test -d #{remote_dir}'"
+      dir_exists = system(check_command)
+
+      unless dir_exists
+        warn "Error: app '#{name}' not found on #{remote_host}"
+        warn "Deploy the app first using 'whctl apply app #{name} -n #{namespace}'"
+        exit 1
+      end
+
+      # Display container status using docker compose ps
+      puts "Status of '#{name}' on #{remote_host}:\n\n"
+
+      # Get container status
+      ps_command = "ssh #{remote_host} 'cd #{remote_dir} && docker compose ps'"
+      system(ps_command)
+
+      puts "\n"
+
+      # Get resource usage for running containers
+      stats_command = "ssh #{remote_host} 'cd #{remote_dir} && docker compose ps -q | xargs -r docker stats --no-stream --format \"table {{.Name}}\\t{{.CPUPerc}}\\t{{.MemUsage}}\\t{{.NetIO}}\\t{{.BlockIO}}\"'"
+
+      puts "Resource Usage:"
+      stats_result = system(stats_command)
+
+      unless stats_result
+        puts "(No running containers or unable to fetch stats)"
+      end
+    end
+
+    def exec_command(namespace:, name:, service: nil, interactive: false, command:)
+      # Get namespace config
+      namespace_config = load_namespace_config(namespace)
+      username = namespace_config["username"]
+      hostname = namespace_config["hostname"]
+
+      remote_host = username ? "#{username}@#{hostname}" : hostname
+      remote_dir = "/data/walheim/apps/#{name}"
+
+      # Check if remote directory exists
+      check_command = "ssh #{remote_host} 'test -d #{remote_dir}'"
+      dir_exists = system(check_command)
+
+      unless dir_exists
+        warn "Error: app '#{name}' not found on #{remote_host}"
+        warn "Deploy the app first using 'whctl apply app #{name} -n #{namespace}'"
+        exit 1
+      end
+
+      # Validate command
+      if command.nil? || command.empty?
+        warn "Error: command is required"
+        warn "Usage: whctl exec app {name} -n {namespace} [--] {command} [args...]"
+        exit 1
+      end
+
+      # Determine service name
+      service_name = service
+      unless service_name
+        # Get first service from docker-compose.yml
+        app_manifest = load_app_manifest(namespace, name)
+        services = app_manifest[:compose]["services"]
+
+        if services.nil? || services.empty?
+          warn "Error: no services found in app '#{name}'"
+          exit 1
+        end
+
+        service_name = services.keys.first
+        puts "Defaulting to service: #{service_name}"
+      end
+
+      # Build docker compose exec command
+      # command is an array, so join with spaces and properly escape
+      command_str = Shellwords.join(command)
+      exec_cmd = "docker compose exec"
+      exec_cmd += " -T" unless interactive  # Disable pseudo-TTY allocation when not interactive
+      exec_cmd += " -it" if interactive
+      exec_cmd += " #{Shellwords.escape(service_name)} #{command_str}"
+
+      # Build SSH command
+      # Use -t flag for SSH when interactive mode is requested
+      ssh_flags = interactive ? "-t" : ""
+      ssh_command = "ssh #{ssh_flags} #{remote_host} 'cd #{remote_dir} && #{exec_cmd}'"
+
+      # Use exec to replace current process for proper signal handling
+      Kernel.exec(ssh_command)
+    end
+
+    # Override get to pre-fetch container status
+    def get(namespace:, name: nil)
+      # Determine which namespaces to fetch status for
+      namespaces_to_fetch = if namespace.nil?
+                              # Fetching all namespaces
+                              all_namespace_names
+      elsif name.nil?
+                              # Fetching single namespace
+                              [ namespace ]
+      else
+                              # Fetching single resource
+                              [ namespace ]
+      end
+
+      # Pre-fetch container status for relevant namespaces
+      fetch_container_status_batch(namespaces_to_fetch)
+
+      # Call parent get implementation
+      super
+    end
+
+    private
+
+    def all_namespace_names
+      namespaces_dir = File.join(@data_dir, "namespaces")
+      return [] unless Dir.exist?(namespaces_dir)
+
+      Dir.entries(namespaces_dir)
+         .select { |entry| File.directory?(File.join(namespaces_dir, entry)) && !entry.start_with?(".") }
+         .select { |entry| File.exist?(File.join(namespaces_dir, entry, ".namespace.yaml")) }
+         .sort
+    end
+
+    def fetch_container_status_batch(namespaces)
+      # Initialize cache if not exists
+      @container_status_cache ||= {}
+
+      # Group namespaces by hostname to batch SSH calls
+      namespace_by_host = {}
+
+      namespaces.each do |ns|
+        begin
+          config = load_namespace_config(ns)
+          hostname = config["hostname"]
+          username = config["username"]
+          host_key = username ? "#{username}@#{hostname}" : hostname
+
+          namespace_by_host[host_key] ||= { namespaces: [], config: config }
+          namespace_by_host[host_key][:namespaces] << ns
+        rescue StandardError
+          # Skip if namespace config not found
+          next
+        end
+      end
+
+      # Fetch status from each unique host in parallel
+      # Use Parallel.map to parallelize SSH calls across hosts
+      results = Parallel.map(namespace_by_host, in_threads: namespace_by_host.size) do |host_key, data|
+        fetch_status_from_host(host_key, data[:namespaces])
+      end
+
+      # Merge results into cache
+      results.each do |result|
+        @container_status_cache.merge!(result) if result
+      end
+    end
+
+    def fetch_status_from_host(remote_host, namespaces)
+      # Query all walheim-managed containers on this host
+      # Use docker ps with labels to get all containers in one call
+      # Use double quotes and escape for proper SSH transmission
+      docker_cmd = 'docker ps -a --filter label=walheim.managed=true --format "{{.Label \\"walheim.namespace\\"}}|{{.Label \\"walheim.app\\"}}|{{.State}}|{{.Status}}"'
+
+      ssh_command = "ssh #{remote_host} #{Shellwords.escape(docker_cmd)} 2>/dev/null"
+
+      output = `#{ssh_command}`
+
+      # Build result hash to return (thread-safe)
+      result = {}
+
+      # Parse output and populate result
+      # Format: namespace|appname|state|status
+      output.each_line do |line|
+        parts = line.strip.split("|")
+        next if parts.size < 4
+
+        ns = parts[0]
+        app_name = parts[1]
+        state = parts[2]      # running, exited, paused, etc.
+        status_text = parts[3] # "Up 2 hours", "Exited (0) 5 minutes ago", etc.
+
+        # Only cache for namespaces we're querying
+        next unless namespaces.include?(ns)
+
+        cache_key = "#{ns}/#{app_name}"
+        result[cache_key] ||= { containers: [] }
+        result[cache_key][:containers] << {
+          state: state,
+          status: status_text
+        }
+      end
+
+      # Mark namespaces as queried (even if no containers found)
+      namespaces.each do |ns|
+        result["_queried_#{ns}"] = true
+      end
+
+      result
+    end
+
+    def get_container_status(namespace, app_name)
+      cache_key = "#{namespace}/#{app_name}"
+
+      # Check if we've queried this namespace
+      return "Unknown" unless @container_status_cache&.dig("_queried_#{namespace}")
+
+      # Get cached container data
+      cached_data = @container_status_cache&.dig(cache_key)
+      return "NotFound" if cached_data.nil? || cached_data[:containers].empty?
+
+      # Aggregate status from all containers
+      containers = cached_data[:containers]
+      states = containers.map { |c| c[:state] }.uniq
+
+      if states.all? { |s| s == "running" }
+        "Running"
+      elsif states.all? { |s| s == "exited" }
+        "Stopped"
+      elsif states.include?("running")
+        "Degraded"
+      elsif states.include?("paused")
+        "Paused"
+      elsif states.include?("restarting")
+        "Restarting"
+      else
+        "Unknown"
+      end
+    end
+
+    def get_container_ready(namespace, app_name)
+      cache_key = "#{namespace}/#{app_name}"
+
+      # Check if we've queried this namespace
+      return "-" unless @container_status_cache&.dig("_queried_#{namespace}")
+
+      # Get cached container data
+      cached_data = @container_status_cache&.dig(cache_key)
+      return "-" if cached_data.nil? || cached_data[:containers].empty?
+
+      # Count running vs total containers
+      containers = cached_data[:containers]
+      total = containers.size
+      running = containers.count { |c| c[:state] == "running" }
+
+      "#{running}/#{total}"
+    end
+
+    # Override get_single_resource to inject actual status and ready
+    def get_single_resource(namespace, name)
+      result = super
+
+      # Override status and ready with actual container data
+      if result[:summary]
+        result[:summary][:status] = get_container_status(namespace, name)
+        result[:summary][:ready] = get_container_ready(namespace, name)
+      end
+
+      result
+    end
+
     private
 
     def load_app_manifest(namespace, name)

data/lib/walheim/resources/namespaces.rb

@@ -28,7 +28,12 @@ module Resources
         get: {
           description: "List all namespaces",
           usage: [ "get namespaces" ],
-          options: {} # No namespace flag for cluster resource
+          options: {}, # No namespace flag for cluster resource
+          dispatch: {
+            method: :get,
+            params: [ :name ],
+            output: :table
+          }
         },
         create: {
           description: "Create a new namespace",
@@ -36,6 +41,14 @@ module Resources
           options: {
             username: { type: :string, desc: "SSH username for namespace" },
             hostname: { type: :string, desc: "Hostname for namespace" }
+          },
+          dispatch: {
+            method: :create,
+            params: [ :name ],
+            named_params: {
+              username: :username,
+              hostname: :hostname
+            }
           }
         },
         apply: {
@@ -43,12 +56,32 @@ module Resources
           usage: [ "apply namespace {name}", "apply -f namespace.yaml" ],
           options: {
             file: { type: :string, aliases: [ :f ], desc: "Manifest file" }
+          },
+          dispatch: {
+            method: :apply,
+            params: [ :name ],
+            named_params: {
+              manifest_source: :file
+            }
           }
         },
         delete: {
           description: "Delete a namespace",
           usage: [ "delete namespace {name}" ],
-          options: {}
+          options: {},
+          dispatch: {
+            method: :delete,
+            params: [ :name ]
+          }
+        },
+        describe: {
+          description: "Show detailed namespace information",
+          usage: [ "describe namespace {name}" ],
+          options: {},
+          dispatch: {
+            method: :describe,
+            params: [ :name ]
+          }
         }
       }
     end
@@ -79,8 +112,218 @@ module Resources
       puts "  Hostname: #{hostname}"
     end
 
+    # Describe a namespace with detailed information
+    def describe(name:)
+      namespace_path = File.join(@data_dir, "namespaces", name)
+      unless Dir.exist?(namespace_path)
+        warn "Error: namespace '#{name}' not found"
+        exit 1
+      end
+
+      # Load namespace config
+      config_path = File.join(namespace_path, ".namespace.yaml")
+      unless File.exist?(config_path)
+        warn "Error: namespace config not found at #{config_path}"
+        exit 1
+      end
+
+      config = YAML.load_file(config_path)
+      username = config["username"]
+      hostname = config["hostname"]
+      remote_host = username ? "#{username}@#{hostname}" : hostname
+
+      # Print metadata
+      puts "Name:           #{name}"
+      puts "Hostname:       #{hostname}"
+      puts "Username:       #{username || '(from SSH config)'}"
+      puts "SSH:            #{remote_host}"
+      puts ""
+
+      # Test SSH connectivity and Docker availability
+      puts "Status:"
+      connection_status = test_ssh_connection(remote_host)
+      puts "  Connection:   #{connection_status[:status]}"
+
+      if connection_status[:connected]
+        docker_info = get_docker_info(remote_host)
+        puts "  Docker:       #{docker_info[:status]}"
+        puts ""
+
+        # Get deployed apps with status
+        apps_info = get_deployed_apps(name, remote_host)
+        if apps_info[:apps].any?
+          puts "Deployed Apps:"
+          apps_info[:apps].each do |app|
+            status_display = format_app_status(app[:status])
+            ready_display = app[:ready] || "-"
+            puts "  %-15s %-12s %s" % [ app[:name], status_display, ready_display ]
+          end
+          puts ""
+        end
+
+        # Count resources
+        puts "Resources:"
+        apps_count = count_resources(namespace_path, "apps")
+        secrets_count = count_resources(namespace_path, "secrets")
+        configmaps_count = count_resources(namespace_path, "configmaps")
+        puts "  Apps:         #{apps_count}"
+        puts "  Secrets:      #{secrets_count}"
+        puts "  ConfigMaps:   #{configmaps_count}"
+        puts ""
+
+        # Show usage info if available
+        if docker_info[:connected]
+          usage_info = get_usage_info(remote_host)
+          if usage_info[:available]
+            puts "Usage:"
+            puts "  Disk:         #{usage_info[:disk]}" if usage_info[:disk]
+            puts "  Containers:   #{usage_info[:containers]}" if usage_info[:containers]
+          end
+        end
+      else
+        puts ""
+        puts "Unable to connect to namespace. Please check SSH configuration."
+      end
+    end
+
     private
 
+    # Test SSH connection to remote host
+    def test_ssh_connection(remote_host)
+      # Try a simple SSH command with timeout
+      test_command = "ssh -o ConnectTimeout=5 -o BatchMode=yes #{remote_host} 'echo ok' 2>/dev/null"
+      result = `#{test_command}`.strip
+
+      if result == "ok"
+        { connected: true, status: "Connected" }
+      else
+        { connected: false, status: "Failed" }
+      end
+    end
+
+    # Get Docker version and availability
+    def get_docker_info(remote_host)
+      docker_command = "ssh -o ConnectTimeout=5 #{remote_host} 'docker --version' 2>/dev/null"
+      result = `#{docker_command}`.strip
+
+      if result.include?("Docker version")
+        version = result.match(/Docker version ([\d.]+)/)[1] rescue "unknown"
+        { connected: true, status: "Available (v#{version})" }
+      else
+        { connected: false, status: "Not available" }
+      end
+    end
+
+    # Get list of deployed apps with their status
+    def get_deployed_apps(namespace, remote_host)
+      require "shellwords"
+
+      # Query all containers for this namespace
+      docker_cmd = "docker ps -a --filter label=walheim.namespace=" + namespace + ' --format "{{.Label \\"walheim.app\\"}}|{{.State}}|{{.Status}}"'
+      ssh_command = "ssh #{remote_host} #{Shellwords.escape(docker_cmd)} 2>/dev/null"
+      output = `#{ssh_command}`
+
+      # Parse container data
+      apps_data = {}
+      output.each_line do |line|
+        parts = line.strip.split("|")
+        next if parts.size < 3
+
+        app_name = parts[0]
+        state = parts[1]
+        status_text = parts[2]
+
+        apps_data[app_name] ||= { containers: [] }
+        apps_data[app_name][:containers] << { state: state, status: status_text }
+      end
+
+      # Convert to app list with aggregated status
+      apps = apps_data.map do |app_name, data|
+        containers = data[:containers]
+        total = containers.size
+        running = containers.count { |c| c[:state] == "running" }
+        ready = "#{running}/#{total}"
+
+        # Determine overall status
+        states = containers.map { |c| c[:state] }.uniq
+        status = if states.all? { |s| s == "running" }
+                   "Running"
+        elsif states.all? { |s| s == "exited" }
+                   "Stopped"
+        elsif states.include?("running")
+                   "Degraded"
+        elsif states.include?("paused")
+                   "Paused"
+        else
+                   "Unknown"
+        end
+
+        { name: app_name, status: status, ready: ready }
+      end
+
+      { apps: apps.sort_by { |a| a[:name] } }
+    end
+
+    # Format app status for display
+    def format_app_status(status)
+      case status
+      when "Running"
+        status
+      when "Degraded"
+        status
+      when "Stopped"
+        status
+      when "Paused"
+        status
+      else
+        status
+      end
+    end
+
+    # Count resources in a namespace directory
+    def count_resources(namespace_path, resource_type)
+      resource_dir = File.join(namespace_path, resource_type)
+      return 0 unless Dir.exist?(resource_dir)
+
+      Dir.entries(resource_dir)
+         .select { |entry| File.directory?(File.join(resource_dir, entry)) && !entry.start_with?(".") }
+         .size
+    end
+
+    # Get usage information from remote host
+    def get_usage_info(remote_host)
+      # Get disk usage
+      disk_command = "ssh #{remote_host} 'df -h /data 2>/dev/null | tail -1' 2>/dev/null"
+      disk_output = `#{disk_command}`.strip
+      disk_info = nil
+      if disk_output && !disk_output.empty?
+        parts = disk_output.split
+        disk_info = "#{parts[2]} / #{parts[1]}" if parts.size >= 4
+      end
+
+      # Get container counts
+      container_command = "ssh #{remote_host} 'docker ps -q | wc -l; docker ps -aq | wc -l' 2>/dev/null"
+      container_output = `#{container_command}`.strip
+      container_info = nil
+      if container_output && !container_output.empty?
+        lines = container_output.split("\n")
+        if lines.size == 2
+          running = lines[0].strip.to_i
+          total = lines[1].strip.to_i
+          stopped = total - running
+          container_info = "#{running} running"
+          container_info += ", #{stopped} stopped" if stopped > 0
+        end
+      end
+
+      {
+        available: disk_info || container_info,
+        disk: disk_info,
+        containers: container_info
+      }
+    end
+
+
     def manifest_filename
       ".namespace.yaml"
     end

data/lib/walheim/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Walheim
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: walheim
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Akhyar Amarullah
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement