@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/blueprint/query.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs'
 
 import { PlatformApi } from '../../api/platform-api'
+import { resolveObjectSetReferences, type SavedObjectSet } from '../../blueprint/object-sets'
 import { CliError, UsageError } from '../../errors'
+import { isUuid } from '../../local/local-sync-refs'
+import { resolveObjectSet, savedObjectSets } from './object-sets'
 import { table } from '../../table'
-import { flagString, type Command } from '../types'
+import { flagBool, flagString, flagStrings, type Command } from '../types'
 
 /**
  * Read rows through the ontology.
@@ -23,11 +26,61 @@ function api(ctx: { apiUrl: string; token: string; workspaceId?: string }): Plat
   return new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
 }
 
-/** `status:open` and `amount:>:1000` — the two forms worth typing by hand. */
+/** The operators the shorthand names, so `url:https://…` reads as an equality on `url`, not as operator `https`. */
+const WHERE_OPS = new Set(['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'contains', 'startsWith', 'isNull', 'isNotNull'])
+/** Spellings a person types: `not_in` for `notIn`, `>` for `gt`. */
+const OP_ALIASES: Record<string, string> = {
+  not_in: 'notIn', notin: 'notIn', nin: 'notIn',
+  '=': 'eq', '!=': 'ne', '>': 'gt', '>=': 'gte', '<': 'lt', '<=': 'lte',
+}
+/** Operators whose value is a list: `state:in:new,assigned`, `amount:between:10,20`. */
+const LIST_OPS = new Set(['in', 'notIn', 'between'])
+
+/**
+ * A comma list, as `in`, `notIn` and `between` take one: `new,assigned`.
+ * `\,` is a comma inside a value and `\\` a backslash; a value that starts
+ * with `[` is read as a JSON array instead (`["Smith, J", "Lee"]`), which also
+ * keeps numbers and `null` as written.
+ */
+export function parseWhereList(raw: string, op: string): unknown[] {
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('[')) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch (e) {
+      throw new UsageError(`the "${op}" list is not valid JSON: ${(e as Error).message}`, 'write it as a JSON array, like ["new","assigned"], or as new,assigned')
+    }
+    if (!Array.isArray(parsed)) throw new UsageError(`the "${op}" list is not a JSON array`, 'write it as ["new","assigned"]')
+    return parsed
+  }
+  const values: string[] = []
+  let current = ''
+  for (let i = 0; i < raw.length; i += 1) {
+    const ch = raw[i]!
+    if (ch === '\\' && i + 1 < raw.length) {
+      current += raw[i + 1]
+      i += 1
+    } else if (ch === ',') {
+      values.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  values.push(current)
+  return values.map((v) => v.trim()).filter((v) => v !== '')
+}
+
+/**
+ * `status:open`, `amount:gt:1000` and `state:in:new,assigned` — the forms worth
+ * typing by hand. The value is everything after the operator, so a time
+ * (`openedAt:gt:2026-10-01T09:00:00Z`) or a URL keeps its colons.
+ */
 export function parseWhere(raw: string): unknown {
   const trimmed = raw.trim()
   // A JSON object is passed through untouched: the shorthand covers one
-  // condition, and anything with an `and`/`or` in it needs the real grammar
+  // condition, and anything with an `or` in it needs the real grammar
   // rather than a punctuation language invented here to avoid it.
   if (trimmed.startsWith('{')) {
     try {
@@ -41,17 +94,54 @@ export function parseWhere(raw: string): unknown {
     }
   }
 
-  const parts = trimmed.split(':')
-  if (parts.length === 2) {
-    return { property: parts[0], op: 'eq', value: parts[1] }
+  const first = trimmed.indexOf(':')
+  const property = first === -1 ? '' : trimmed.slice(0, first)
+  if (!property) {
+    throw new UsageError(
+      `cannot read --where "${raw}"`,
+      'use <property>:<value>, <property>:<op>:<value>, <property>:in:<a>,<b>, or a JSON where-node',
+    )
+  }
+  const rest = trimmed.slice(first + 1)
+  const second = rest.indexOf(':')
+  const named = second === -1 ? rest : rest.slice(0, second)
+  const op = OP_ALIASES[named.toLowerCase()] ?? named
+  if (!WHERE_OPS.has(op)) {
+    // A word between two colons is an operator, and a misspelt one must not
+    // turn into an equality that quietly matches nothing.
+    if (second !== -1 && /^(?:[A-Za-z_]+|[<>=!]+)$/.test(named)) {
+      throw new UsageError(
+        `--where "${raw}": unknown operator "${named}"`,
+        `use one of ${[...WHERE_OPS].join(', ')}; for a value with a colon in it, write ${property}:eq:<value>`,
+      )
+    }
+    // No operator: the whole rest is the value of an equality (`openedAt:2026-10-01T09:00:00Z`).
+    return { property, op: 'eq', value: rest }
+  }
+  if (op === 'isNull' || op === 'isNotNull') {
+    if (second !== -1 && rest.slice(second + 1).trim() !== '') throw new UsageError(`"${op}" takes no value`, `use ${property}:${op}`)
+    return { property, op }
   }
-  if (parts.length === 3) {
-    return { property: parts[0], op: parts[1], value: parts[2] }
+  if (second === -1) {
+    // `status:in` — the operator word with nothing after it reads as the value "in"
+    // of an equality, which is what it said before operators were recognised.
+    return { property, op: 'eq', value: rest }
   }
-  throw new UsageError(
-    `cannot read --where "${raw}"`,
-    'use <property>:<value>, <property>:<op>:<value>, or a JSON where-node',
-  )
+  const value = rest.slice(second + 1)
+  if (LIST_OPS.has(op)) {
+    const values = parseWhereList(value, op)
+    if (values.length === 0) throw new UsageError(`"${op}" on "${property}" names no values`, `use ${property}:${op}:<a>,<b>`)
+    if (op === 'between' && values.length !== 2) throw new UsageError(`"between" on "${property}" takes two values, a low and a high`, `use ${property}:between:<low>,<high>`)
+    return { property, op, values }
+  }
+  return { property, op, value }
+}
+
+/** Several `--where` flags are all true at once: one condition each, ANDed. */
+export function parseWheres(raws: readonly string[]): unknown {
+  const nodes = raws.map(parseWhere)
+  if (nodes.length === 0) return null
+  return nodes.length === 1 ? nodes[0] : { and: nodes }
 }
 
 export function parseOrder(raw: string): Array<{ property: string; dir: 'asc' | 'desc' }> {
@@ -94,12 +184,16 @@ export function coerceWhereValue(value: unknown, dataType: string | undefined):
   return value
 }
 
-/** `{ property, op, value }` from the shorthand, retyped against the ontology. */
+/** `{ property, op, value }` (or `values`) from the shorthand, retyped against the ontology; `and` of them too. */
 export function typeWhereNode(node: unknown, types: Map<string, string>): unknown {
-  const condition = node as { property?: string; value?: unknown }
+  const and = (node as { and?: unknown })?.and
+  if (Array.isArray(and)) return { and: and.map((n) => typeWhereNode(n, types)) }
+  const condition = node as { property?: string; value?: unknown; values?: unknown }
   if (!condition || typeof condition !== 'object' || typeof condition.property !== 'string') return node
+  const dataType = types.get(condition.property)
+  if (Array.isArray(condition.values)) return { ...condition, values: condition.values.map((v) => coerceWhereValue(v, dataType)) }
   if (!('value' in condition)) return node
-  return { ...condition, value: coerceWhereValue(condition.value, types.get(condition.property)) }
+  return { ...condition, value: coerceWhereValue(condition.value, dataType) }
 }
 
 export function parseLimit(raw: string): number {
@@ -140,25 +234,47 @@ export const blueprintQuery: Command = {
       limit: 'string',
       'page-token': 'string',
       file: 'string',
+      'object-set': 'string',
     },
     aliases: { f: 'file' },
-    summary: 'Read rows of an object type through the ontology',
+    summary: 'Read rows of an object type, or of a saved object set, through the ontology',
+    details: [
+      '`--object-set` reads a saved object set\'s rows instead of a whole object type: name it by its name (`"Open work orders"`), the reference a file names it by (`objectSet/open-work-orders`) or its id, from `frontera blueprint object-sets`. `--where` then narrows the set.',
+      'In a `--file` query, a `{ "type": "reference", "objectSetId": … }` may name the set the same ways; the name is read as its id before the query is sent.',
+      '`--where` takes `<property>:<value>` (equality), `<property>:<op>:<value>` with op one of eq, ne, gt, gte, lt, lte, contains, startsWith, or `<property>:isNull` / `<property>:isNotNull`. `in`, `notIn` and `between` take a comma list: `--where state:in:new,assigned`, `--where amount:between:10,20`. Write `\\,` for a comma inside a value, or give the list as a JSON array: `--where \'owner:in:["Smith, J","Lee"]\'`. Repeat `--where` for conditions that must all hold; pass a JSON where-node for an `or` or a `not`.',
+      'On a date or time property, a value can be the time the query runs: `$now`, or `$now` plus or minus an amount in m (or min), h, d or w: `--where \'dueAt:lt:$now\'` (overdue), `--where \'createdAt:gt:$now-7d\'` (the last week). Quote it, so the shell leaves `$now` alone; a `--file` query takes the same value.',
+    ],
     examples: [
       'frontera blueprint query Invoice --limit 5',
+      'frontera blueprint query --object-set "Open work orders" --limit 10',
+      'frontera blueprint query --object-set objectSet/open-orders --where tier:gold',
       'frontera blueprint query Invoice --where status:open --select id,amount',
       'frontera blueprint query Invoice --order amount:desc --limit 20',
+      "frontera blueprint query WorkOrder --where 'dueAt:lt:$now'",
+      'frontera blueprint query WorkOrder --where state:in:new,assigned',
       'frontera blueprint query --file ./query.json --json',
     ],
   },
 
   async run(ctx) {
-    const apiName = ctx.positional[0]
     const file = flagString(ctx, 'file')
+    const setFlag = flagString(ctx, 'object-set')
+    if (setFlag !== undefined && !setFlag.trim()) throw new UsageError('--object-set names no set', 'frontera blueprint object-sets — then pass a name, reference or id')
+    if (setFlag && file) throw new UsageError('--object-set and --file both say what to read', 'put the set in the file as { "type": "reference", "objectSetId": "<name or id>" }, or drop --file')
+    // The sets, read once, when a name has to become an id.
+    let listed: SavedObjectSet[] | undefined
+    const sets = async () => (listed ??= await savedObjectSets(ctx))
+    const set = setFlag ? await resolveObjectSet(ctx, setFlag, await sets()) : null
+    if (set && ctx.positional[0] && set.objectType && !isUuid(set.objectType) && ctx.positional[0] !== set.objectType) {
+      throw new UsageError(`${set.name} is a set of ${set.objectType}, not ${ctx.positional[0]}`, `drop <apiName>, or pass ${set.objectType}`)
+    }
+    // A set's object type is what its rows are: the shorthand's values are typed against it.
+    const apiName = ctx.positional[0] ?? (set && !isUuid(set.objectType) ? set.objectType : undefined)
 
-    if (!apiName && !file) {
+    if (!apiName && !file && !set) {
       throw new UsageError(
         'missing <apiName>',
-        'frontera blueprint list — then `frontera blueprint query <apiName>`',
+        'frontera blueprint list — then `frontera blueprint query <apiName>`; or `frontera blueprint object-sets`, then `--object-set <name>`',
       )
     }
 
@@ -184,17 +300,19 @@ export const blueprintQuery: Command = {
           'the minimum is { "objectSet": { "type": "base", "objectType": "Invoice" } }',
         )
       }
-      body = doc as typeof body
+      // A set named in words (`objectSet/open-work-orders`, `Open work orders`) is sent as its id.
+      body = (await resolveObjectSetReferences(doc, async (name) => (await resolveObjectSet(ctx, name, await sets())).id)) as typeof body
     } else {
-      const where = flagString(ctx, 'where')
-      let node = where ? parseWhere(where) : null
+      // Every `--where` holds: repeated, they are ANDed (the last one alone used to win, silently).
+      const wheres = flagStrings(ctx, 'where')
+      let node = parseWheres(wheres)
 
       // One extra read, and only when the shorthand is used: the flag carries
       // a string and the compiler is typed, so the property's declared type is
       // what makes `--where salesIdr:gt:9000000` a number rather than a 400.
       // A JSON where-node is already typed by whoever wrote it, and is left
       // exactly as given.
-      if (node && where && !where.trim().startsWith('{')) {
+      if (node && wheres.some((w) => !w.trim().startsWith('{')) && apiName) {
         const shape = (await api(ctx).blueprintObjectType(apiName!)) as {
           properties?: Array<{ apiName?: string; dataType?: string }>
         }
@@ -202,14 +320,13 @@ export const blueprintQuery: Command = {
         for (const p of shape?.properties ?? []) {
           if (p.apiName && p.dataType) types.set(p.apiName, p.dataType)
         }
-        node = typeWhereNode(node, types)
+        node = wheres.length === 1
+          ? typeWhereNode(node, types)
+          : { and: wheres.map((w, i) => (w.trim().startsWith('{') ? (node as { and: unknown[] }).and[i] : typeWhereNode((node as { and: unknown[] }).and[i], types))) }
       }
 
-      body = {
-        objectSet: node
-          ? { type: 'filter', objectSet: { type: 'base', objectType: apiName }, where: node }
-          : { type: 'base', objectType: apiName },
-      }
+      const from = set ? { type: 'reference', objectSetId: set.id } : { type: 'base', objectType: apiName }
+      body = { objectSet: node ? { type: 'filter', objectSet: from, where: node } : from }
     }
 
     const select = flagString(ctx, 'select')
@@ -221,7 +338,14 @@ export const blueprintQuery: Command = {
     const pageToken = flagString(ctx, 'page-token')
     if (pageToken) body.pageToken = pageToken
 
-    const result = await api(ctx).blueprintQuery(body)
+    // JSON is read by code that may go on to submit an Action: each row says its record version
+    // (`_meta.recordVersion`). A runtime that predates the flag is asked again without it.
+    if (flagBool(ctx, 'json')) body.recordVersions = true
+    const result = await api(ctx).blueprintQuery(body).catch(async (err: unknown) => {
+      if (!body.recordVersions || !/recordVersions/.test(String((err as Error)?.message ?? ''))) throw err
+      delete body.recordVersions
+      return api(ctx).blueprintQuery(body)
+    })
     const rows = result.rows ?? []
 
     if (rows.length === 0) {
@@ -231,7 +355,7 @@ export const blueprintQuery: Command = {
         // names the two things that produce one rather than printing "0 rows".
         text:
           'No rows.\n'
-          + '  The object type may have no dataset binding yet, or the filter matched nothing.\n'
+          + (set ? `  The set ${set.name} has no rows now, or the filter matched nothing.\n` : '  The object type may have no dataset binding yet, or the filter matched nothing.\n')
           + `  Check the binding with \`frontera blueprint get ${apiName ?? '<apiName>'}\`.`,
       }
     }

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

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
 
-import { DatasetApi, type DatasetColumn } from '../../api/dataset-api'
+import { DatasetApi, type DatasetColumn, type DatasetSummary } from '../../api/dataset-api'
 import { CliError } from '../../errors'
 import { table } from '../../table'
 import { flagString, type Command } from '../types'
@@ -103,6 +103,76 @@ function readColumns(raw: unknown, path: string): DatasetColumn[] {
   })
 }
 
+/**
+ * The column contract of a file dataset that declares `columns`: each included
+ * column with the type and nullability the file says, the CSV's own where it
+ * says nothing (`upload-preview`). The CSV must hold exactly the included
+ * columns, since a contract built this way records none as left out.
+ */
+async function fileContract(api: DatasetApi, csvPath: string, included: string[], declared: Map<string, { nullable?: boolean; databaseType?: string }>, filePath: string): Promise<DatasetColumn[]> {
+  const preview = await api.uploadPreview(csvPath)
+  const inferred = new Map((preview.columns ?? []).flatMap((c) => (c.name ? [[c.name, c] as const] : [])))
+  const extra = [...inferred.keys()].filter((name) => !included.includes(name))
+  if (extra.length) {
+    throw new CliError(`${filePath} declares \`columns\`, and its CSV carries ${extra.join(', ')}, which \`includedColumns\` leaves out.`, {
+      code: 'USAGE',
+      hint: 'With `columns`, the CSV holds exactly the included columns: add them to includedColumns, or drop them from the CSV.',
+    })
+  }
+  return included.map((name): DatasetColumn => {
+    const said = declared.get(name)
+    const seen = inferred.get(name)
+    const databaseType = (said?.databaseType ?? seen?.databaseType) as DatasetColumn['databaseType'] | undefined
+    if (!databaseType || !COLUMN_TYPES.includes(databaseType as never)) {
+      throw new CliError(`${filePath}: the CSV has no column "${name}" to read its type from.`, {
+        code: 'USAGE',
+        hint: `Add it to the CSV, or declare it: columns: [{ name: ${name}, databaseType: text, nullable: true }]`,
+      })
+    }
+    return { name, databaseType, nullable: said?.nullable ?? seen?.nullable ?? true }
+  })
+}
+
+/**
+ * A file dataset's `columns`: what it declares of each column instead of
+ * leaving it to the first CSV (`[{ name, nullable, databaseType? }]`). Each
+ * names an included column and says its nullability, its type, or both;
+ * the rest come from the CSV.
+ */
+function readFileColumns(raw: unknown, included: string[], path: string): Map<string, { nullable?: boolean; databaseType?: string }> {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new CliError(`${path} has \`columns\` that is not a list.`, {
+      code: 'USAGE',
+      hint: 'columns: [{ name: closed_at, nullable: true }] — the columns whose nullability (or type) the file declares.',
+    })
+  }
+  const out = new Map<string, { nullable?: boolean; databaseType?: string }>()
+  raw.forEach((entry, position) => {
+    const where = `${path}: columns[${position}]`
+    const column = (entry && typeof entry === 'object' ? entry : {}) as Record<string, unknown>
+    const name = column.name
+    if (typeof name !== 'string' || !included.includes(name)) {
+      throw new CliError(`${where} names ${typeof name === 'string' ? `"${name}", which is not in includedColumns` : 'no column'}.`, {
+        code: 'USAGE',
+        hint: `Included: ${included.join(', ')}`,
+      })
+    }
+    const strays = Object.keys(column).filter((k) => !['name', 'nullable', 'databaseType'].includes(k))
+    if (strays.length) throw new CliError(`${where} carries ${strays.join(', ')}.`, { code: 'USAGE', hint: 'A file dataset’s column is { name, nullable, databaseType }; databaseType is optional.' })
+    if (column.nullable !== undefined && typeof column.nullable !== 'boolean') {
+      throw new CliError(`${where}: \`nullable\` is true or false.`, { code: 'USAGE', hint: 'nullable: true lets the column hold empty values in any later CSV.' })
+    }
+    if (column.databaseType !== undefined && (typeof column.databaseType !== 'string' || !COLUMN_TYPES.includes(column.databaseType as never))) {
+      throw new CliError(`${where} has an unknown \`databaseType\`.`, { code: 'USAGE', hint: `One of: ${COLUMN_TYPES.join(', ')}` })
+    }
+    if (column.nullable === undefined && column.databaseType === undefined) {
+      throw new CliError(`${where} declares nothing about "${name}".`, { code: 'USAGE', hint: 'Say `nullable`, `databaseType`, or both; leave a column out to take both from the CSV.' })
+    }
+    out.set(name, { ...(column.nullable !== undefined ? { nullable: column.nullable as boolean } : {}), ...(column.databaseType !== undefined ? { databaseType: column.databaseType as string } : {}) })
+  })
+  return out
+}
+
 const list: Command = {
   meta: {
     noun: 'dataset',
@@ -476,7 +546,9 @@ const create: Command = {
     const KIND_KEYS: Record<string, Set<string>> = {
       blank: new Set(['columns']),
       source: new Set(['source', 'schema', 'relation', 'includedColumns']),
-      file: new Set(['path', 'includedColumns']),
+      // `columns`: what the file declares of each column (its nullability, its type) instead of
+      // leaving both to the first CSV, whose contract every later upload must then match.
+      file: new Set(['path', 'includedColumns', 'columns']),
     }
     const COMMON = new Set([
       'apiName', 'displayName', 'description', 'kind', 'keyColumns', 'deterministicKeyConfirmed',
@@ -569,10 +641,21 @@ const create: Command = {
       }
       // Relative to the DEFINITION, not the shell's cwd: the two travel together in a
       // repo, and resolving against cwd broke the moment anyone ran it from elsewhere.
-      created = await api.createFromFile(
-        resolve(dirname(path), csv),
-        { ...common, includedColumns: names(document.includedColumns, 'includedColumns', filePath) },
-      )
+      const csvPath = resolve(dirname(path), csv)
+      const included = names(document.includedColumns, 'includedColumns', filePath)
+      const declared = document.columns === undefined ? null : readFileColumns(document.columns, included, filePath)
+      if (!declared) {
+        created = await api.createFromFile(csvPath, { ...common, includedColumns: included })
+      } else {
+        // The contract as the file declares it, then the CSV loaded into it: a column declared
+        // nullable stays so, whatever this CSV holds.
+        const columns = await fileContract(api, csvPath, included, declared, filePath)
+        const blank = await api.createBlank({ ...common, columns })
+        if (!blank.id) {
+          throw new CliError(`"${apiName}" was created without an id, so its rows were not loaded.`, { code: 'FAILURE', hint: `frontera dataset upload ${apiName} ${csv}` })
+        }
+        created = await api.uploadSnapshot(blank.id, csvPath)
+      }
     } else {
       throw new CliError(`${filePath} has an unknown \`kind\`: ${String(kind)}.`, {
         code: 'USAGE',
@@ -664,4 +747,70 @@ const upload: Command = {
   },
 }
 
-export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create, upload]
+const revise: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'revise',
+    args: [],
+    flags: { file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Cut a new revision of a file dataset from its CSV, when the CSV holds empty values the current revision refuses',
+    examples: ['frontera dataset revise -f datasets/work_orders.json'],
+  },
+  /**
+   * A file dataset's first load fixes which columns may be empty. A later CSV
+   * with empty values in a column that had none is refused by `upload`; this
+   * makes that CSV the dataset's next revision instead, which only widens what
+   * may be empty. A column added, dropped or retyped, or a key column that
+   * became nullable, is a different dataset: the service refuses it, naming
+   * the column. Object types still read the old revision until they are bound
+   * to the new one (`blueprint bind`, which `local dev` does).
+   */
+  async run(ctx) {
+    const filePath = flagString(ctx, 'file')
+    if (!filePath) throw new CliError('A definition file is required.', { code: 'USAGE', hint: 'frontera dataset revise -f datasets/<apiName>.json' })
+    const path = resolve(ctx.cwd, filePath)
+    let document: Record<string, unknown>
+    try {
+      document = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+    } catch (err) {
+      throw new CliError(`${filePath} could not be read as JSON: ${(err as Error).message}`, { code: 'USAGE', hint: 'A dataset definition is JSON: `frontera local schema dataset`.' })
+    }
+    if (document.kind !== 'file' || typeof document.path !== 'string' || typeof document.apiName !== 'string') {
+      throw new CliError(`${filePath} is not a file dataset.`, { code: 'USAGE', hint: 'revise reads kind: "file" with `apiName` and `path`; a Source dataset is revised from its Source.' })
+    }
+    const apiName = document.apiName
+    const csvPath = resolve(dirname(path), document.path)
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const dataset = await resolveDataset(api, apiName)
+    const revisions = await api.revisions(dataset.id!)
+    const expectedRevision = (revisions.find((r) => r.id === dataset.currentRevisionId) ?? revisions.at(-1))?.revision
+    if (typeof expectedRevision !== 'number') {
+      throw new CliError(`"${apiName}" has no current revision to follow.`, { code: 'CONFLICT', hint: `frontera dataset get ${apiName}` })
+    }
+    let result: DatasetSummary
+    try {
+      result = await api.reviseFromFile(dataset.id!, csvPath, expectedRevision)
+    } catch (err) {
+      if (err instanceof CliError && (err.code === 'DATASET_REVISION_UNCHANGED' || /DATASET_REVISION_UNCHANGED/.test(err.message))) {
+        return { data: { unchanged: true, revision: expectedRevision }, text: `"${apiName}" already fits ${basename(csvPath)}: revision ${expectedRevision} stays.` }
+      }
+      if (err instanceof CliError && err.code === 'CONFLICT') {
+        throw new CliError(err.message, {
+          code: 'CONFLICT',
+          hint: 'A new revision may only let more columns be empty. A column added, dropped or retyped (or a key column that became nullable) is a new dataset: give it another apiName, or on a local runtime run `frontera local reset`, which creates every dataset again from its definition.',
+        })
+      }
+      throw err
+    }
+    const revision = (result as { currentRevision?: { revision?: number } }).currentRevision?.revision
+    return {
+      data: result,
+      text: `Cut revision ${revision ?? expectedRevision + 1} of "${apiName}" from ${basename(csvPath)}.\n`
+        + '  Object types read the old revision until bound to this one: `frontera blueprint bind <Type> --dataset '
+        + `${apiName} --file <mapping> --accept-contract-change\`.`,
+    }
+  },
+}
+
+export const datasetCommands: Command[] = [list, get, rows, sources, preview, testSource, create, upload, revise]