@frontera-sdk/cli 1.45.7 → 1.45.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.45.7",
+  "version": "1.45.8",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,13 +38,13 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.45.2",
-    "@frontera-sdk/core": "1.45.2",
+    "@frontera-sdk/automation": "1.45.7",
+    "@frontera-sdk/core": "1.45.7",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }
 }

package/src/api/blueprint-authoring-api.ts

@@ -1,5 +1,6 @@
 import { CliError } from '../errors'
 import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
 import type { DefinitionBundle } from '../blueprint/model'
 
 /**
@@ -60,7 +61,16 @@ export class BlueprintAuthoringApi {
           hint: 'frontera blueprint status',
         })
       }
-      throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, { code: 'FAILURE', hint: 'frontera blueprint status' })
+      // The service's refusal often carries a TypeBox details array naming the
+      // exact fields — `/pluralName`, a valueType outside the enum — and this
+      // path used to flatten all of it to "Validation failed". On the verb that
+      // WRITES the draft, that reasonless refusal was the whole error a caller
+      // saw, and the audit read it as an unusable write path.
+      const detail = formatValidationDetails(payload?.details)
+      throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, {
+        code: (payload?.code as string) ?? 'FAILURE',
+        hint: detail ?? 'frontera blueprint status',
+      })
     }
 
     return (payload?.data ?? payload) as T
@@ -313,7 +323,15 @@ export class BlueprintAuthoringApi {
 
   // ── release lifecycle ─────────────────────────────────────────────────────
 
-  validate(): Promise<{ id?: string; reportId?: string }> {
+  validate(): Promise<{
+    id?: string
+    reportId?: string
+    draftRevision?: number
+    draftDigest?: string
+    baseReleaseDigest?: string
+    catalogProjection?: { objectTypes?: unknown[]; linkTypes?: unknown[] }
+    evolution?: { changes?: unknown[] }
+  }> {
     return this.call('/v1/blueprint/lifecycle/validate', { method: 'POST', body: {} })
   }
 

package/src/api/dataset-api.ts

@@ -3,6 +3,7 @@ import { basename } from 'node:path'
 
 import { CliError } from '../errors'
 import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
 
 /**
  * Datasets, from the CLI.
@@ -105,9 +106,19 @@ export class DatasetApi {
       // bare "Insufficient permissions" and no route out.
       const credential = credentialFailure(response.status, payload?.message, { token: this.token })
       if (credential) throw credential
+      // `details` is TypeBox's own error array. Stringified it was unreadable,
+      // and this is the last gate before a Source exists.
+      const detail = formatValidationDetails(payload?.details)
       throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
         code: payload?.code ?? 'FAILURE',
-        ...(payload?.details ? { hint: JSON.stringify(payload.details) } : {}),
+        // A refused CONNECTION is not a malformed document, and telling someone
+        // to re-read their file sends them to the wrong place entirely: the
+        // service dials the database itself, from wherever it runs.
+        hint: detail
+          ?? (response.status === 409
+            ? 'the service dials the database itself — check host and port are reachable '
+              + 'from where the service runs, and that the password on stdin is current'
+            : 'check the document against `frontera source create --help`'),
       })
     }
     return (payload?.data ?? payload) as T
@@ -288,6 +299,28 @@ export class DatasetApi {
     return this.call<DatasetSummary>('/v1/data-integration/datasets/from-file', { form })
   }
 
+  /**
+   * Rows into a dataset that already exists, as a new snapshot.
+   *
+   * `createFromFile` is CREATE-time only. A blank dataset — declared columns,
+   * no rows, and the common first step — had no way to receive data afterwards
+   * through the CLI, so an agent told its user the capability did not exist.
+   * It does: the service republishes against the CURRENT column contract and
+   * repoints the dataset atomically, keeping the prior snapshot on any failure.
+   *
+   * The file must match that contract exactly — names, types, nullability. A
+   * schema change is refused here by design; it is a new revision, not a
+   * re-upload.
+   */
+  uploadSnapshot(datasetId: string, path: string): Promise<DatasetSummary> {
+    const form = new FormData()
+    form.append('file', new Blob([readFileSync(path)]), basename(path))
+    return this.call<DatasetSummary>(
+      `/v1/data-integration/datasets/${encodeURIComponent(datasetId)}/snapshots`,
+      { form },
+    )
+  }
+
   createBlank(payload: {
     apiName: string
     displayName: string

package/src/api/validation-detail.ts

@@ -0,0 +1,87 @@
+/**
+ * Turn the service's validation `details` into something a person can act on.
+ *
+ * The service answers a rejected document with TypeBox's own error array, and
+ * the CLI put it on screen with `JSON.stringify`:
+ *
+ *   [{"summary":"Expected 'virtual'","type":32,"schema":{"const":"virtual",
+ *   "type":"string"},"path":"/datasets/0/mode","message":"Expected 'virtual'",
+ *   "errors":[]}]
+ *
+ * Every fact a caller needs is in there, and none of it is legible. The path is
+ * buried mid-line, the schema fragment is noise, and `type: 32` is an internal
+ * enum. `source create` was unusable through this: it is the last gate before a
+ * Source exists, and it answered with a machine's notes.
+ */
+
+interface TypeBoxError {
+  path?: string
+  message?: string
+  summary?: string
+  value?: unknown
+}
+
+/** `/datasets/0/mode` reads better as `datasets[0].mode`. */
+export function readablePath(path: string | undefined): string {
+  if (!path || path === '/') return '(document root)'
+  return path
+    .replace(/^\//, '')
+    .split('/')
+    .map((segment) => (/^\d+$/.test(segment) ? `[${segment}]` : `.${segment}`))
+    .join('')
+    .replace(/^\./, '')
+    .replace(/\.\[/g, '[')
+}
+
+/**
+ * Whether these errors all point at a discriminator.
+ *
+ * A discriminated union reports the field it switches on when ANY branch fails,
+ * so `mode: "virtual"` is rejected with "Expected 'virtual'" while the real
+ * defect is somewhere else in that branch entirely. Silently correct and
+ * completely misleading, and it cost an audit an afternoon — so when the shape
+ * matches, the hint says so rather than letting the caller stare at a field
+ * that is already right.
+ */
+export function looksLikeDiscriminator(errors: TypeBoxError[]): boolean {
+  return (
+    errors.length > 0
+    && errors.every((e) => /^Expected '.*'$/.test(e.message ?? e.summary ?? ''))
+  )
+}
+
+/**
+ * One line per error, plus a note when the paths cannot be trusted.
+ *
+ * Returns `undefined` when there is nothing structured to say, so the caller
+ * keeps whatever hint it already had rather than showing an empty one.
+ */
+export function formatValidationDetails(details: unknown): string | undefined {
+  const errors = Array.isArray(details) ? (details as TypeBoxError[]) : null
+  if (!errors || errors.length === 0) return undefined
+
+  const lines = errors
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => {
+      const message = e.message ?? e.summary ?? 'is not valid'
+      return `${readablePath(e.path)} — ${message}`
+    })
+  if (lines.length === 0) return undefined
+
+  // Capped: a document with fifty problems produces fifty lines, and the first
+  // few are the ones anybody reads. The count says what was left out rather
+  // than letting the list end without saying so.
+  const SHOWN = 5
+  const shown = lines.slice(0, SHOWN)
+  if (lines.length > SHOWN) shown.push(`… and ${lines.length - SHOWN} more`)
+
+  if (looksLikeDiscriminator(errors)) {
+    shown.push(
+      'that field may already be correct — a discriminated union reports the '
+      + 'field it switches on when any part of that branch fails, so look at '
+      + 'the rest of the same object',
+    )
+  }
+
+  return shown.join('\n  ')
+}

package/src/commands/agent/index-commands.ts

@@ -368,13 +368,26 @@ const diff: Command = {
   },
   async run(ctx) {
     const t = await target(ctx, 'diff')
-    const draft = await t.api.agentDraft(t.id)
+    // Both, before either branch answers: "the live version is current" is as
+    // wrong for an agent that has never published as "matches the live
+    // version" is, and that branch used to answer without ever looking.
+    const [draft, live] = await Promise.all([
+      t.api.agentDraft(t.id),
+      t.api.agent(t.id) as Promise<Record<string, unknown>>,
+    ])
+    const published = Boolean(live.currentVersion ?? live.currentVersionId)
 
     if (!draft) {
-      return { data: { hasDraft: false, changed: [] }, text: 'No draft staged — the live version is current.' }
+      return {
+        data: { hasDraft: false, published, changed: [] },
+        text: published
+          ? 'No draft staged — the live version is current.'
+          : 'No draft staged, and nothing is published — this agent has no configuration '
+            + 'of its own yet.\n'
+            + `  Stage one with \`frontera agent apply ${t.ref} --file <path>\`.`,
+      }
     }
 
-    const live = (await t.api.agent(t.id)) as Record<string, unknown>
     const liveConfig = (live.config ?? live) as Record<string, unknown>
     const draftConfig = (draft.snapshot.config ?? {}) as Record<string, unknown>
 
@@ -421,11 +434,15 @@ const diff: Command = {
     ].sort()
 
     return {
-      data: { hasDraft: true, revision: draft.revision, changed },
+      data: { hasDraft: true, revision: draft.revision, published, changed },
       text:
-        changed.length === 0
-          ? `Draft revision ${draft.revision} matches the live version.`
-          : [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n'),
+        changed.length > 0
+          ? [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n')
+          : published
+            ? `Draft revision ${draft.revision} matches the live version.`
+            : `Draft revision ${draft.revision}. Nothing is published yet, so there is `
+              + 'nothing to compare against — the draft IS the whole configuration.\n'
+              + `  Publish it with \`frontera agent publish ${t.ref}\`.`,
     }
   },
 }

package/src/commands/blueprint/authoring.ts

@@ -247,16 +247,46 @@ export const blueprintValidate: Command = {
   },
   async run(ctx) {
     const report = await api(ctx).validate()
-    const id = report?.id ?? report?.reportId
-    return {
-      data: report,
-      // The id matters: `publish` takes it, which is what ties a release to the
-      // validation that cleared it rather than to whatever the draft holds later.
-      text: `Draft validated. Report ${id} — pass it to \`frontera blueprint publish\`.`,
-    }
+    return { data: report, text: renderValidationReport(report) }
   },
 }
 
+type ValidationReport = Awaited<ReturnType<BlueprintAuthoringApi['validate']>>
+
+/**
+ * Say WHAT passed, not only that something did.
+ *
+ * This validates the SERVER draft. `plan` and `apply` read the file tree, and
+ * an audit ran the three as one pipeline: plan said "+1 object type", validate
+ * said "Draft validated", apply refused — validate had passed the still-empty
+ * server draft, and its bare success line was the false confidence in the
+ * middle. The counts make emptiness visible, and the unchanged-draft case
+ * names the verb that moves files into it.
+ *
+ * The report id stays on the page: `publish` takes it, which is what ties a
+ * release to the validation that cleared it rather than to whatever the draft
+ * holds later.
+ */
+export function renderValidationReport(report: ValidationReport): string {
+  const id = report?.id ?? report?.reportId
+  const objectTypes = report?.catalogProjection?.objectTypes?.length ?? 0
+  const linkTypes = report?.catalogProjection?.linkTypes?.length ?? 0
+  const unchanged = Boolean(
+    report?.draftDigest && report.draftDigest === report.baseReleaseDigest,
+  )
+
+  const what = `Draft revision ${report?.draftRevision ?? '?'} validated — `
+    + `${objectTypes} object type${objectTypes === 1 ? '' : 's'}, `
+    + `${linkTypes} link type${linkTypes === 1 ? '' : 's'}`
+    + (unchanged ? ', unchanged since the base release' : '')
+  const note = unchanged
+    ? '\n  This checks the draft on the SERVER. Local files are not part of it until '
+      + '`frontera blueprint apply` moves them there.'
+    : ''
+
+  return `${what}.${note}\n  Report ${id} — pass it to \`frontera blueprint publish\`.`
+}
+
 export const blueprintPublish: Command = {
   meta: {
     noun: 'blueprint',

package/src/commands/blueprint/declarative.ts

@@ -1108,9 +1108,15 @@ export const blueprintApply: Command = {
       const done = applied.length
         ? `Applied before failing:\n${applied.map((line) => `  ${line}`).join('\n')}\n`
         : 'Nothing was applied.\n'
+      // The inner error's hint survives: it names the fields the service
+      // refused. Replacing it with "re-plan" was advice for a DIFFERENT
+      // failure — a draft that moved — handed out for every failure, so a
+      // validation refusal read as "Validation failed / re-plan", which no
+      // amount of re-planning fixes.
+      const inner = err instanceof CliError ? err.hint : undefined
       throw new CliError(`${done}${(err as Error).message}`, {
         code: err instanceof CliError ? err.code : 'FAILURE',
-        hint: 'frontera blueprint plan — re-plan against the current draft, then re-apply.',
+        hint: inner ?? 'frontera blueprint plan — re-plan against the current draft, then re-apply.',
       })
     }
 

package/src/commands/blueprint/grants.ts

@@ -148,11 +148,38 @@ export const blueprintGrant: Command = {
     const resolved = await resolveSubject(client, subject, name)
     const revoke = ctx.flags.revoke === true
     for (const apiName of apiNames) {
-      if (subject === 'workspace') {
-        if (revoke) await client.revokeWorkspace(resolved.id, apiName)
-        else await client.grantWorkspace(resolved.id, apiName)
-      } else if (revoke) await client.revokeAgent(resolved.id, apiName)
-      else await client.grantAgent(resolved.id, apiName)
+      try {
+        if (subject === 'workspace') {
+          if (revoke) await client.revokeWorkspace(resolved.id, apiName)
+          else await client.grantWorkspace(resolved.id, apiName)
+        } else if (revoke) await client.revokeAgent(resolved.id, apiName)
+        else await client.grantAgent(resolved.id, apiName)
+      } catch (err) {
+        /**
+         * Grants address the PUBLISHED catalog, and the draft is a different
+         * store — the runtime catalog materializes at release. So an object
+         * type that was just applied answers "not found" here, from the verb a
+         * caller reaches for immediately after `apply` succeeds.
+         *
+         * "Not found" is true of the catalog and a lie about the work: the
+         * type exists, one step from here. When the draft holds the name, say
+         * which step — a comprehension audit read the bare 404 as the whole
+         * pipeline being broken.
+         */
+        const notFound = err instanceof CliError && err.code === 'NOT_FOUND'
+        if (!notFound) throw err
+        const onDraft = await client.getObjectType(apiName).then((t) => Boolean(t?.id)).catch(() => false)
+        if (!onDraft) throw err
+        throw new CliError(
+          `"${apiName}" is on the draft but not in any release yet.`,
+          {
+            code: 'NOT_FOUND',
+            hint: 'grants and queries read the published catalog — publishing is what '
+              + 'materializes the draft into it. Ask for a release, then re-run: '
+              + '`frontera blueprint publish` needs an explicit go-ahead.',
+          },
+        )
+      }
     }
 
     return {

package/src/commands/dataset/index-commands.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { basename, dirname, resolve } from 'node:path'
 
 import { DatasetApi, type DatasetColumn } from '../../api/dataset-api'
 import { CliError } from '../../errors'
@@ -204,7 +204,8 @@ const rows: Command = {
         text:
           `No rows in the current revision of "${apiName}".\n`
           + '  The column contract is published, so anything bound to it will bind and read nothing.\n'
-          + `  \`frontera dataset get ${apiName}\` shows the contract.`,
+          + `  \`frontera dataset upload ${apiName} ./rows.csv\` loads rows that match the contract; `
+          + `\`frontera dataset get ${apiName}\` shows it.`,
       }
     }
 
@@ -386,8 +387,14 @@ const create: Command = {
     flags: { file: 'string' },
     aliases: { f: 'file' },
     summary: 'Create a dataset — from declared columns, a Source relation, or a CSV',
+    // One example per kind, because the summary promises three forms and a
+    // single JSON example taught callers that the third did not exist: an
+    // agent given only this surface concluded "rows can never be loaded from
+    // a CSV through the CLI" while `kind: "file"` sat unadvertised.
     examples: [
       'frontera dataset create --file ./customers.json',
+      'frontera dataset create --file ./orders.json  # kind:"file" ingests a CSV',
+      'frontera dataset create --file ./stock.json   # kind:"source" pulls a relation',
     ],
   },
   async run(ctx) {
@@ -399,7 +406,22 @@ const create: Command = {
       })
     }
     const path = resolve(ctx.cwd, filePath)
-    const document = JSON.parse(readFileSync(path, 'utf8')) as DatasetFile
+    let document: DatasetFile
+    try {
+      document = JSON.parse(readFileSync(path, 'utf8')) as DatasetFile
+    } catch (e) {
+      // The likeliest way to get here is handing over the CSV itself — the
+      // summary says "from … a CSV" and this is the only flag. That used to be
+      // a raw parser crash: `INTERNAL_ERROR: JSON Parse error: Unexpected
+      // identifier "id"`, exit 1, naming the first CSV header as the fault.
+      throw new CliError(`${filePath} is not a JSON definition: ${(e as Error).message}`, {
+        code: 'USAGE',
+        hint: filePath.toLowerCase().endsWith('.csv')
+          ? '--file takes the definition document, not the CSV. To ingest a CSV, the document '
+            + 'names it: { "apiName": "…", "kind": "file", "path": "./' + basename(filePath) + '" }'
+          : 'the document is JSON: { apiName, kind: blank | source | file, … } — see `frontera dataset create --help`',
+      })
+    }
 
     const apiName = document.apiName
     if (typeof apiName !== 'string' || !apiName) {
@@ -437,7 +459,56 @@ const create: Command = {
     }
 
     const api = new DatasetApi(ctx.apiUrl, ctx.token)
+
+    /**
+     * `kind` defaults to blank, and blank reads NOTHING — so a document that
+     * carried `source` or `path` without saying `kind` was created as an empty
+     * schema, its row-bearing keys silently dropped. "Created" was the whole
+     * answer, and the caller found the zero rows later, somewhere else.
+     *
+     * The default stays, because a plain columns document is the common case
+     * and has always worked. What goes is the silence: keys that only mean
+     * something under another kind refuse rather than vanish.
+     */
+    const doc = document as Record<string, unknown>
     const kind = document.kind ?? 'blank'
+
+    const KIND_KEYS: Record<string, Set<string>> = {
+      blank: new Set(['columns']),
+      source: new Set(['source', 'schema', 'relation', 'includedColumns']),
+      file: new Set(['path', 'includedColumns']),
+    }
+    const COMMON = new Set([
+      'apiName', 'displayName', 'description', 'kind', 'keyColumns', 'deterministicKeyConfirmed',
+    ])
+    // Where a stray key probably meant to point. `csv`, `rows` and `data` are
+    // what people actually reached for when probing how rows get in.
+    const MEANT: Record<string, string> = {
+      csv: 'kind: "file" with `path`',
+      rows: 'kind: "file" with `path` (rows ride in the CSV)',
+      data: 'kind: "file" with `path`',
+      source: 'kind: "source"',
+      path: 'kind: "file"',
+      schema: 'kind: "source"',
+      relation: 'kind: "source"',
+    }
+
+    const allowed = KIND_KEYS[kind as string] ?? new Set<string>()
+    const strays = Object.keys(doc).filter((k) => !COMMON.has(k) && !allowed.has(k))
+    if (strays.length > 0) {
+      const guesses = strays
+        .map((k) => (MEANT[k] && !allowed.has(k) ? `\`${k}\` belongs to ${MEANT[k]}` : null))
+        .filter(Boolean)
+      const named = strays.map((k) => '`' + k + '`').join(', ')
+      const strayHint = guesses.length > 0
+        ? `${guesses.join('; ')} — say the kind explicitly, it does not default from the keys`
+        : `kind "${kind}" reads: ${[...COMMON, ...allowed].join(', ')}`
+      throw new CliError(`${filePath} carries ${named}, which kind "${kind}" does not read.`, {
+        code: 'USAGE',
+        hint: strayHint,
+      })
+    }
+
     let created
 
     if (kind === 'blank') {
@@ -511,10 +582,86 @@ const create: Command = {
 
     return {
       data: created,
-      text: `Created dataset "${apiName}". `
+      // Blank is a CONTRACT with no rows, and that surprised everyone who
+      // reached it by default. Said here, at creation, rather than left for
+      // `dataset rows` to reveal after the binding is already built.
+      text: `Created dataset "${apiName}"${kind === 'blank'
+        ? ` — declared columns only, no rows. Load them with \`frontera dataset upload ${apiName} ./rows.csv\`,`
+          + ' or create with kind "file" (a CSV) or kind "source" instead.'
+        : '.'} `
         + `Bind an object type to it: frontera blueprint bind <ObjectType> --dataset ${apiName} --plan ./map.json`,
     }
   },
 }
 
-export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create]
+const upload: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'upload',
+    args: [
+      { name: 'apiName', required: true, description: 'The dataset’s API name, from `frontera dataset list`' },
+      { name: 'path', required: true, description: 'Path to a CSV matching the dataset’s column contract' },
+    ],
+    flags: {},
+    summary: 'Load rows from a CSV into an existing dataset, as a new snapshot',
+    examples: [
+      'frontera dataset upload customers ./customers.csv',
+      'frontera dataset preview ./customers.csv   # check the columns first',
+    ],
+  },
+  /**
+   * Rows into a dataset that already exists.
+   *
+   * `create` with kind "file" loads a CSV at creation, and nothing loaded one
+   * afterwards. A blank dataset — declared columns, no rows — is the common
+   * first step, and the moment someone had one and a CSV to put in it, the
+   * CLI had no verb. An agent told its user the capability did not exist;
+   * the service had it all along.
+   *
+   * The file must match the CURRENT contract exactly: names, types,
+   * nullability. That is the service's rule, and a sound one — a re-upload
+   * that changed the schema would silently alter what every binding reads.
+   * A schema change is a new revision, not this verb.
+   */
+  async run(ctx) {
+    const [apiName, path] = ctx.positional
+    if (!apiName) {
+      throw new CliError('A dataset apiName is required.', { code: 'USAGE', hint: 'frontera dataset list' })
+    }
+    if (!path) {
+      throw new CliError('A path to a CSV is required.', {
+        code: 'USAGE',
+        hint: `frontera dataset upload ${apiName} ./rows.csv`,
+      })
+    }
+
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const dataset = await resolveDataset(api, apiName)
+
+    let result
+    try {
+      result = await api.uploadSnapshot(dataset.id!, resolve(ctx.cwd, path))
+    } catch (err) {
+      // The service's refusal says WHAT is wrong (contract mismatch) and the
+      // caller needs to see WHERE: the dataset's contract on one side and the
+      // file's columns on the other. Both are one command away.
+      const mismatch = err instanceof CliError && err.code === 'CONFLICT'
+      if (!mismatch) throw err
+      throw new CliError((err as Error).message, {
+        code: 'CONFLICT',
+        hint: `compare \`frontera dataset get ${apiName}\` (the contract) with `
+          + `\`frontera dataset preview ${path}\` (the file) — names, types and nullability must all match. `
+          + 'A schema change is a new revision, not an upload.',
+      })
+    }
+
+    const revision = (result as { currentRevision?: { revision?: number } }).currentRevision?.revision
+    return {
+      data: result,
+      text: `Loaded ${basename(path)} into "${apiName}"${revision !== undefined ? ` — now at revision ${revision}` : ''}.\n`
+        + `  \`frontera dataset rows ${apiName}\` reads them back.`,
+    }
+  },
+}
+
+export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create, upload]

package/src/commands/knowledge/index-commands.ts

@@ -1,10 +1,18 @@
+import { basename } from 'node:path'
+
 import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
 import { resolveAgentRef } from '../agent/resolve'
 import { flagString, type Command } from '../types'
 import { resolveWorkspaceId } from '../workspace-id'
-import { renderUploadSummary, summarizeUploads, uploadAll } from './upload-batch'
+import {
+  countExistingSources,
+  describeExistingSources,
+  renderUploadSummary,
+  summarizeUploads,
+  uploadAll,
+} from './upload-batch'
 import { planUploads } from './upload-plan'
 
 interface KnowledgeRow {
@@ -378,9 +386,20 @@ const upload: Command = {
     // code says so, and name the first cause rather than a count.
     if (summary.uploaded === 0) {
       const first = outcomes.find((o) => o.status === 'failed')
+
+      // The hint used to promise that "a retry duplicates nothing already
+      // ingested". It is not true: the service registers the source and then
+      // fails downstream, so the row exists and re-running adds another. Rather
+      // than soften the claim, look.
+      const existing = describeExistingSources(
+        await countExistingSources(api, baseId, plan.files.map((f) => basename(f.path))),
+      )
+
       throw new CliError(`all ${summary.failed} upload(s) failed: ${first?.error ?? 'unknown error'}`, {
         code: 'FAILURE',
-        hint: 'fix the cause above and re-run — uploading is additive, so a retry duplicates nothing already ingested',
+        hint: existing
+          ? `${existing}. Check \`frontera knowledge sources ${ref}\` before re-running`
+          : `fix the cause above, then re-run — nothing was registered, so \`frontera knowledge sources ${ref}\` should still be empty for this file`,
       })
     }