@frontera-sdk/cli 1.50.79 → 1.50.81

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

@@ -0,0 +1,592 @@
+import { readFileSync, statSync } from 'node:fs'
+import { basename, relative, sep } from 'node:path'
+
+import { MediaApi, type ChunkingStatus, type ExtractionStatus, type MediaItem } from '../../api/media-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { UPLOAD_CONCURRENCY } from '../knowledge/upload-batch'
+import { extensionOf, planUploads, type PlannedFile } from '../knowledge/upload-plan'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+
+/**
+ * Media Sets: governed document collections that extraction, chunking and
+ * Blueprint read from.
+ *
+ * Every verb here is `authLane: 'session'` — see `MediaApi` for why both key
+ * kinds are refused; the dispatcher words that refusal. The verbs cover one path: create a set, upload a
+ * directory, switch processing on, wait for it, spot-check with a search, and
+ * grant the set to the workspace that will use it.
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The types a Media Set accepts, by extension.
+ *
+ * A mirror of `MEDIA_ALLOWED_TYPES` in the service, which stays the authority.
+ * The service reads the type the client DECLARES, so the mapping is not only a
+ * filter — a `.pdf` sent as `application/octet-stream` is refused.
+ */
+export const MEDIA_MIME_BY_EXTENSION: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.txt': 'text/plain',
+  '.csv': 'text/csv',
+  '.json': 'application/json',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+}
+
+/** The workspace for a next-step line: the one named, or a placeholder. */
+function ws(ctx: CommandContext): string {
+  return ctx.workspaceId ?? '<workspaceId>'
+}
+
+function api(ctx: CommandContext): MediaApi {
+  return new MediaApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+}
+
+/** Accept a set by API name or id — `media list` shows both. */
+async function resolveSet(client: MediaApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+  const sets = await client.list()
+  const match = sets.find((s) => s.apiName.toLowerCase() === ref.toLowerCase())
+  if (match) return match.id
+  throw new CliError(`no Media Set named "${ref}"`, {
+    code: 'NOT_FOUND',
+    // Without an administrator's view, the list is only what the named
+    // workspace was granted — so a set you just created may be absent here.
+    hint: `known sets: ${sets.map((s) => s.apiName).join(', ') || '(none visible)'} — `
+      + 'or pass the set id from `frontera media list --workspace <id>`',
+  })
+}
+
+function requireSetArg(ctx: CommandContext, verb: string): string {
+  const ref = ctx.positional[0]
+  if (!ref) throw new UsageError('missing <set>', `frontera media list --workspace <id> — then \`frontera media ${verb} <apiName>\``)
+  return ref
+}
+
+function positiveNumber(ctx: CommandContext, flag: string, integer: boolean): number | undefined {
+  const raw = flagString(ctx, flag)
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  if (Number.isNaN(value) || value < 0 || (integer && (!Number.isInteger(value) || value < 1))) {
+    throw new UsageError(
+      `--${flag} must be a ${integer ? 'positive whole number' : 'non-negative number'}, not "${raw}"`,
+      integer ? `try --${flag} 5` : `try --${flag} 0.5`,
+    )
+  }
+  return value
+}
+
+const list: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'list',
+    authLane: 'session',
+    args: [],
+    flags: {},
+    summary: 'List the Media Sets visible to you in a workspace',
+    sessionAlternative: 'Blueprint → Media Sets',
+    examples: ['frontera media list --workspace <workspaceId>', 'frontera media list --workspace <workspaceId> --json'],
+  },
+  async run(ctx) {
+    const sets = await api(ctx).list()
+    return {
+      data: sets,
+      text:
+        sets.length === 0
+          ? 'No Media Sets visible. Create one with `frontera media create <apiName>`.'
+          : table(
+              ['apiName', 'name', 'items', 'id'],
+              sets.map((s) => [s.apiName, s.displayName, String(s.itemCount ?? ''), s.id]),
+              [undefined, 40, undefined, undefined],
+            ),
+    }
+  },
+}
+
+const create: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'create',
+    scope: 'organization',
+    authLane: 'session',
+    args: [{ name: 'apiName', required: true, description: 'letters, digits and underscores, starting with a letter' }],
+    flags: { name: 'string', description: 'string' },
+    summary: 'Create a Media Set',
+    sessionAlternative: 'Blueprint → Media Sets → Create set',
+    examples: [
+      'frontera media create contracts',
+      'frontera media create contracts --name "Signed contracts" --description "MSAs"',
+    ],
+  },
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) throw new UsageError('missing <apiName>', 'frontera media create contracts --name "Signed contracts"')
+    const description = flagString(ctx, 'description')
+    const set = await api(ctx).create({
+      apiName,
+      displayName: flagString(ctx, 'name') ?? apiName,
+      ...(description ? { description } : {}),
+    })
+    return {
+      data: set,
+      text: [
+        `created ${set.apiName}  ${set.id}`,
+        // Grant first: upload and search act inside a workspace, and the
+        // service refuses both for a workspace the set is not granted to.
+        `  next: frontera media grant ${set.apiName} <workspaceId> --permissions read,write`,
+        `  then: frontera media upload ${set.apiName} <path…> --workspace <workspaceId>`,
+      ].join('\n'),
+    }
+  },
+}
+
+/**
+ * The service's hard ceiling on one file, whatever a deployment configures
+ * below it. Checked before reading so a stray disk image is not pulled into
+ * memory four at a time just to be refused.
+ */
+export const MEDIA_MAX_BYTES = 50 * 1024 * 1024
+
+interface UploadOutcome {
+  file: string
+  logicalPath: string
+  /** `skipped`: `--skip-existing`, and the set already holds this path. */
+  status: 'uploaded' | 'failed' | 'skipped'
+  item?: MediaItem
+  error?: string
+  /** The failure's error code, so an all-failed batch can name its cause. */
+  code?: string
+  /** The failure's own recovery, carried through an all-failed rethrow. */
+  hint?: string
+}
+
+/**
+ * The item's path inside the set. A file found by walking a directory keeps
+ * its place under that directory, so `contracts/2024/a.pdf` and
+ * `contracts/2025/a.pdf` stay two items instead of versioning each other.
+ */
+function logicalPathOf(file: PlannedFile): string {
+  return file.root === undefined ? basename(file.path) : relative(file.root, file.path).split(sep).join('/')
+}
+
+const upload: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'upload',
+    authLane: 'session',
+    args: [
+      { name: 'set', required: true, description: 'Media Set API name or id, from `frontera media list`' },
+      { name: 'path...', required: true, description: 'files or directories; directories are walked, unsupported types skipped' },
+    ],
+    flags: { markings: 'string', 'skip-existing': 'boolean' },
+    summary: 'Upload local files into a Media Set; the same path again adds a new version',
+    sessionAlternative: 'Blueprint → Media Sets → Files',
+    examples: [
+      'frontera media upload contracts ./contracts --workspace <workspaceId>',
+      'frontera media upload contracts msa.pdf --workspace <workspaceId>',
+      'frontera media upload contracts ./contracts --workspace <id> --skip-existing',
+    ],
+  },
+  async run(ctx) {
+    const [ref, ...paths] = ctx.positional
+    if (!ref) throw new UsageError('missing <set>', 'frontera media list --workspace <id> — then pass an API name or id')
+    if (paths.length === 0) throw new UsageError('missing <path...>', `frontera media upload ${ref} <file-or-directory…>`)
+
+    const plan = planUploads(paths, Object.keys(MEDIA_MIME_BY_EXTENSION))
+    if (plan.rejected.length > 0) {
+      // Same rule as `knowledge upload`: a path the caller named that cannot go
+      // is a mistake in the command, so nothing is sent.
+      const first = plan.rejected[0]!
+      throw new UsageError(`cannot upload ${first.path}: ${first.reason}`, 'fix the path, or pass a directory and let unsupported types be skipped')
+    }
+    if (plan.files.length === 0) {
+      throw new CliError('nothing to upload', {
+        code: 'USAGE',
+        hint: plan.skippedByType > 0 ? `${plan.skippedByType} file(s) found, none of a supported type` : 'the paths given contain no files',
+      })
+    }
+
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const markings = flagString(ctx, 'markings')
+    // Re-running a directory re-versions every file that already landed, so a
+    // retry after a partial failure asks for only what the set lacks.
+    const existing = flagBool(ctx, 'skip-existing')
+      ? new Set((await client.items(setId)).filter((i) => i.isLatest).map((i) => i.path))
+      : new Set<string>()
+
+    // A failure never ends the batch; outcomes stay in plan order.
+    const outcomes: UploadOutcome[] = new Array(plan.files.length)
+    let next = 0
+    const worker = async (): Promise<void> => {
+      for (let index = next++; index < plan.files.length; index = next++) {
+        const planned = plan.files[index]!
+        const logicalPath = logicalPathOf(planned)
+        if (existing.has(logicalPath)) {
+          outcomes[index] = { file: planned.path, logicalPath, status: 'skipped' }
+          continue
+        }
+        try {
+          // Inside the try: a file removed between the walk and this read
+          // fails only itself, not the batch.
+          if (statSync(planned.path).size > MEDIA_MAX_BYTES) {
+            throw new CliError('larger than the 50 MB Media Set limit', { code: 'BAD_REQUEST' })
+          }
+          const item = await client.upload(setId, {
+            bytes: new Uint8Array(readFileSync(planned.path)),
+            filename: basename(planned.path),
+            mime: MEDIA_MIME_BY_EXTENSION[extensionOf(planned.path)]!,
+            logicalPath,
+            ...(markings ? { markings } : {}),
+          })
+          outcomes[index] = { file: planned.path, logicalPath, status: 'uploaded', item }
+        } catch (err) {
+          outcomes[index] = {
+            file: planned.path,
+            logicalPath,
+            status: 'failed',
+            error: err instanceof Error ? err.message : String(err),
+            ...(err instanceof CliError ? { code: err.code } : {}),
+            ...(err instanceof CliError && err.hint ? { hint: err.hint } : {}),
+          }
+        }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, plan.files.length) }, () => worker()))
+
+    const count = (status: UploadOutcome['status']) => outcomes.filter((o) => o.status === status).length
+    const uploaded = count('uploaded')
+    const failed = count('failed')
+    const present = count('skipped')
+    const rerun = `frontera media upload ${ref} ${paths.join(' ')} --workspace ${ws(ctx)} --skip-existing`
+    if (uploaded === 0 && failed > 0) {
+      const firstFailure = outcomes.find((o) => o.status === 'failed')!
+      // A permission refusal is not a per-file fault. Keys never get this far
+      // (the dispatcher refuses them before any request), but a person whose
+      // role lacks upload is refused on every file: surface that as itself,
+      // exit 4, rather than as a retryable batch count.
+      if (
+        (firstFailure.code === 'UNAUTHORIZED' || firstFailure.code === 'FORBIDDEN')
+        && outcomes.every((o) => o.status !== 'failed' || o.code === firstFailure.code)
+      ) {
+        throw new CliError(firstFailure.error ?? 'refused', {
+          code: firstFailure.code,
+          ...(firstFailure.hint ? { hint: firstFailure.hint } : {}),
+        })
+      }
+      // The upload route answers "not found" for a set this workspace holds no
+      // write grant on — the same answer as for no set at all, by design.
+      const ungranted = outcomes.every((o) => o.status !== 'failed' || o.code === 'NOT_FOUND')
+      throw new CliError(`all ${failed} upload(s) failed: ${firstFailure.error ?? 'unknown error'}`, {
+        code: 'FAILURE',
+        hint: ungranted
+          ? `the set may not be granted to workspace ${ws(ctx)} — `
+            + `frontera media grant ${ref} ${ws(ctx)} --permissions read,write`
+          : 'fix the cause above, then re-run — a failed upload creates no item',
+      })
+    }
+
+    const lines: string[] = []
+    if (failed > 0) lines.push(`${failed} of ${outcomes.length} FAILED — see below`)
+    lines.push(
+      `uploaded ${uploaded} file(s) into ${ref}`
+      + (present > 0 ? `, ${present} already present` : '')
+      + (plan.skippedByType > 0 ? `, skipped ${plan.skippedByType} of an unsupported type` : ''),
+    )
+    lines.push(table(
+      ['path', 'status', 'version', 'detail'],
+      outcomes.map((o) => [o.logicalPath, o.status, o.item ? String(o.item.version) : '', o.error ?? o.item?.mediaItemId ?? '']),
+      [50, undefined, undefined, 60],
+    ))
+    if (failed > 0) lines.push(`  send only what is missing, without re-versioning the rest: ${rerun}`)
+    lines.push(`  processing runs asynchronously — frontera media status ${ref} --watch --workspace ${ws(ctx)}`)
+    return {
+      data: { set: ref, setId, uploaded, failed, alreadyPresent: present, skippedByType: plan.skippedByType, items: outcomes },
+      text: lines.join('\n'),
+    }
+  },
+}
+
+const processCommand: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'process',
+    scope: 'organization',
+    authLane: 'session',
+    args: [{ name: 'set', required: true, description: 'Media Set API name or id' }],
+    flags: { ocr: 'boolean', 'skip-embed': 'boolean' },
+    summary: 'Switch on text extraction, chunking and embedding for a Media Set',
+    sessionAlternative: 'Blueprint → Media Sets → Processing',
+    examples: [
+      'frontera media process contracts',
+      'frontera media process scanned_invoices --ocr',
+      'frontera media process contracts --skip-embed',
+    ],
+  },
+  async run(ctx) {
+    const ref = requireSetArg(ctx, 'process')
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const embed = !flagBool(ctx, 'skip-embed')
+
+    // Extraction first: the service refuses chunking on a set that does not
+    // extract, because passages are cut from extracted text.
+    await client.setExtraction(setId, { enabled: true, ...(flagBool(ctx, 'ocr') ? { profile: 'ocr' as const } : {}) })
+    await client.setChunking(setId, { enabled: true, embed: { enabled: embed } })
+
+    return {
+      data: { setId, extraction: true, chunking: true, embedding: embed },
+      text: [
+        `processing on for ${ref}: extraction${flagBool(ctx, 'ocr') ? ' (ocr)' : ''}, chunking${embed ? ', embedding' : ''}`,
+        `  existing items are queued too — frontera media status ${ref} --watch --workspace <workspaceId>`,
+      ].join('\n'),
+    }
+  },
+}
+
+/** Polling cadence for `status --watch`. Mutable so a test can run it without sleeping. */
+export const WAIT = { intervalMs: 5_000, timeoutMs: 10 * 60_000 }
+
+function settled(extraction: ExtractionStatus, chunking: ChunkingStatus): boolean {
+  const e = extraction.extraction.extractEnabled ? extraction.coverage.pending : 0
+  const c = chunking.chunking.chunkEnabled ? chunking.coverage.pending : 0
+  const m = chunking.chunking.chunkEnabled && chunking.chunking.embedEnabled ? chunking.coverage.embedPending : 0
+  return e + c + m === 0
+}
+
+function renderStatus(ref: string, workspace: string, extraction: ExtractionStatus, chunking: ChunkingStatus): string {
+  const x = extraction.coverage
+  const c = chunking.coverage
+  const on = (enabled: boolean, detail = ''): string => (enabled ? `on${detail}` : 'off')
+  const embedOn = chunking.chunking.chunkEnabled && chunking.chunking.embedEnabled
+  const lines = [
+    table(
+      ['stage', 'state', 'ready', 'pending', 'failed', 'skipped', 'detail'],
+      [
+        ['extraction', on(extraction.extraction.extractEnabled, ` (${extraction.extraction.extractProfile})`),
+          `${x.ready}/${x.items}`, String(x.pending), String(x.failed), String(x.skipped), `${x.items} item(s)`],
+        ['chunking', on(chunking.chunking.chunkEnabled),
+          `${c.ready}/${c.extracts}`, String(c.pending), String(c.failed), String(c.skipped),
+          `${c.chunks} passage(s)${c.truncated > 0 ? `, ${c.truncated} document(s) truncated` : ''}`],
+        ['embedding', on(embedOn),
+          `${c.embedded}/${c.chunks}`, String(c.embedPending), String(c.embedFailed), '', chunking.chunking.embedModel ?? 'no model set'],
+      ],
+    ),
+  ]
+  if (!extraction.extraction.extractEnabled) lines.push(`  nothing is processed until you run \`frontera media process ${ref}\``)
+  if (x.failed + c.failed + c.embedFailed > 0) lines.push(`  after fixing the cause: frontera media retry ${ref}`)
+  if (embedOn && c.embedded > 0) lines.push(`  spot-check: frontera media search ${ref} "<a question the documents answer>" --workspace ${workspace}`)
+  return lines.join('\n')
+}
+
+const status: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'status',
+    authLane: 'session',
+    args: [{ name: 'set', required: true, description: 'Media Set API name or id' }],
+    flags: { watch: 'boolean' },
+    summary: 'Show extraction, chunking and embedding progress for a Media Set',
+    sessionAlternative: 'Blueprint → Media Sets → Processing',
+    examples: [
+      'frontera media status contracts --workspace <workspaceId>',
+      'frontera media status contracts --workspace <workspaceId> --watch --json',
+    ],
+  },
+  async run(ctx) {
+    const ref = requireSetArg(ctx, 'status')
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const read = () => Promise.all([client.extraction(setId), client.chunking(setId)])
+
+    let [extraction, chunking] = await read()
+    if (flagBool(ctx, 'watch')) {
+      const deadline = Date.now() + WAIT.timeoutMs
+      while (!settled(extraction, chunking)) {
+        if (Date.now() >= deadline) {
+          throw new CliError(`${ref} is still processing after ${Math.round(WAIT.timeoutMs / 60_000)} minutes`, {
+            code: 'FAILURE',
+            hint: `re-run \`frontera media status ${ref} --watch --workspace ${ws(ctx)}\` — the work continues server-side`,
+          })
+        }
+        await new Promise((r) => setTimeout(r, WAIT.intervalMs))
+        ;[extraction, chunking] = await read()
+      }
+    }
+
+    return {
+      data: { setId, extraction, chunking, settled: settled(extraction, chunking) },
+      text: renderStatus(ref, ws(ctx), extraction, chunking),
+    }
+  },
+}
+
+const retry: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'retry',
+    scope: 'organization',
+    authLane: 'session',
+    args: [{ name: 'set', required: true, description: 'Media Set API name or id' }],
+    flags: {},
+    summary: 'Queue a Media Set’s failed extractions, chunkings and embeddings again',
+    sessionAlternative: 'Blueprint → Media Sets → Processing',
+    examples: ['frontera media retry contracts'],
+  },
+  async run(ctx) {
+    const ref = requireSetArg(ctx, 'retry')
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const extraction = await client.retryExtraction(setId)
+    const chunking = await client.retryChunking(setId)
+    return {
+      data: { setId, extraction: extraction.retried, chunking: chunking.retried.chunking, embedding: chunking.retried.embedding },
+      text: [
+        `re-queued ${extraction.retried} extraction(s), ${chunking.retried.chunking} chunking(s), ${chunking.retried.embedding} embedding(s)`,
+        `  frontera media status ${ref} --watch --workspace <workspaceId>`,
+      ].join('\n'),
+    }
+  },
+}
+
+/**
+ * Retrieval, which is the only thing that proves processing produced text an
+ * agent can find. `status` counts passages; it cannot say they are useful.
+ */
+const search: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'search',
+    authLane: 'session',
+    args: [
+      { name: 'set', required: true, description: 'Media Set API name or id' },
+      { name: 'query', required: true, description: 'text to search for, as an agent would ask it' },
+    ],
+    flags: { limit: 'string', 'max-distance': 'string' },
+    summary: 'Search a Media Set’s passages and show the nearest matches',
+    sessionAlternative: 'Blueprint → Media Sets → Processing',
+    examples: [
+      'frontera media search contracts "termination notice" --workspace <id>',
+      'frontera media search contracts "governing law" --workspace <id> --limit 3',
+    ],
+  },
+  async run(ctx) {
+    const [ref, ...queryParts] = ctx.positional
+    if (!ref) throw new UsageError('missing <set>', 'frontera media list --workspace <id> — then pass an API name or id')
+    const query = queryParts.join(' ').trim()
+    if (!query) throw new UsageError('missing <query>', `frontera media search ${ref} "what a user would ask"`)
+    const limit = positiveNumber(ctx, 'limit', true)
+    const maxDistance = positiveNumber(ctx, 'max-distance', false)
+
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const result = await client.search(setId, {
+      query,
+      ...(limit === undefined ? {} : { limit }),
+      ...(maxDistance === undefined ? {} : { maxDistance }),
+    })
+
+    if (result.matches.length === 0) {
+      return {
+        data: result,
+        text: `No passages matched. Check \`frontera media status ${ref} --workspace ${ws(ctx)}\` — only embedded passages are searchable.`,
+      }
+    }
+    return {
+      data: result,
+      text: table(
+        ['distance', 'path', 'passage'],
+        result.matches.map((m) => [m.distance.toFixed(3), m.path, m.text.replace(/\s+/g, ' ').trim()]),
+        [undefined, 40, 90],
+      ),
+    }
+  },
+}
+
+const GRANT_PERMISSIONS = ['read', 'write', 'manage', 'read_sensitive']
+
+function requireWorkspaceArg(ctx: CommandContext, verb: string): { ref: string; workspaceId: string } {
+  const [ref, workspaceId] = ctx.positional
+  if (!ref) throw new UsageError('missing <set>', 'frontera media list --workspace <id> — then pass an API name or id')
+  if (!workspaceId || !UUID.test(workspaceId)) {
+    throw new UsageError(
+      workspaceId ? `<workspace> must be a workspace id, not "${workspaceId}"` : 'missing <workspace>',
+      `frontera workspace list — then \`frontera media ${verb} ${ref} <workspaceId>\``,
+    )
+  }
+  return { ref, workspaceId }
+}
+
+const grant: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'grant',
+    scope: 'organization',
+    authLane: 'session',
+    args: [
+      { name: 'set', required: true, description: 'Media Set API name or id' },
+      { name: 'workspace', required: true, description: 'workspace id, from `frontera workspace list`' },
+    ],
+    flags: { permissions: 'string' },
+    summary: 'Grant a workspace access to a Media Set; re-granting replaces its permissions',
+    sessionAlternative: 'Blueprint → Media Sets → Access',
+    examples: [
+      'frontera media grant contracts 7f3c9a2e-1b4d-4e8f-9a6c-2d5e8f1a3b7c',
+      'frontera media grant contracts <workspaceId> --permissions read,write',
+    ],
+  },
+  async run(ctx) {
+    const { ref, workspaceId } = requireWorkspaceArg(ctx, 'grant')
+    const raw = flagString(ctx, 'permissions')
+    const permissions = raw?.split(',').map((p) => p.trim()).filter(Boolean)
+    const unknown = permissions?.find((p) => !GRANT_PERMISSIONS.includes(p))
+    if (unknown) throw new UsageError(`unknown permission "${unknown}"`, `one or more of: ${GRANT_PERMISSIONS.join(', ')}`)
+
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const result = await client.grant(setId, { workspaceId, ...(permissions?.length ? { permissions } : {}) })
+    return {
+      data: { setId, workspaceId, permissions: result.permissions },
+      text: `granted ${ref} to workspace ${workspaceId}: ${result.permissions.join(', ')}`,
+    }
+  },
+}
+
+const revoke: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'revoke',
+    scope: 'organization',
+    authLane: 'session',
+    args: [
+      { name: 'set', required: true, description: 'Media Set API name or id' },
+      { name: 'workspace', required: true, description: 'workspace id' },
+    ],
+    flags: {},
+    summary: 'Remove a workspace’s access to a Media Set',
+    sessionAlternative: 'Blueprint → Media Sets → Access',
+    examples: ['frontera media revoke contracts 7f3c9a2e-1b4d-4e8f-9a6c-2d5e8f1a3b7c'],
+  },
+  async run(ctx) {
+    const { ref, workspaceId } = requireWorkspaceArg(ctx, 'revoke')
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    await client.revoke(setId, workspaceId)
+    return {
+      data: { setId, workspaceId, revoked: true },
+      // Said explicitly: the set and its items are untouched.
+      text: `revoked workspace ${workspaceId} from ${ref} — the set and its items are unchanged`,
+    }
+  },
+}
+
+export const mediaCommands: Command[] = [list, create, upload, processCommand, status, retry, search, grant, revoke]