feat: package search cmd with version info (#21)

* registry list cmd

* added verbose for detailed view

* package search cmd with flags

* fixed gql query issues

* refactoring

* display refactoring

* added openapi endpoints for package search, with fallback logic

* refactorings

* refactorings

* print package search with total count, further refactorings

Author: thelonewolf1603

CLAUDE.md

@@ -3,7 +3,6 @@
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Project Overview
-
 This is a Go-based CLI tool for interacting with JuliaHub, a platform for Julia computing. The CLI provides commands for authentication, dataset management, registry management, project management, user information, token management, Git integration, and Julia integration.
 
 ## Architecture
@@ -13,7 +12,8 @@ The application follows a command-line interface pattern using the Cobra library
 - **main.go**: Core CLI structure with command definitions and configuration management
 - **auth.go**: OAuth2 device flow authentication with JWT token handling
 - **datasets.go**: Dataset operations (list, download, upload, status) with REST API integration
-- **registries.go**: Registry operations (list) with REST API integration
+- **registries.go**: Registry operations (list, fetch) with REST API integration
+- **packages.go**: Package search with REST API primary path (`/packages/info`) and GraphQL fallback
 - **projects.go**: Project management using GraphQL API with user filtering
 - **user.go**: User information retrieval using GraphQL API and REST API for listing users
 - **tokens.go**: Token management operations (list) with REST API integration
@@ -31,8 +31,8 @@ The application follows a command-line interface pattern using the Cobra library
    - Stores tokens securely in `~/.juliahub` with 0600 permissions
 
 2. **API Integration**:
-   - **REST API**: Used for dataset operations (`/api/v1/datasets`, `/datasets/{uuid}/url/{version}`), registry operations (`/api/v1/ui/registries/descriptions`), token management (`/app/token/activelist`) and user management (`/app/config/features/manage`)
-   - **GraphQL API**: Used for projects and user info (`/v1/graphql`)
+   - **REST API**: Used for dataset operations (`/api/v1/datasets`, `/datasets/{uuid}/url/{version}`), registry operations (`/api/v1/registry/registries/descriptions`), package search primary path (`/packages/info`), token management (`/app/token/activelist`) and user management (`/app/config/features/manage`)
+   - **GraphQL API**: Used for projects, user info, and package search fallback (`/v1/graphql`)
    - **Headers**: All GraphQL requests require `X-Hasura-Role: jhuser` header
    - **Authentication**: Uses ID tokens (`token.IDToken`) for API calls
 
@@ -41,6 +41,7 @@ The application follows a command-line interface pattern using the Cobra library
    - `jh dataset`: Dataset operations (list, download, upload, status)
    - `jh registry`: Registry operations (list with REST API, supports verbose mode)
    - `jh project`: Project management (list with GraphQL, supports user filtering)
+   - `jh package`: Package search (REST primary via `/packages/info`, GraphQL fallback)
    - `jh user`: User information (info with GraphQL)
    - `jh admin`: Administrative commands (user management, token management)
    - `jh admin user`: User management (list all users with REST API, supports verbose mode)
@@ -90,6 +91,14 @@ go run . dataset download <dataset-name>
 go run . dataset upload --new ./file.tar.gz
 ```
 
+### Test package search operations
+```bash
+go run . package search dataframes
+go run . package search --verbose plots
+go run . package search --limit 20 ml
+go run . package search --registries General optimization
+```
+
 ### Test registry operations
 ```bash
 go run . registry list
@@ -187,6 +196,7 @@ The application uses OAuth2 device flow:
 - **Dataset operations**: Use presigned URLs for upload/download
 - **User management**: `/app/config/features/manage` endpoint for listing all users
 - **Token management**: `/app/token/activelist` endpoint for listing all API tokens
+- **Package search primary**: `/packages/info` endpoint with `name`, `registries`, `tags`, `licenses`, `limit`, `offset` query params; returns `{packages: [...], meta: {total: N}}`
 - **Authentication**: Bearer token with ID token
 - **Upload workflow**: 3-step process (request presigned URL, upload to URL, close upload)
 
@@ -308,6 +318,13 @@ jh run setup
 - Token list output is concise by default (Subject, Created By, and Expired status only); use `--verbose` flag for detailed information (signature, creation date, expiration date with estimate indicator)
 - Token dates are formatted in human-readable format and converted to local timezone (respects system timezone or TZ environment variable)
 - Token expiration estimate indicator only shown when `expires_at_is_estimate` is true in API response
+- Package search (`jh package search`) tries REST API (`/packages/info`) first, then falls back to GraphQL (`FilteredPackagesWithCount` via `/v1/graphql`) on failure; a warning is printed to stderr when the fallback is used
+- Package search GraphQL fallback passes `--registries` as registry IDs to the `registries` variable
+- `fetchRegistries` in `registries.go` is used by both `listRegistries` (for display) and `packageSearchCmd` (to resolve registry names to IDs for GraphQL and names for REST fallback)
+- Both REST and GraphQL package search paths produce identical output columns (Registry and Owner); GraphQL resolves registry names from the `registryIDs`/`registryNames` already in `PackageSearchParams` — no extra API call needed
+- A package in multiple registries appears as multiple rows (one per registry) in both REST and GraphQL paths, since the GraphQL view (`package_rank_vw`) is already flattened per package-registry combination
+- GraphQL fallback uses `package_search_with_count.gql` which fetches both the package list and aggregate count in a single request (`package_search` + `package_search_aggregate` root fields)
+- `executeGraphQL(server, token, req)` in `packages.go` is a shared helper for GraphQL POST requests (sets Authorization, Content-Type, Accept, X-Hasura-Role headers)
 
 ## Implementation Details
 

README.md

@@ -6,6 +6,7 @@ A command-line interface for interacting with JuliaHub, a platform for Julia com
 
 - **Authentication**: OAuth2 device flow authentication with JWT token handling
 - **Dataset Management**: List, download, upload, and check status of datasets
+- **Package Search**: Search Julia packages across registries via REST API (GraphQL fallback)
 - **Registry Management**: List and manage Julia package registries
 - **Project Management**: List and filter projects using GraphQL API
 - **Git Integration**: Clone, push, fetch, and pull with automatic JuliaHub authentication
@@ -150,6 +151,15 @@ go build -o jh .
 - `jh dataset upload [dataset-id] <file-path>` - Upload a dataset
 - `jh dataset status <dataset-id> [version]` - Show dataset status
 
+### Package Search (`jh package`)
+
+- `jh package search [search-term]` - Search for Julia packages
+  - Default: Shows Name, Registry, Owner, Version, and Description
+  - `jh package search --verbose` - Show detailed package information including UUID, repository, tags, stars, docs, and license
+  - `--registries <names>` - Filter by registry names (comma-separated, e.g. `General,MyRegistry`)
+  - `--limit <n>` - Maximum results to return (default: 10)
+  - `--offset <n>` - Number of results to skip
+
 ### Registry Management (`jh registry`)
 
 - `jh registry list` - List all package registries on JuliaHub
@@ -234,6 +244,22 @@ jh dataset upload --new ./my-data.tar.gz
 jh dataset upload my-dataset ./updated-data.tar.gz
 ```
 
+### Package Search
+
+```bash
+# Search for packages by name
+jh package search dataframes
+
+# Search with verbose output
+jh package search --verbose plots
+
+# Filter by registry
+jh package search --registries General optimization
+
+# Limit and paginate results
+jh package search --limit 20 --offset 0 ml
+```
+
 ### Registry Operations
 
 ```bash
@@ -333,7 +359,7 @@ Note: Arguments after `--` are passed directly to Julia. The `jh run` command:
 
 - **Built with Go** using the Cobra CLI framework
 - **Authentication**: OAuth2 device flow with JWT token management
-- **APIs**: REST API for datasets, GraphQL API for projects and user info
+- **APIs**: REST API for datasets and package search (primary); GraphQL API for projects, user info, and package search fallback (single request returns results + total count)
 - **Git Integration**: Seamless authentication via HTTP headers or credential helper
 - **Cross-platform**: Supports Windows, macOS, and Linux
 

main.go

@@ -164,6 +164,7 @@ job execution, project management, Git integration, and package hosting capabili
 Available command categories:
   auth      - Authentication and token management
   dataset   - Dataset operations (list, download, upload, status)
+  package   - Package search and exploration
   registry  - Registry management (list registries)
   project   - Project management (list, filter by user)
   user      - User information and profile
@@ -555,6 +556,109 @@ Displays:
 	},
 }
 
+var packageCmd = &cobra.Command{
+	Use:   "package",
+	Short: "Package search commands",
+	Long: `Search and explore Julia packages on JuliaHub.
+
+Packages are Julia libraries that provide reusable functionality. JuliaHub
+hosts packages from multiple registries and provides comprehensive search
+capabilities including filtering by tags, registries, and more.`,
+}
+
+var packageSearchCmd = &cobra.Command{
+	Use:   "search [search-term]",
+	Short: "Search for packages",
+	Long: `Search for Julia packages on JuliaHub.
+
+Displays package information including:
+- Package name, owner, and UUID
+- Version information
+- Description and repository
+- Tags and star count
+- License information
+
+Filtering options:
+- Filter by registry using --registries flag (searches all registries by default)
+
+Use --verbose flag for comprehensive output, or get a concise summary by default.`,
+	Example: "  jh package search dataframes\n  jh package search --verbose plots\n  jh package search --limit 20 ml\n  jh package search --registries General optimization",
+	Args:    cobra.MaximumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		server, err := getServerFromFlagOrConfig(cmd)
+		if err != nil {
+			fmt.Printf("Failed to get server config: %v\n", err)
+			os.Exit(1)
+		}
+
+		search := ""
+		if len(args) > 0 {
+			search = args[0]
+		}
+
+		limit, _ := cmd.Flags().GetInt("limit")
+		offset, _ := cmd.Flags().GetInt("offset")
+		verbose, _ := cmd.Flags().GetBool("verbose")
+		registryNamesStr, _ := cmd.Flags().GetString("registries")
+
+		// Fetch all registries from the API
+		allRegistries, err := fetchRegistries(server)
+		if err != nil {
+			fmt.Printf("Failed to fetch registries: %v\n", err)
+			os.Exit(1)
+		}
+
+		// Determine which registry IDs and names to use
+		var registryIDs []int
+		var registryNames []string
+		if registryNamesStr != "" {
+			// Use only specified registries
+			requestedNames := strings.Split(registryNamesStr, ",")
+			for _, requestedName := range requestedNames {
+				requestedName = strings.TrimSpace(requestedName)
+				if requestedName == "" {
+					continue
+				}
+
+				// Find matching registry (case-insensitive)
+				found := false
+				for _, reg := range allRegistries {
+					if strings.EqualFold(reg.Name, requestedName) {
+						registryIDs = append(registryIDs, reg.RegistryID)
+						registryNames = append(registryNames, reg.Name)
+						found = true
+						break
+					}
+				}
+
+				if !found {
+					fmt.Printf("Registry not found: '%s'\n", requestedName)
+					os.Exit(1)
+				}
+			}
+		} else {
+			// Use all registries
+			for _, reg := range allRegistries {
+				registryIDs = append(registryIDs, reg.RegistryID)
+				registryNames = append(registryNames, reg.Name)
+			}
+		}
+
+		if err := searchPackages(PackageSearchParams{
+			Server:        server,
+			Search:        search,
+			Limit:         limit,
+			Offset:        offset,
+			RegistryIDs:   registryIDs,
+			RegistryNames: registryNames,
+			Verbose:       verbose,
+		}); err != nil {
+			fmt.Printf("Failed to search packages: %v\n", err)
+			os.Exit(1)
+		}
+	},
+}
+
 var registryCmd = &cobra.Command{
 	Use:   "registry",
 	Short: "Registry management commands",
@@ -1121,6 +1225,11 @@ func init() {
 	datasetUploadCmd.Flags().StringP("server", "s", "juliahub.com", "JuliaHub server")
 	datasetUploadCmd.Flags().Bool("new", false, "Create a new dataset")
 	datasetStatusCmd.Flags().StringP("server", "s", "juliahub.com", "JuliaHub server")
+	packageSearchCmd.Flags().StringP("server", "s", "juliahub.com", "JuliaHub server")
+	packageSearchCmd.Flags().Int("limit", 10, "Maximum number of results to return")
+	packageSearchCmd.Flags().Int("offset", 0, "Number of results to skip")
+	packageSearchCmd.Flags().String("registries", "", "Filter by registry names (comma-separated, e.g., 'General,CustomRegistry')")
+	packageSearchCmd.Flags().Bool("verbose", false, "Show detailed package information")
 	registryListCmd.Flags().StringP("server", "s", "juliahub.com", "JuliaHub server")
 	registryListCmd.Flags().Bool("verbose", false, "Show detailed registry information")
 	projectListCmd.Flags().StringP("server", "s", "juliahub.com", "JuliaHub server")
@@ -1139,6 +1248,7 @@ func init() {
 	authCmd.AddCommand(authLoginCmd, authRefreshCmd, authStatusCmd, authEnvCmd)
 	jobCmd.AddCommand(jobListCmd, jobStartCmd)
 	datasetCmd.AddCommand(datasetListCmd, datasetDownloadCmd, datasetUploadCmd, datasetStatusCmd)
+	packageCmd.AddCommand(packageSearchCmd)
 	registryCmd.AddCommand(registryListCmd)
 	projectCmd.AddCommand(projectListCmd)
 	userCmd.AddCommand(userInfoCmd)
@@ -1149,7 +1259,7 @@ func init() {
 	runCmd.AddCommand(runSetupCmd)
 	gitCredentialCmd.AddCommand(gitCredentialHelperCmd, gitCredentialGetCmd, gitCredentialStoreCmd, gitCredentialEraseCmd, gitCredentialSetupCmd)
 
-	rootCmd.AddCommand(authCmd, jobCmd, datasetCmd, projectCmd, registryCmd, userCmd, adminCmd, juliaCmd, cloneCmd, pushCmd, fetchCmd, pullCmd, runCmd, gitCredentialCmd, updateCmd)
+	rootCmd.AddCommand(authCmd, jobCmd, datasetCmd, projectCmd, packageCmd, registryCmd, userCmd, adminCmd, juliaCmd, cloneCmd, pushCmd, fetchCmd, pullCmd, runCmd, gitCredentialCmd, updateCmd)
 }
 
 func main() {

package_search_with_count.gql

@@ -0,0 +1,78 @@
+query FilteredPackagesWithCount(
+  $search: String
+  $limit: Int
+  $offset: Int
+  $matchtags: _text
+  $registries: _int8
+  $hasfailures: Boolean
+  $installed: Boolean
+  $notinstalled: Boolean
+  $licenses: _text
+  $order: [package_rank_vw_order_by!]
+  $filter: package_rank_vw_bool_exp = {}
+) {
+  package_search(
+    args: {
+      search: $search
+      matchtags: $matchtags
+      licenses: $licenses
+      isinstalled: $installed
+      notinstalled: $notinstalled
+      hasfailures: $hasfailures
+      registrylist: $registries
+    }
+    order_by: $order
+    limit: $limit
+    offset: $offset
+    where: { _and: [{ fit: { _gte: 1 } }, $filter] }
+  ) {
+    name
+    owner
+    slug
+    license
+    isapp
+    score
+    registrymap {
+      version
+      registryid
+      status
+      isapp
+      isjsml
+      __typename
+    }
+    metadata {
+      docshosteduri
+      versions
+      description
+      docslink
+      repo
+      owner
+      tags
+      starcount
+      __typename
+    }
+    uuid
+    installed
+    failures {
+      package_version
+      __typename
+    }
+    __typename
+  }
+  package_search_aggregate(
+    args: {
+      search: $search
+      matchtags: $matchtags
+      licenses: $licenses
+      isinstalled: $installed
+      notinstalled: $notinstalled
+      hasfailures: $hasfailures
+      registrylist: $registries
+    }
+    where: { _and: [{ fit: { _gte: 1 } }, $filter] }
+  ) {
+    aggregate {
+      count
+    }
+  }
+}