feat: [PRODUCT-608], [ENG-2210] add filter on sf nodes list (#230)

Co-authored-by: Matt Nappo <matt@modal.com>

Author: sigmachirality

src/lib/nodes/list.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Command } from "@commander-js/extra-typings";
+import { Command, Option } from "@commander-js/extra-typings";
 import { brightBlack, gray } from "jsr:@std/fmt/colors";
 import console from "node:console";
 import ora from "ora";
@@ -20,6 +20,7 @@ import { handleNodesError, nodesClient } from "../../nodesClient.ts";
 import { Row } from "../Row.tsx";
 import {
   createNodesTable,
+  DEFAULT_NODE_LS_LIMIT,
   getLastVM,
   getStatusColor,
   getVMStatusColor,
@@ -32,6 +33,16 @@ dayjs.extend(utc);
 dayjs.extend(advanced);
 dayjs.extend(timezone);
 
+// Valid node status values for filtering
+const VALID_STATES = [
+  "pending",
+  "awaitingcapacity",
+  "running",
+  "released",
+  "failed",
+  "terminated",
+] as const;
+
 // Helper component to display VMs in a table format using Ink
 function VMTable({ vms }: { vms: NonNullable<SFCNodes.Node["vms"]>["data"] }) {
   const sortedVms = vms.sort((a, b) => b.updated_at - a.updated_at);
@@ -447,27 +458,36 @@ async function listNodesAction(options: ReturnType<typeof list.opts>) {
 
     spinner.stop();
 
+    const filteredNodes = (options.status?.length)
+      ? nodes.filter((n) =>
+        options.status?.length &&
+        options.status.includes(n.status)
+      )
+      : nodes;
+
     if (options.json) {
-      console.log(JSON.stringify(nodes, null, 2));
+      console.log(JSON.stringify(filteredNodes, null, 2));
       return;
     }
 
-    if (nodes.length === 0) {
+    if (filteredNodes.length === 0) {
       console.log("No nodes found.");
       console.log(gray("\nCreate your first node:"));
       console.log("  sf nodes create my-first-node");
       return;
     }
 
     if (options.verbose) {
-      render(<NodesVerboseDisplay nodes={nodes} />);
+      render(
+        <NodesVerboseDisplay nodes={filteredNodes.slice(0, options.limit)} />,
+      );
     } else {
-      console.log(createNodesTable(nodes));
+      console.log(createNodesTable(filteredNodes, options.limit));
       console.log(
         gray(
-          `\nFound ${nodes.length} ${
-            pluralizeNodes(nodes.length)
-          }. Use --verbose for detailed information, such as previous virtual machines.`,
+          `\nFound ${filteredNodes.length} ${
+            pluralizeNodes(filteredNodes.length)
+          } total. Use --verbose for detailed information, such as previous virtual machines.`,
         ),
       );
 
@@ -476,7 +496,7 @@ async function listNodesAction(options: ReturnType<typeof list.opts>) {
       const seenLabels = new Set<string>();
 
       // Sort nodes by created_at (newest first), fallback to index for consistent ordering
-      const sortedNodes = [...nodes].sort((a, b) => {
+      const sortedNodes = [...filteredNodes].sort((a, b) => {
         const aTime = a.created_at || 0;
         const bTime = b.created_at || 0;
         return bTime - aTime; // Newest first
@@ -513,6 +533,16 @@ const list = new Command("list")
   .description("List all compute nodes")
   .showHelpAfterError()
   .option("--verbose", "Show detailed information for each node")
+  .option(
+    "--limit <number>",
+    "Limit the number of nodes to display",
+    Number.parseInt,
+    DEFAULT_NODE_LS_LIMIT,
+  )
+  .addOption(
+    new Option("--status <status...>", "Filter by node status")
+      .choices(VALID_STATES as (readonly SFCNodes.Status[])),
+  )
   .addOption(jsonOption)
   .addHelpText(
     "after",
@@ -524,6 +554,12 @@ Next Steps:\n
   \x1b[2m# List all nodes with detailed information\x1b[0m
   $ sf nodes list --verbose
 
+  \x1b[2m# List up to 100 nodes\x1b[0m
+  $ sf nodes list --limit 100
+
+  \x1b[2m# List pending or running nodes\x1b[0m
+  $ sf nodes list --status pending running
+
   \x1b[2m# List nodes in JSON format\x1b[0m
   $ sf nodes list --json
 `,

src/lib/nodes/utils.ts

@@ -95,12 +95,18 @@ export function getLastVM(node: SFCNodes.Node) {
     ).at(0);
 }
 
+export const DEFAULT_NODE_LS_LIMIT = 12 as const;
+
 /**
  * Creates a formatted table display of nodes
  * @param nodes Array of nodes to display
+ * @param limit Optional limit on number of nodes to display (default: show all)
  * @returns Formatted table string
  */
-export function createNodesTable(nodes: SFCNodes.Node[]): string {
+export function createNodesTable(
+  nodes: SFCNodes.Node[],
+  limit: number = DEFAULT_NODE_LS_LIMIT,
+): string {
   const table = new Table({
     head: [
       cyan("NAME"),
@@ -118,7 +124,9 @@ export function createNodesTable(nodes: SFCNodes.Node[]): string {
     },
   });
 
-  for (const node of nodes) {
+  const nodesToShow = limit ? nodes.slice(0, limit) : nodes;
+
+  for (const node of nodesToShow) {
     const startDate = node.start_at ? dayjs.unix(node.start_at) : null;
     const endDate = node.end_at ? dayjs.unix(node.end_at) : null;
 
@@ -142,6 +150,19 @@ export function createNodesTable(nodes: SFCNodes.Node[]): string {
     ]);
   }
 
+  if (limit && nodes.length > limit) {
+    table.push([
+      {
+        colSpan: 8,
+        content: brightBlack(
+          `${nodes.length - limit} older ${
+            pluralizeNodes(nodes.length - limit)
+          } not shown. Use sf nodes list --limit ${nodes.length} or sf nodes list --json to list all nodes.`,
+        ),
+      },
+    ]);
+  }
+
   return table.toString();
 }