feat(cli): add blocks list with filtering and JSON output

cmd/wsh/cmd/wshcmd-blocks.go

@@ -0,0 +1,234 @@
+// Copyright 2025, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/wavetermdev/waveterm/pkg/waveobj"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc/wshclient"
+)
+
+// Command-line flags for the blocks commands
+var (
+	blocksWindowId    string // Window ID to filter blocks by
+	blocksWorkspaceId string // Workspace ID to filter blocks by
+	blocksTabId       string // Tab ID to filter blocks by
+	blocksView        string // View type to filter blocks by (term, web, etc.)
+	blocksJSON        bool   // Whether to output as JSON
+)
+
+// BlockDetails represents the information about a block returned by the list command
+type BlockDetails struct {
+	BlockId     string              `json:"blockid"`     // Unique identifier for the block
+	WorkspaceId string              `json:"workspaceid"` // ID of the workspace containing the block
+	TabId       string              `json:"tabid"`       // ID of the tab containing the block
+	Meta        waveobj.MetaMapType `json:"meta"`        // Block metadata including view type
+}
+
+// blocksListCmd represents the 'blocks list' command
+var blocksListCmd = &cobra.Command{
+	Use:     "list",
+	Aliases: []string{"ls", "get"},
+	Short:   "List blocks in workspaces/windows",
+	Long:    `List blocks with optional filtering by workspace, window, tab, or view type.
+
+Examples:
+  # List blocks from all workspaces
+  wsh blocks list
+
+  # List only terminal blocks
+  wsh blocks list --view=term
+
+  # Filter by window ID (get IDs from 'wsh workspace list')
+  wsh blocks list --window=dbca23b5-f89b-4780-a0fe-452f5bc7d900
+
+  # Filter by workspace ID
+  wsh blocks list --workspace=12d0c067-378e-454c-872e-77a314248114
+
+  # Output as JSON for scripting
+  wsh blocks list --json`,
+	RunE:    blocksListRun,
+	PreRunE: preRunSetupRpcClient,
+}
+
+// init registers the blocks commands with the root command
+// It configures all the flags and command options
+func init() {
+	blocksListCmd.Flags().StringVar(&blocksWindowId, "window", "", "restrict to window id")
+	blocksListCmd.Flags().StringVar(&blocksWorkspaceId, "workspace", "", "restrict to workspace id")
+	blocksListCmd.Flags().StringVar(&blocksTabId, "tab", "", "restrict to tab id")
+	blocksListCmd.Flags().StringVar(&blocksView, "view", "", "restrict to view type (term/terminal, web/browser, preview/edit, sysinfo, waveai)")
+	blocksListCmd.Flags().BoolVar(&blocksJSON, "json", false, "output as JSON")
+
+	for _, cmd := range rootCmd.Commands() {
+		if cmd.Use == "blocks" {
+			cmd.AddCommand(blocksListCmd)
+			return
+		}
+	}
+
+	blocksCmd := &cobra.Command{
+		Use:     "blocks",
+		Short:   "Manage blocks",
+		Long:    "Commands for working with blocks",
+	}
+
+	blocksCmd.AddCommand(blocksListCmd)
+	rootCmd.AddCommand(blocksCmd)
+}
+
+// blocksListRun implements the 'blocks list' command
+// It retrieves and displays blocks with optional filtering by workspace, window, tab, or view type
+func blocksListRun(cmd *cobra.Command, args []string) error {
+	var allBlocks []BlockDetails
+
+	workspaces, err := wshclient.WorkspaceListCommand(RpcClient, &wshrpc.RpcOpts{Timeout: 5000})
+	if err != nil {
+		return fmt.Errorf("failed to list workspaces: %v", err)
+	}
+
+	if len(workspaces) == 0 {
+		return fmt.Errorf("no workspaces found")
+	}
+
+	var workspaceIdsToQuery []string
+
+	// Determine which workspaces to query
+	if blocksWorkspaceId != "" {
+		workspaceIdsToQuery = []string{blocksWorkspaceId}
+	} else if blocksWindowId != "" {
+		// Find workspace ID for this window
+		windowFound := false
+		for _, ws := range workspaces {
+			if ws.WindowId == blocksWindowId {
+				workspaceIdsToQuery = []string{ws.WorkspaceData.OID}
+				windowFound = true
+				break
+			}
+		}
+		if !windowFound {
+			return fmt.Errorf("window %s not found", blocksWindowId)
+		}
+	} else {
+		// Default to all workspaces
+		for _, ws := range workspaces {
+			workspaceIdsToQuery = append(workspaceIdsToQuery, ws.WorkspaceData.OID)
+		}
+	}
+
+	// Query each selected workspace
+	for _, wsId := range workspaceIdsToQuery {
+		req := wshrpc.BlocksListRequest{
+			WorkspaceId: wsId,
+		}
+
+		blocks, err := wshclient.BlocksListCommand(RpcClient, req, &wshrpc.RpcOpts{Timeout: 5000})
+		if err != nil {
+			WriteStderr("Warning: couldn't list blocks for workspace %s: %v\n", wsId, err)
+			continue
+		}
+
+		// Apply filters
+		for _, b := range blocks {
+			if blocksTabId != "" && blocksTabId != "current" && b.TabId != blocksTabId {
+				continue
+			}
+
+			if blocksView != "" {
+				view := b.Meta.GetString(waveobj.MetaKey_View, "")
+
+				// Support view type aliases
+				if !matchesViewType(view, blocksView) {
+					continue
+				}
+			}
+
+			allBlocks = append(allBlocks, BlockDetails{
+				BlockId:     b.BlockId,
+				WorkspaceId: b.WorkspaceId,
+				TabId:       b.TabId,
+				Meta:        b.Meta,
+			})
+		}
+	}
+
+	// Output results
+	if blocksJSON {
+		bytes, err := json.MarshalIndent(allBlocks, "", "  ")
+		if err != nil {
+			return fmt.Errorf("failed to marshal JSON: %v", err)
+		}
+		WriteStdout("%s\n", string(bytes))
+		return nil
+	}
+
+	if len(allBlocks) == 0 {
+		WriteStdout("No blocks found\n")
+		return nil
+	}
+
+	format := "%-36s  %-10s  %-36s  %-15s  %s\n"
+	WriteStdout(format, "BLOCK ID", "WORKSPACE", "TAB ID", "VIEW", "CONTENT")
+
+	for _, b := range allBlocks {
+		view := b.Meta.GetString(waveobj.MetaKey_View, "<unknown>")
+		var content string
+
+		switch view {
+		case "preview", "edit":
+			content = b.Meta.GetString(waveobj.MetaKey_File, "<no file>")
+		case "web":
+			content = b.Meta.GetString(waveobj.MetaKey_Url, "<no url>")
+		case "term":
+			content = b.Meta.GetString(waveobj.MetaKey_CmdCwd, "<no cwd>")
+		default:
+			content = ""
+		}
+
+		wsID := b.WorkspaceId
+		if len(wsID) > 10 {
+			wsID = wsID[0:8] + ".."
+		}
+
+		tabID := b.TabId
+		if len(tabID) > 36 {
+			tabID = tabID[0:34] + ".."
+		}
+
+		WriteStdout(format, b.BlockId, wsID, tabID, view, content)
+	}
+
+	return nil
+}
+
+// matchesViewType checks if a view type matches a filter, supporting aliases
+// It handles different aliases for the same view type, allowing flexible filtering
+// Examples: "term" matches "terminal", "shell", "console"; "web" matches "browser", "url"
+func matchesViewType(actual, filter string) bool {
+	// Direct match (case insensitive)
+	if strings.EqualFold(actual, filter) {
+		return true
+	}
+
+	// Handle aliases
+	switch strings.ToLower(filter) {
+	case "preview", "edit":
+		return strings.EqualFold(actual, "preview") || strings.EqualFold(actual, "edit")
+	case "terminal", "term", "shell", "console":
+		return strings.EqualFold(actual, "term")
+	case "web", "browser", "url":
+		return strings.EqualFold(actual, "web")
+	case "ai", "waveai", "assistant":
+		return strings.EqualFold(actual, "waveai")
+	case "sys", "sysinfo", "system":
+		return strings.EqualFold(actual, "sysinfo")
+	}
+
+	return false
+}

frontend/app/store/wshclientapi.ts

@@ -32,6 +32,11 @@ class RpcApiType {
         return client.wshRpcCall("blockinfo", data, opts);
     }
 
+    // command "blockslist" [call]
+    BlocksListCommand(client: WshClient, data: BlocksListRequest, opts?: RpcOpts): Promise<BlocksListEntry[]> {
+        return client.wshRpcCall("blockslist", data, opts);
+    }
+
     // command "connconnect" [call]
     ConnConnectCommand(client: WshClient, data: ConnRequest, opts?: RpcOpts): Promise<void> {
         return client.wshRpcCall("connconnect", data, opts);

frontend/types/gotypes.d.ts

@@ -84,6 +84,21 @@ declare global {
         inputdata64: string;
     };
 
+    // wshrpc.BlocksListEntry
+    type BlocksListEntry = {
+        windowid: string;
+        workspaceid: string;
+        tabid: string;
+        blockid: string;
+        meta: MetaType;
+    };
+
+    // wshrpc.BlocksListRequest
+    type BlocksListRequest = {
+        windowid?: string;
+        workspaceid?: string;
+    };
+
     // waveobj.Client
     type Client = WaveObj & {
         windowids: string[];

pkg/wshrpc/wshclient/wshclient.go

@@ -46,6 +46,12 @@ func BlockInfoCommand(w *wshutil.WshRpc, data string, opts *wshrpc.RpcOpts) (*ws
 	return resp, err
 }
 
+// command "blockslist", wshserver.BlocksListCommand
+func BlocksListCommand(w *wshutil.WshRpc, data wshrpc.BlocksListRequest, opts *wshrpc.RpcOpts) ([]wshrpc.BlocksListEntry, error) {
+	resp, err := sendRpcRequestCallHelper[[]wshrpc.BlocksListEntry](w, "blockslist", data, opts)
+	return resp, err
+}
+
 // command "connconnect", wshserver.ConnConnectCommand
 func ConnConnectCommand(w *wshutil.WshRpc, data wshrpc.ConnRequest, opts *wshrpc.RpcOpts) error {
 	_, err := sendRpcRequestCallHelper[any](w, "connconnect", data, opts)

pkg/wshrpc/wshrpctypes.go

@@ -67,6 +67,7 @@ const (
 	Command_Mkdir             = "mkdir"
 	Command_ResolveIds        = "resolveids"
 	Command_BlockInfo         = "blockinfo"
+	Command_BlocksList        = "blockslist"
 	Command_CreateBlock       = "createblock"
 	Command_DeleteBlock       = "deleteblock"
 
@@ -196,6 +197,7 @@ type WshRpcInterface interface {
 	SetConnectionsConfigCommand(ctx context.Context, data ConnConfigRequest) error
 	GetFullConfigCommand(ctx context.Context) (wconfig.FullConfigType, error)
 	BlockInfoCommand(ctx context.Context, blockId string) (*BlockInfoData, error)
+	BlocksListCommand(ctx context.Context, data BlocksListRequest) ([]BlocksListEntry, error)
 	WaveInfoCommand(ctx context.Context) (*WaveInfoData, error)
 	WshActivityCommand(ct context.Context, data map[string]int) error
 	ActivityCommand(ctx context.Context, data ActivityUpdate) error
@@ -678,6 +680,19 @@ type WorkspaceInfoData struct {
 	WorkspaceData *waveobj.Workspace `json:"workspacedata"`
 }
 
+type BlocksListRequest struct {
+	WindowId    string `json:"windowid,omitempty"`
+	WorkspaceId string `json:"workspaceid,omitempty"`
+}
+
+type BlocksListEntry struct {
+	WindowId    string              `json:"windowid"`
+	WorkspaceId string              `json:"workspaceid"`
+	TabId       string              `json:"tabid"`
+	BlockId     string              `json:"blockid"`
+	Meta        waveobj.MetaMapType `json:"meta"`
+}
+
 type AiMessageData struct {
 	Message string `json:"message,omitempty"`
 }

pkg/wshrpc/wshserver/wshserver.go

@@ -813,6 +813,73 @@ func (ws *WshServer) WaveInfoCommand(ctx context.Context) (*wshrpc.WaveInfoData,
 	}, nil
 }
 
+// BlocksListCommand returns every block visible in the requested
+// scope (current workspace by default).
+func (ws *WshServer) BlocksListCommand(
+	ctx context.Context,
+	req wshrpc.BlocksListRequest) ([]wshrpc.BlocksListEntry, error) {
+	var results []wshrpc.BlocksListEntry
+
+	// Resolve the set of workspaces to inspect
+	var workspaceIDs []string
+	if req.WorkspaceId != "" {
+		workspaceIDs = []string{req.WorkspaceId}
+	} else if req.WindowId != "" {
+		win, err := wcore.GetWindow(ctx, req.WindowId)
+		if err != nil {
+			return nil, err
+		}
+		workspaceIDs = []string{win.WorkspaceId}
+	} else {
+		// "current" == first workspace in client focus list
+		client, err := wstore.DBGetSingleton[*waveobj.Client](ctx)
+		if err != nil {
+			return nil, err
+		}
+		if len(client.WindowIds) == 0 {
+			return nil, fmt.Errorf("no active window")
+		}
+		win, err := wcore.GetWindow(ctx, client.WindowIds[0])
+		if err != nil {
+			return nil, err
+		}
+		workspaceIDs = []string{win.WorkspaceId}
+	}
+
+	for _, wsID := range workspaceIDs {
+		wsData, err := wcore.GetWorkspace(ctx, wsID)
+		if err != nil {
+			return nil, err
+		}
+
+		windowId, err := wstore.DBFindWindowForWorkspaceId(ctx, wsID)
+		if err != nil {
+			log.Printf("error finding window for workspace %s: %v", wsID, err)
+		}
+
+		for _, tabID := range append(wsData.PinnedTabIds, wsData.TabIds...) {
+			tab, err := wstore.DBMustGet[*waveobj.Tab](ctx, tabID)
+			if err != nil {
+				return nil, err
+			}
+			for _, blkID := range tab.BlockIds {
+				blk, err := wstore.DBMustGet[*waveobj.Block](ctx, blkID)
+				if err != nil {
+					return nil, err
+				}
+				results = append(results, wshrpc.BlocksListEntry{
+					WindowId:    windowId,
+					WorkspaceId: wsID,
+					TabId:       tabID,
+					BlockId:     blkID,
+					Meta:        blk.Meta,
+				})
+			}
+		}
+	}
+	return results, nil
+}
+
 func (ws *WshServer) WorkspaceListCommand(ctx context.Context) ([]wshrpc.WorkspaceInfoData, error) {
 	workspaceList, err := wcore.ListWorkspaces(ctx)
 	if err != nil {