feat: prompt dataset selection on ambiguous --data-set-metadata match

Author: BravoNatalie

src/add/add.ts

@@ -13,7 +13,7 @@ import pino from 'pino'
 import { CliFatal, isCliFatal } from '../common/cli-errors.js'
 import { DEVNET_CHAIN_ID } from '../common/get-rpc-url.js'
 import { describeLockupShortfall } from '../common/lockup-error.js'
-import { displayUploadResults, performAutoFunding, performUpload, validatePaymentSetup } from '../common/upload-flow.js'
+import { displayUploadResults, performAutoFunding, performUpload, promptDataSetSelection, validatePaymentSetup } from '../common/upload-flow.js'
 import { carInputError, INPUT_IS_CAR, isCar } from '../core/car/index.js'
 import { resolveDataSetIdsByMetadata } from '../core/data-set/index.js'
 import { normalizeMetadataConfig, withDerivedNameMetadata } from '../core/metadata/index.js'
@@ -197,11 +197,9 @@ export async function runAdd(options: AddOptions): Promise<AddResult> {
           `${pc.green('✓')} Matched existing data sets ${resolution.dataSetIds.join(', ')} via metadata filter`
         )
       } else if (resolution.kind === 'too-many-matches') {
-        spinner.stop(`${pc.red('✗')} --data-set-metadata matched too many data sets`)
-        throw new Error(
-          `--data-set-metadata matched ${resolution.matchedIds.length} data sets (${resolution.matchedIds.join(', ')}) ` +
-            `but expected ${resolution.expected} (narrow the filter or pass --data-set-id to pin the target).`
-        )
+        const chosenIds = await promptDataSetSelection(resolution.matchedDataSets, resolution.expected, spinner)
+        contextSelection.dataSetIds = chosenIds
+        effectiveDataSetMetadata = undefined
       } else if (resolution.kind === 'too-few-matches') {
         spinner.stop(`${pc.red('✗')} --data-set-metadata matched too few data sets`)
         throw new Error(

src/common/upload-flow.ts

@@ -5,10 +5,12 @@
  * including payment validation, storage context creation, and result display.
  */
 
+import { isCancel, multiselect } from '@clack/prompts'
 import type { CopyResult, FailedAttempt, Synapse } from '@filoz/synapse-sdk'
 import type { CID } from 'multiformats/cid'
 import pc from 'picocolors'
 import type { Logger } from 'pino'
+import type { DataSetSummary } from '../core/data-set/types.js'
 import { DEFAULT_LOCKUP_DAYS, type PaymentCapacityCheck } from '../core/payments/index.js'
 import {
   checkUploadReadiness,
@@ -21,11 +23,72 @@ import { formatUSDFC } from '../core/utils/format.js'
 import { autoFund } from '../payments/fund.js'
 import type { AutoFundOptions } from '../payments/types.js'
 import type { Spinner } from '../utils/cli-helpers.js'
-import { cancel, formatFileSize } from '../utils/cli-helpers.js'
+import { cancel, formatFileSize, isInteractive } from '../utils/cli-helpers.js'
 import { log } from '../utils/cli-logger.js'
 import { createSpinnerFlow } from '../utils/multi-operation-spinner.js'
 import { CliFatal } from './cli-errors.js'
 
+/**
+ * Prompt the user to select exactly `expectedCopies` data sets from a list of candidates.
+ *
+ * Only called when `--data-set-metadata` matched more datasets than `--copies` requires and
+ * the process is running in an interactive TTY. In non-interactive contexts the caller must
+ * throw before reaching here.
+ *
+ * Stops the spinner before rendering the Clack prompt (they cannot coexist).
+ */
+export async function promptDataSetSelection(
+  matchedDataSets: DataSetSummary[],
+  expectedCopies: number,
+  spinner: Spinner
+): Promise<bigint[]> {
+  if (!isInteractive()) {
+    throw new Error(
+      `--data-set-metadata matched ${matchedDataSets.length} data sets (${matchedDataSets.map((d) => d.dataSetId).join(', ')}) ` +
+        `but expected ${expectedCopies}. Narrow the filter, pass --data-set-ids, or run in a TTY to pick interactively.`
+    )
+  }
+
+  spinner.stop(`${pc.yellow('?')} --data-set-metadata matched ${matchedDataSets.length} data sets — select ${expectedCopies} to upload to`)
+
+  const options = matchedDataSets.map((ds) => {
+    const spaceName = ds.metadata?.['space-name']
+    const spaceDid = ds.metadata?.['space-did']
+    const pieces = Number(ds.activePieceCount ?? 0n)
+    const didDisplay = spaceDid ? `${spaceDid.slice(0, 20)}…${spaceDid.slice(-6)}` : undefined
+
+    const label = [
+      `#${ds.dataSetId}`,
+      spaceName,
+      didDisplay,
+      `(${pieces} piece${pieces !== 1 ? 's' : ''})`,
+    ]
+      .filter(Boolean)
+      .join('  ')
+
+    return { value: ds.dataSetId, label }
+  })
+
+  const chosen = await multiselect<bigint>({
+    message: `Select exactly ${expectedCopies} data set${expectedCopies !== 1 ? 's' : ''}:`,
+    options,
+    required: true,
+  })
+
+  if (isCancel(chosen)) {
+    cancel('Cancelled')
+    throw new CliFatal('Dataset selection cancelled')
+  }
+
+  if (chosen.length !== expectedCopies) {
+    throw new CliFatal(
+      `Select exactly ${expectedCopies} data set${expectedCopies !== 1 ? 's' : ''} — got ${chosen.length}. Re-run and select the correct number.`
+    )
+  }
+
+  return chosen
+}
+
 export interface UploadFlowOptions {
   /**
    * Context identifier for logging (e.g., 'import', 'add')

src/core/data-set/resolve-by-metadata.ts

@@ -1,11 +1,12 @@
 import type { Synapse } from '@filoz/synapse-sdk'
 import type { Logger } from 'pino'
 import { listDataSets } from './list-data-sets.js'
+import type { DataSetSummary } from './types.js'
 
 export type MetadataResolution =
   | { kind: 'no-match' }
   | { kind: 'matched'; dataSetIds: bigint[] }
-  | { kind: 'too-many-matches'; matchedIds: bigint[]; expected: number }
+  | { kind: 'too-many-matches'; matchedIds: bigint[]; matchedDataSets: DataSetSummary[]; expected: number }
   | { kind: 'too-few-matches'; matchedIds: bigint[]; expected: number }
 
 export interface ResolveByMetadataOptions {
@@ -58,7 +59,7 @@ export async function resolveDataSetIdsByMetadata(
   const matchedIds = matched.map((d) => d.dataSetId)
 
   if (matched.length > options.expectedCopies) {
-    return { kind: 'too-many-matches', matchedIds, expected: options.expectedCopies }
+    return { kind: 'too-many-matches', matchedIds, matchedDataSets: matched, expected: options.expectedCopies }
   }
 
   if (matched.length < options.expectedCopies) {

src/import/import.ts

@@ -15,7 +15,7 @@ import pino from 'pino'
 import { CliFatal, isCliFatal } from '../common/cli-errors.js'
 import { DEVNET_CHAIN_ID } from '../common/get-rpc-url.js'
 import { describeLockupShortfall } from '../common/lockup-error.js'
-import { displayUploadResults, performAutoFunding, performUpload, validatePaymentSetup } from '../common/upload-flow.js'
+import { displayUploadResults, performAutoFunding, performUpload, promptDataSetSelection, validatePaymentSetup } from '../common/upload-flow.js'
 import { resolveDataSetIdsByMetadata } from '../core/data-set/index.js'
 import { normalizeMetadataConfig } from '../core/metadata/index.js'
 import { DEFAULT_COPIES } from '../core/synapse/constants.js'
@@ -264,11 +264,9 @@ export async function runCarImport(options: ImportOptions): Promise<ImportResult
           `${pc.green('✓')} Matched existing data sets ${resolution.dataSetIds.join(', ')} via metadata filter`
         )
       } else if (resolution.kind === 'too-many-matches') {
-        spinner.stop(`${pc.red('✗')} --data-set-metadata matched too many data sets`)
-        throw new Error(
-          `--data-set-metadata matched ${resolution.matchedIds.length} data sets (${resolution.matchedIds.join(', ')}) ` +
-            `but expected ${resolution.expected} (narrow the filter or pass --data-set-id to pin the target).`
-        )
+        const chosenIds = await promptDataSetSelection(resolution.matchedDataSets, resolution.expected, spinner)
+        contextSelection.dataSetIds = chosenIds
+        effectiveDataSetMetadata = undefined
       } else if (resolution.kind === 'too-few-matches') {
         spinner.stop(`${pc.red('✗')} --data-set-metadata matched too few data sets`)
         throw new Error(