@frontera-sdk/cli 1.45.6 → 1.45.8

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

@@ -132,7 +132,7 @@ const deploy: Command = {
       )
     }
 
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await client.deploy(slug, {
       manifest,
       bundle,
@@ -173,7 +173,7 @@ const list: Command = {
   },
 
   async run(ctx) {
-    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).list()
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).list()
 
     return {
       data: rows,
@@ -209,7 +209,7 @@ const versions: Command = {
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 
     // Which version is LIVE is on the automation row, not on any version, so
     // it takes a second read. Worth it: "which one is running" is the question
@@ -268,7 +268,7 @@ const promote: Command = {
       )
     }
 
-    const result = await new AutomationApi(ctx.apiUrl, ctx.token).promote(slug, version)
+    const result = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).promote(slug, version)
     return { data: result, text: `Promoted ${slug} to v${result.version}` }
   },
 }
@@ -292,7 +292,7 @@ function enabledCommand(verb: 'enable' | 'disable', summary: string): Command {
 
     async run(ctx) {
       const slug = requireSlug(ctx)
-      const result = await new AutomationApi(ctx.apiUrl, ctx.token).setEnabled(slug, enabled)
+      const result = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).setEnabled(slug, enabled)
       return {
         data: result,
         text: `${enabled ? 'Enabled' : 'Disabled'} ${slug}`,

package/src/commands/automation/pull.ts

@@ -85,7 +85,7 @@ export const automationPull: Command = {
     if (!raw) throw new UsageError('missing <slug>', 'frontera automation pull <slug>[@version]')
     const { slug, version } = parseTarget(raw)
 
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 
     // "Latest" is resolved against the version list rather than by inventing a
     // server endpoint for it — `versions` already exists and is authoritative.

package/src/commands/automation/run.ts

@@ -218,7 +218,7 @@ export const automationRun: Command = {
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // Parsed here rather than passed through as a string: a typo should fail
     // before the registry wait, not after it, and `--version abc` reaching the
     // service as `NaN` would come back as a schema error naming a field the
@@ -364,7 +364,7 @@ export const automationRuns: Command = {
     // where it is explained, so the two belong under one name.
     const runId = ctx.positional[1]
     if (runId) {
-      const api = new AutomationApi(ctx.apiUrl, ctx.token)
+      const api = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
       const [detail, steps] = await Promise.all([
         api.runById(slug, runId),
         // A run that failed before its first step has none, and that is a fact
@@ -393,7 +393,7 @@ export const automationRuns: Command = {
     // without this a dev run is invisible from the CLI — the same blind spot
     // that made `run --dev` wait out its timeout.
     const dev = flagBool(ctx, 'dev')
-    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).runs(
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).runs(
       slug,
       undefined,
       dev ? 'dev' : 'live',

package/src/commands/blueprint/authoring.ts

@@ -79,12 +79,21 @@ function readDocument(ctx: CommandContext, positionalIndex = 0): Record<string,
 const KINDS = ['object-type', 'link-type', 'metric', 'action', 'object-set'] as const
 type Kind = (typeof KINDS)[number]
 
-function readKind(ctx: CommandContext): Kind {
+/**
+ * `create`, `update` and `delete` all start with a kind, so they all land here
+ * — and the hint named `create` for all three. Someone who mistyped
+ * `blueprint update` was sent to a different verb's help, whose shape is not
+ * the one they need: update and delete take an apiName that create does not.
+ *
+ * The caller's own verb is passed in, and the hint is that verb's first
+ * example, which shows every argument rather than only the one that failed.
+ */
+function readKind(ctx: CommandContext, verb: string, example: string): Kind {
   const kind = ctx.positional[0] as Kind
   if (!KINDS.includes(kind)) {
     throw new CliError(
       `Unknown kind "${ctx.positional[0] ?? ''}". Expected one of: ${KINDS.join(', ')}.`,
-      { code: 'USAGE', hint: 'frontera blueprint create --help' },
+      { code: 'USAGE', hint: `${example} — see \`frontera blueprint ${verb} --help\`` },
     )
   }
   return kind
@@ -121,7 +130,7 @@ export const blueprintCreate: Command = {
     ],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'create', 'frontera blueprint create object-type --file customer.json')
     const client = api(ctx)
     const document = readDocument(ctx, 1)
     const revision = await client.revision()
@@ -152,7 +161,7 @@ export const blueprintUpdate: Command = {
     examples: ['frontera blueprint update object-type Customer --file customer.json'],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'update', 'frontera blueprint update object-type Customer --file customer.json')
     const apiName = ctx.positional[1]
     if (!apiName) {
       throw new CliError('An apiName is required.', {
@@ -188,7 +197,7 @@ export const blueprintDelete: Command = {
     examples: ['frontera blueprint delete metric revenuePerCustomer'],
   },
   async run(ctx) {
-    const kind = readKind(ctx)
+    const kind = readKind(ctx, 'delete', 'frontera blueprint delete metric revenuePerCustomer')
     const apiName = ctx.positional[1]
     if (!apiName) {
       throw new CliError('An apiName is required.', {
@@ -238,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/generate-types.ts

@@ -13,6 +13,9 @@ export const blueprintGenerateTypes: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'generate-types',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [],
     flags: { output: 'string', check: 'boolean' },
     summary: 'Generate App-local TypeScript types from this workspace Blueprint',

package/src/commands/blueprint/get.ts

@@ -62,6 +62,9 @@ export const blueprintGet: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'get',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       {
         name: 'apiName',

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/blueprint/list.ts

@@ -21,6 +21,9 @@ export const blueprintList: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'list',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [],
     flags: {},
     summary: 'List the object types this workspace can read',

package/src/commands/blueprint/query.ts

@@ -123,6 +123,9 @@ export const blueprintQuery: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'query',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       {
         name: 'apiName',
@@ -254,6 +257,9 @@ export const blueprintInstance: Command = {
   meta: {
     noun: 'blueprint',
     verb: 'instance',
+    // Reads the slice granted to ONE workspace, unlike the rest of this
+    // noun — see `scope` on CommandMeta.
+    scope: 'workspace' as const,
     args: [
       { name: 'apiName', required: true, description: 'object type, from `frontera blueprint list`' },
       { name: 'pk', required: true, description: 'primary key value of the record to read' },

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/kit/status.ts

@@ -5,6 +5,28 @@ import { checkCompatibility, digest, findDuplicateSources, KIT, LOCK_FILE, readL
 import type { Command } from '../types'
 import { cliVersion, kitRoot } from './shared'
 
+/**
+ * A drift list, counted and capped.
+ *
+ * `modified` was summarised with a count and `missing` was not, so a tree short
+ * of a whole skill printed fifty bare paths under a headline reading
+ * "(current)" — and the two lines that actually needed acting on, the
+ * duplicate-source and compatibility warnings, scrolled off the top.
+ *
+ * Truncation is stated rather than silent, and `--json` still carries every
+ * path, because the full list is what `sync` is judged against.
+ */
+export function driftLines(files: string[], what: string, bullet: string, shown = 8): string[] {
+  if (files.length === 0) return []
+  return [
+    `  ${files.length} generated file(s) ${what}:`,
+    ...files.slice(0, shown).map((f) => `    ${bullet} ${f}`),
+    ...(files.length > shown
+      ? [`    … and ${files.length - shown} more — \`frontera kit status --json\` lists them all`]
+      : []),
+  ]
+}
+
 /**
  * What this repository has, what this CLI carries, and whether they agree.
  *
@@ -73,9 +95,8 @@ export const kitStatus: Command = {
       lines.push(`  bundled kit ${KIT.kitVersion}; run \`frontera kit vendor\` to commit it to this repository`)
     } else {
       lines.push(`kit ${lock.kitVersion} vendored${outdated ? ` — this CLI carries ${KIT.kitVersion}` : ' (current)'}`)
-      if (modified.length > 0) lines.push(`  ${modified.length} generated file(s) edited locally:`)
-      lines.push(...modified.map((f) => `    · ${f}`))
-      if (missing.length > 0) lines.push(...missing.map((f) => `    - ${f} (missing)`))
+      lines.push(...driftLines(modified, 'edited locally', '·'))
+      lines.push(...driftLines(missing, 'missing — run `frontera kit sync`', '-'))
     }
     if (claudeImportsAgents === false) {
       lines.push('  ! CLAUDE.md does not import @AGENTS.md — run `frontera kit vendor` to repair it')

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

@@ -1,9 +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 { renderUploadSummary, summarizeUploads, uploadAll } from './upload-batch'
+import { resolveWorkspaceId } from '../workspace-id'
+import {
+  countExistingSources,
+  describeExistingSources,
+  renderUploadSummary,
+  summarizeUploads,
+  uploadAll,
+} from './upload-batch'
 import { planUploads } from './upload-plan'
 
 interface KnowledgeRow {
@@ -13,24 +22,13 @@ interface KnowledgeRow {
   description?: string
 }
 
-/** The workspace a `sk-ws-` key is scoped to. Not visible from anywhere else. */
-async function requireWorkspaceId(api: PlatformApi): Promise<string> {
-  const me = await api.whoami()
-  if (!me.workspaceId) {
-    throw new CliError('this credential is not scoped to a workspace', {
-      code: 'FORBIDDEN',
-      hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
-    })
-  }
-  return me.workspaceId
-}
 
 /** Accept a base by name or id — `knowledge list` shows both. */
 async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<string> {
   const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
   if (UUID.test(ref)) return ref
 
-  const workspaceId = await requireWorkspaceId(client)
+  const workspaceId = await resolveWorkspaceId(client)
   const rows = (await client.knowledgeBases(workspaceId)) as KnowledgeRow[]
   const match = rows.find((k) => (k.name ?? '').toLowerCase() === ref.toLowerCase())
   if (match?.id) return match.id
@@ -54,7 +52,7 @@ const list: Command = {
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // The route takes the workspace explicitly, and a key holder cannot see
     // its own workspace id from anywhere else — hence /v1/whoami.
-    const workspaceId = await requireWorkspaceId(api)
+    const workspaceId = await resolveWorkspaceId(api)
     const rows = (await api.knowledgeBases(workspaceId)) as KnowledgeRow[]
     return {
       data: rows,
@@ -292,7 +290,7 @@ const create: Command = {
     }
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const workspaceId = await requireWorkspaceId(api)
+    const workspaceId = await resolveWorkspaceId(api)
 
     // Checked here rather than left to the unique constraint: the service
     // answers a duplicate with a bare CONFLICT, whose generic hint ("resolve
@@ -388,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`,
       })
     }