query_file_ownership

Instructions

Implementation Reference

• src/arch_ops_server/pacman.py:987-1047 (handler)

  Main handler function for query_file_ownership tool. Routes to find_package_owner, list_package_files, or search_package_files based on mode.

  async def query_file_ownership(
      query: str,
      mode: str,
      filter_pattern: Optional[str] = None
  ) -> Dict[str, Any]:
      """
      Unified tool for querying file ownership relationships.
      
      This consolidates three operations:
      - file_to_package: Find which package owns a specific file (replaces find_package_owner)
      - package_to_files: List all files owned by a package (replaces list_package_files)
      - filename_search: Search for files across all packages (replaces search_package_files)
  
      Args:
          query: The query string (file path, package name, or filename pattern depending on mode)
          mode: Query mode - "file_to_package", "package_to_files", or "filename_search"
          filter_pattern: Optional regex pattern to filter files (only used in package_to_files mode)
  
      Returns:
          Dict with query results appropriate to the mode
      """
      if not IS_ARCH:
          return create_error_response(
              "NotSupported",
              "File ownership queries are only available on Arch Linux"
          )
  
      if not check_command_exists("pacman"):
          return create_error_response(
              "CommandNotFound",
              "pacman command not found"
          )
  
      # Validate mode
      valid_modes = ["file_to_package", "package_to_files", "filename_search"]
      if mode not in valid_modes:
          return create_error_response(
              "ValidationError",
              f"Invalid mode '{mode}'. Must be one of: {', '.join(valid_modes)}"
          )
  
      logger.info(f"File ownership query: mode={mode}, query={query}")
  
      # Route to appropriate implementation based on mode
      if mode == "file_to_package":
          # Find which package owns a specific file (replaces find_package_owner)
          return await find_package_owner(query)
      
      elif mode == "package_to_files":
          # List all files owned by a package (replaces list_package_files)
          return await list_package_files(query, filter_pattern)
      
      elif mode == "filename_search":
          # Search for files across all packages (replaces search_package_files)
          return await search_package_files(query)
      
      # This should never be reached due to validation above
      return create_error_response(
          "InternalError",
          f"Unexpected mode: {mode}"
      )

• src/arch_ops_server/server.py:801-825 (registration)

  Tool registration in list_tools() with input schema defining query, mode, and optional filter_pattern parameters.

  # File Ownership Query (Consolidated)
  Tool(
      name="query_file_ownership",
      description="[ORGANIZATION] Unified tool for querying file-package ownership relationships. Supports three modes: 'file_to_package' (find which package owns a file), 'package_to_files' (list all files in a package with optional filtering), and 'filename_search' (search for files across all packages). Only works on Arch Linux. Examples: mode='file_to_package', query='/usr/bin/python' → returns 'python' package; mode='package_to_files', query='systemd', filter_pattern='*.service' → lists all systemd service files; mode='filename_search', query='*.desktop' → finds all packages with desktop entries.",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Query string: file path for file_to_package mode, package name for package_to_files mode, or filename pattern for filename_search mode"
              },
              "mode": {
                  "type": "string",
                  "enum": ["file_to_package", "package_to_files", "filename_search"],
                  "description": "Query mode: 'file_to_package' (find package owner), 'package_to_files' (list package files), or 'filename_search' (search across packages)"
              },
              "filter_pattern": {
                  "type": "string",
                  "description": "Optional regex pattern to filter files (only used in package_to_files mode, e.g., '*.conf' or '/etc/')"
              }
          },
          "required": ["query", "mode"]
      },
      annotations=ToolAnnotations(readOnlyHint=True)
  ),

• src/arch_ops_server/server.py:1165-1174 (registration)

  Tool dispatch in call_tool() that extracts arguments and delegates to the query_file_ownership handler.

  # File Ownership Query
  elif name == "query_file_ownership":
      if not IS_ARCH:
          return [TextContent(type="text", text=create_platform_error_message("query_file_ownership"))]
  
      query = arguments["query"]
      mode = arguments["mode"]
      filter_pattern = arguments.get("filter_pattern", None)
      result = await query_file_ownership(query, mode, filter_pattern)
      return [TextContent(type="text", text=json.dumps(result, indent=2))]

• src/arch_ops_server/tool_metadata.py:141-149 (schema)

  Tool metadata definition including category (organization), platform (arch), permission (read), and related tools.

  "query_file_ownership": ToolMetadata(
      name="query_file_ownership",
      category="organization",
      platform="arch",
      permission="read",
      workflow="debug",
      related_tools=["verify_package_integrity", "manage_groups"],
      prerequisite_tools=[]
  ),

• src/arch_ops_server/__init__.py:22-34 (helper)

  Export of query_file_ownership from pacman module, making it importable as part of the package.

  from .pacman import (
      get_official_package_info,
      check_updates_dry_run,
      remove_package,
      remove_packages_batch,
      remove_packages,
      list_orphan_packages,
      remove_orphans,
      manage_orphans,
      find_package_owner,
      list_package_files,
      search_package_files,
      query_file_ownership,