CLI hardening: provider health checks, readable errors, incur 0.4.8 (#22)

* chore(deps): upgrade incur to 0.4.8, drop @remix-run/fs, require node >=22

incur 0.4.x requires Node >=22; also removes the unused @remix-run/fs dependency.

* fix(cli): read version from package.json

The hardcoded version had drifted (0.0.4 vs 0.1.1), so --version reported the wrong number.

* chore: remove dead link helpers from utils

datasetLink, pieceLink, and dealbotLink were unused (flagged by knip); commands use the *ScannerUrl helpers.

* test: extend command mocks and unexport unused fixtures

Add mocks for provider-selection input + fetch health checks, piece hasMore, costs needsFwssMaxApproval, and createDataSet statusUrl (asserting statusUrl is forwarded). Drop the export keyword from fixtures only used in-file (flagged by knip).

* fix(output): render the real error code and message on failure

OutputContext.fail passed a nested { error } object, but incur's c.error reads code/message off the top level, so every failure printed 'code: null, message: null'. Pass them at the top level; incur rebuilds the envelope. (incur's error path has no slot for processLog, so the step trail is surfaced on success only.)

* fix(wallet): drop duplicate monthly rate and report approval need

summary emitted monthlyAccountRate and monthlyStorageRate with identical values; keep a single account rate. costs now surfaces needsFwssMaxApproval so callers can tell 'needs deposit' from 'needs approval only'.

* feat(dataset,piece): paginate piece listings with a next-page CTA

Add --offset/--limit to dataset details and piece list; return hasMore/nextOffset and a CTA with the next-page command when more pieces remain (previously capped silently at 100).

* feat(upload): health-check providers before context selection

The SDK's smartSelect requires an endorsed primary and pings with a 1s budget that excludes healthy-but-slow providers, so uploads failed even when providers were reachable. Pre-select reachable providers ourselves (endorsed first, falling back to a healthy approved provider; reduce copies if fewer are reachable) and pass explicit providerIds, bypassing smartSelect.

* docs(skills): refresh foc-cli and foc-docs skills

Document the pagination flags and needsFwssMaxApproval, replace the stale pricing minimum with the v1 model, sharpen triggering, and clarify the foc-cli vs foc-docs boundary.

* refactor(cli): centralize Synapse construction in synapseClient

Replace the seven duplicated `new Synapse({ client, source })` sites with a single `synapseClient(chainId)` helper returning { client, chain, synapse }. The source tag is resolved in one place — from the config store, defaulting to "foc-cli".

* feat(wallet): set the Synapse source tag via init

Persist `source` in the config store; `wallet init --source <name>` writes it (defaults to "foc-cli"). Document the setting in the README and skill.

* chore(lint): format tests with biome and lint the tests dir

The lint script only formatted src/, so test files drifted from biome's style and CI's `biome check src tests` failed. Format them and add tests/ to the lint script so local matches CI.

Author: nijoe1

README.md

@@ -121,6 +121,14 @@ npx foc-cli docs --url <url>                      # Fetch specific page
 | `--format <fmt>` | `toon` | Output format: `toon`, `json`, `yaml`, `md` |
 | `--json` | | Shorthand for `--format json` |
 
+### Source tag
+
+The `source` string the CLI reports to Synapse/Warm Storage (telemetry & attribution) is stored in your config. Set it to identify your app or integration (defaults to `foc-cli`):
+
+```bash
+npx foc-cli wallet init --source my-app
+```
+
 ## How FOC Works
 
 FOC transforms Filecoin into a **programmable cloud storage layer**:

cli/bun.lock

@@ -21,7 +21,7 @@
     "prepublishOnly": "rm -rf dist && tsc && cp ../README.md ../LICENSE . && cp -r ../skills .",
     "postpublish": "rm -f README.md LICENSE && rm -rf skills",
     "test": "bun test",
-    "lint": "tsc --noEmit && biome check --fix src/"
+    "lint": "tsc --noEmit && biome check --fix src/ tests/"
   },
   "keywords": [
     "filecoin",
@@ -46,15 +46,14 @@
   },
   "homepage": "https://github.com/FIL-Builders/foc-cli#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
     "@filoz/synapse-core": "^0.7.0",
     "@filoz/synapse-sdk": "^1.0.1",
-    "@remix-run/fs": "^0.4.1",
     "conf": "^15.0.2",
-    "incur": "^0.3.1",
+    "incur": "^0.4.8",
     "terminal-link": "^5.0.0",
     "viem": "^2.47.1"
   },

cli/package.json

@@ -13,6 +13,14 @@ export const detailsCommand = {
       .number()
       .default(314159)
       .describe('Chain ID. 314159 = Calibration, 314 = Mainnet'),
+    offset: z.coerce
+      .number()
+      .default(0)
+      .describe('Piece offset to start from (for pagination)'),
+    limit: z.coerce
+      .number()
+      .default(100)
+      .describe('Max pieces per page (defaults to 100)'),
     debug: z.boolean().optional().describe('Enable debug mode'),
   }),
   alias: { chain: 'c', dataSetId: 'd' },
@@ -38,6 +46,8 @@ export const detailsCommand = {
         metadata: z.record(z.string(), z.string()),
       })
     ),
+    hasMore: z.boolean(),
+    nextOffset: z.number().optional(),
   }),
   async run(c: any) {
     const out = new OutputContext(c)
@@ -56,10 +66,15 @@ export const detailsCommand = {
         )
       }
 
+      const offset = c.options.offset ?? 0
+      const limit = c.options.limit ?? 100
+
       out.step('Fetching pieces and metadata')
-      const { pieces } = await getPiecesWithMetadata(client, {
+      const { pieces, hasMore } = await getPiecesWithMetadata(client, {
         dataSet: ds,
         address: client.account.address,
+        offset: BigInt(offset),
+        limit: BigInt(limit),
       })
 
       const dataset = {
@@ -86,11 +101,32 @@ export const detailsCommand = {
         }
       })
 
+      const nextOffset = offset + piecesList.length
+      const nextPage = hasMore
+        ? [
+            {
+              command: 'dataset details',
+              options: {
+                dataSetId: c.options.dataSetId,
+                offset: nextOffset,
+                limit,
+              },
+              description: `Show the next page of pieces (offset ${nextOffset})`,
+            },
+          ]
+        : []
+
       return out.done(
-        { dataset, pieces: piecesList },
+        {
+          dataset,
+          pieces: piecesList,
+          hasMore,
+          ...(hasMore ? { nextOffset } : {}),
+        },
         {
           cta: {
             commands: [
+              ...nextPage,
               {
                 command: 'piece remove',
                 description: 'Remove a piece from this dataset',

cli/src/commands/dataset/details.ts

@@ -1,11 +1,11 @@
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { Synapse } from '@filoz/synapse-sdk'
 import type { StorageContext } from '@filoz/synapse-sdk/storage'
 import { z } from 'incur'
 import type { Hex } from 'viem'
-import { privateKeyClient } from '../client.ts'
 import { OutputContext } from '../output.ts'
+import { selectHealthyProviders } from '../provider-selection.ts'
+import { synapseClient } from '../synapse.ts'
 import {
   datasetScannerUrl,
   hashLink,
@@ -89,7 +89,7 @@ export const multiUploadCommand = {
   ],
   async run(c: any) {
     const out = new OutputContext(c)
-    const { client, chain } = privateKeyClient(c.options.chain)
+    const { client, chain, synapse } = synapseClient(c.options.chain)
 
     try {
       out.step('Reading files')
@@ -132,11 +132,25 @@ export const multiUploadCommand = {
           })
       )
 
-      const synapse = new Synapse({ client, source: 'foc-cli' })
+      out.step('Checking provider health')
+      const selection = await selectHealthyProviders(
+        client,
+        c.options.copies ?? 2
+      )
+      if (selection.usedUnendorsedPrimary) {
+        out.info(
+          `No endorsed provider reachable — using approved provider ${selection.primaryName} for the primary copy.`
+        )
+      }
+      if (selection.reducedCopies) {
+        out.info(
+          `Storing ${selection.selectedCopies} of ${selection.requestedCopies} requested copies (${selection.reachableCount} of ${selection.approvedCount} providers reachable).`
+        )
+      }
 
       out.step('Creating storage contexts')
       const contexts = await synapse.storage.createContexts({
-        copies: c.options.copies,
+        providerIds: selection.providerIds,
         withCDN: c.options.withCDN,
       })
 

cli/src/commands/multi-upload.ts

@@ -15,6 +15,14 @@ export const listCommand = {
       .number()
       .default(314159)
       .describe('Chain ID. 314159 = Calibration, 314 = Mainnet'),
+    offset: z.coerce
+      .number()
+      .default(0)
+      .describe('Piece offset to start from (for pagination)'),
+    limit: z.coerce
+      .number()
+      .default(100)
+      .describe('Max pieces per page (defaults to 100)'),
     debug: z.boolean().optional().describe('Enable debug mode'),
   }),
   alias: { chain: 'c' },
@@ -29,6 +37,8 @@ export const listCommand = {
         metadata: z.record(z.string(), z.string()),
       })
     ),
+    hasMore: z.boolean(),
+    nextOffset: z.number().optional(),
   }),
   examples: [
     { args: { dataSetId: 42 }, description: 'List pieces in dataset #42' },
@@ -45,10 +55,15 @@ export const listCommand = {
       if (!dataSet)
         return out.fail('NOT_FOUND', `Dataset ${c.args.dataSetId} not found`)
 
+      const offset = c.options.offset ?? 0
+      const limit = c.options.limit ?? 100
+
       out.step('Fetching pieces')
-      const { pieces } = await getPiecesWithMetadata(client, {
+      const { pieces, hasMore } = await getPiecesWithMetadata(client, {
         dataSet,
         address: client.account.address,
+        offset: BigInt(offset),
+        limit: BigInt(limit),
       })
 
       const piecesList = pieces.map((piece: any) => {
@@ -61,15 +76,30 @@ export const listCommand = {
         }
       })
 
+      const nextOffset = offset + piecesList.length
+      const nextPage = hasMore
+        ? [
+            {
+              command: 'piece list',
+              args: { dataSetId: c.args.dataSetId },
+              options: { offset: nextOffset, limit },
+              description: `Show the next page of pieces (offset ${nextOffset})`,
+            },
+          ]
+        : []
+
       return out.done(
         {
           dataSetId: c.args.dataSetId.toString(),
           datasetScannerUrl: datasetScannerUrl(c.args.dataSetId, chain),
           pieces: piecesList,
+          hasMore,
+          ...(hasMore ? { nextOffset } : {}),
         },
         {
           cta: {
             commands: [
+              ...nextPage,
               {
                 command: 'piece remove',
                 args: { dataSetId: c.args.dataSetId },

cli/src/commands/piece/list.ts

@@ -1,10 +1,10 @@
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import type { FailedAttempt } from '@filoz/synapse-sdk'
-import { Synapse } from '@filoz/synapse-sdk'
 import { z } from 'incur'
-import { privateKeyClient } from '../client.ts'
 import { OutputContext } from '../output.ts'
+import { selectHealthyProviders } from '../provider-selection.ts'
+import { synapseClient } from '../synapse.ts'
 import { datasetScannerUrl, hashLink, pieceScannerUrl } from '../utils.ts'
 
 export const uploadCommand = {
@@ -75,7 +75,7 @@ export const uploadCommand = {
   ],
   async run(c: any) {
     const out = new OutputContext(c)
-    const { client, chain } = privateKeyClient(c.options.chain)
+    const { client, chain, synapse } = synapseClient(c.options.chain)
 
     try {
       out.step('Reading file')
@@ -88,11 +88,25 @@ export const uploadCommand = {
         },
       })
 
-      const synapse = new Synapse({ client, source: 'foc-cli' })
+      out.step('Checking provider health')
+      const selection = await selectHealthyProviders(
+        client,
+        c.options.copies ?? 2
+      )
+      if (selection.usedUnendorsedPrimary) {
+        out.info(
+          `No endorsed provider reachable — using approved provider ${selection.primaryName} for the primary copy.`
+        )
+      }
+      if (selection.reducedCopies) {
+        out.info(
+          `Storing ${selection.selectedCopies} of ${selection.requestedCopies} requested copies (${selection.reachableCount} of ${selection.approvedCount} providers reachable).`
+        )
+      }
 
       out.step('Creating storage contexts')
       const contexts = await synapse.storage.createContexts({
-        copies: c.options.copies,
+        providerIds: selection.providerIds,
         withCDN: c.options.withCDN,
       })
 

cli/src/commands/upload.ts

@@ -1,8 +1,8 @@
 import { formatBalance } from '@filoz/synapse-core/utils'
-import { Synapse, TOKENS } from '@filoz/synapse-sdk'
+import { TOKENS } from '@filoz/synapse-sdk'
 import { z } from 'incur'
-import { privateKeyClient } from '../../client.ts'
 import { OutputContext } from '../../output.ts'
+import { synapseClient } from '../../synapse.ts'
 
 export const balanceCommand = {
   description: 'Check FIL and USDFC wallet balances and payment account info',
@@ -29,11 +29,11 @@ export const balanceCommand = {
   ],
   async run(c: any) {
     const out = new OutputContext(c)
-    const { client } = privateKeyClient(c.options.chain)
+    const { client, synapse } = synapseClient(c.options.chain)
 
     try {
       out.step('Checking wallet balance')
-      const result = await fetchBalances(client)
+      const result = await fetchBalances(client, synapse)
 
       return out.done(result)
     } catch (error) {
@@ -42,8 +42,7 @@ export const balanceCommand = {
   },
 }
 
-async function fetchBalances(client: any) {
-  const synapse = new Synapse({ client, source: 'foc-cli' })
+async function fetchBalances(client: any, synapse: any) {
   const filBalance = await synapse.payments.walletBalance()
   const usdfcBalance = await synapse.payments.walletBalance({
     token: TOKENS.USDFC,

cli/src/commands/wallet/balance.ts

@@ -1,8 +1,7 @@
 import { formatBalance } from '@filoz/synapse-core/utils'
-import { Synapse } from '@filoz/synapse-sdk'
 import { z } from 'incur'
-import { privateKeyClient } from '../../client.ts'
 import { OutputContext } from '../../output.ts'
+import { synapseClient } from '../../synapse.ts'
 
 export const costsCommand = {
   description: 'Get costs for uploading a file to Filecoin warm storage',
@@ -20,6 +19,7 @@ export const costsCommand = {
     newPerMonthRate: z.string(),
     depositNeeded: z.string(),
     alreadyCovered: z.boolean(),
+    needsFwssMaxApproval: z.boolean(),
   }),
   examples: [
     {
@@ -33,13 +33,11 @@ export const costsCommand = {
   ],
   async run(c: any) {
     const out = new OutputContext(c)
-    const { client } = privateKeyClient(c.options.chain)
+    const { synapse } = synapseClient(c.options.chain)
 
     try {
       out.step('Getting costs')
 
-      const synapse = new Synapse({ client, source: 'foc-cli' })
-
       const prep = await synapse.storage.prepare({
         dataSize: BigInt(c.options.extraBytes),
         extraRunwayEpochs: BigInt(c.options.extraRunway * 30 * 24 * 60 * 2),
@@ -50,8 +48,14 @@ export const costsCommand = {
       })
       const depositNeeded = formatBalance({ value: prep.costs.depositNeeded })
       const alreadyCovered = prep.costs.ready
+      const needsFwssMaxApproval = prep.costs.needsFwssMaxApproval
 
-      return out.done({ newPerMonthRate, depositNeeded, alreadyCovered })
+      return out.done({
+        newPerMonthRate,
+        depositNeeded,
+        alreadyCovered,
+        needsFwssMaxApproval,
+      })
     } catch (error) {
       if (c.options.debug) console.error(error)
       return out.fail('COSTS_FAILED', (error as Error).message)

cli/src/commands/wallet/costs.ts

@@ -1,7 +1,7 @@
-import { parseUnits, Synapse } from '@filoz/synapse-sdk'
+import { parseUnits } from '@filoz/synapse-sdk'
 import { z } from 'incur'
-import { privateKeyClient } from '../../client.ts'
 import { OutputContext } from '../../output.ts'
+import { synapseClient } from '../../synapse.ts'
 import { hashLink, txExplorerUrl } from '../../utils.ts'
 
 export const depositCommand = {
@@ -32,8 +32,7 @@ export const depositCommand = {
   ],
   async run(c: any) {
     const out = new OutputContext(c)
-    const { client, chain } = privateKeyClient(c.options.chain)
-    const synapse = new Synapse({ client, source: 'foc-cli' })
+    const { chain, synapse } = synapseClient(c.options.chain)
 
     try {
       out.step('Depositing funds')