@frontera-sdk/cli 1.50.79 → 1.50.81

package/src/commands/chat-app/index-commands.ts

@@ -0,0 +1,475 @@
+import { readFileSync } from 'node:fs'
+
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * Chat Apps — an Agent roster presented to an audience, published as an
+ * immutable version.
+ *
+ * The editor routes have always accepted a workspace key, so a Chat App could
+ * be staged and published from a script; nothing in the CLI reached them, which
+ * left every rollout a sequence of Console clicks.
+ *
+ * What is NOT here: talking to one. The runtime routes (`/chat`, Sessions,
+ * Agent mode) authenticate people, not keys, and refuse agent API keys
+ * outright — an App answers the person using it. Verify a publish by opening
+ * the App.
+ *
+ * Drafts are per principal. A key's draft is its own, separate from the one a
+ * person is editing in the Console, so `draft` then `publish` from the same key
+ * never picks up someone else's work in progress.
+ */
+
+interface ChatAppRow {
+  id?: string
+  slug?: string
+  displayName?: string
+  status?: string
+  kind?: string
+  systemKey?: string | null
+  deployedVersionId?: string | null
+}
+
+interface Finding {
+  level?: string
+  code?: string
+  message?: string
+}
+
+interface EditorState {
+  app?: ChatAppRow
+  draft?: { configuration?: unknown; saved?: boolean; updatedAt?: string | null }
+  live?: { id?: string; version?: string; createdAt?: string } | null
+  findings?: Finding[]
+  grants?: Array<{ principalKind?: string; principalId?: string }>
+  endpoints?: Array<{ kind?: string; enabled?: boolean }>
+  agents?: Array<{ agentConfigId?: string; slug?: string; name?: string; publishedVersion?: number | null }>
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const ENDPOINTS = ['platform', 'standalone', 'widget'] as const
+const ACCENTS = ['blue', 'violet', 'green', 'amber', 'rose', 'teal', 'slate']
+
+/** The workspace's Chat Apps. The built-in Chat is an application too, but not an editable one. */
+async function chatApps(api: PlatformApi): Promise<ChatAppRow[]> {
+  return ((await api.platformApps()) as ChatAppRow[]).filter((a) => a.kind === 'chat' && !a.systemKey)
+}
+
+async function resolveChatAppRef(api: PlatformApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+
+  const rows = await chatApps(api)
+  const match = rows.find((a) => (a.slug ?? '').toLowerCase() === ref.toLowerCase())
+  if (match?.id) return match.id
+
+  throw new CliError(`no Chat App named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint: `known Chat Apps: ${rows.map((a) => a.slug).filter(Boolean).join(', ') || '(none) — frontera chat-app create <slug> --name <name>'}`,
+  })
+}
+
+async function readConfiguration(path: string): Promise<unknown> {
+  let raw: string
+  if (path === '-') {
+    const chunks: Uint8Array[] = []
+    for await (const chunk of Bun.stdin.stream()) chunks.push(chunk)
+    raw = Buffer.concat(chunks).toString('utf8')
+  } else {
+    try {
+      raw = readFileSync(path, 'utf8')
+    } catch {
+      throw new UsageError(`could not read ${path}`, 'check the path, or pipe the configuration in with -')
+    }
+  }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new UsageError(
+      'the configuration is not valid JSON',
+      'start from `frontera chat-app get <app> --json | jq .draft.configuration`',
+    )
+  }
+}
+
+function findingLines(findings: Finding[]): string[] {
+  return findings.map((f) => `  ${f.level ?? '?'}  ${f.message ?? f.code ?? ''}`)
+}
+
+/**
+ * Turn a Chat App `VALIDATION_ERROR` into one the caller can act on.
+ *
+ * The service uses that code for two shapes. A blocked publish carries level-
+ * tagged findings; a file that is not a Chat App configuration at all carries
+ * plain `path: problem` strings. Rendering both as findings printed "?" for
+ * every schema error and called a malformed file a blocked publish.
+ *
+ * `ownDraft` is a publish of the caller's saved draft. A key's draft is its
+ * own, so an empty roster there usually means no `draft` ran from this key —
+ * not that the App the Console shows is empty.
+ */
+function rethrowValidation(err: unknown, ref: string, ownDraft = false): never {
+  const e = err as { code?: string; message?: string; details?: { details?: unknown } }
+  const entries = e.details?.details
+  if (e.code !== 'VALIDATION_ERROR' || !Array.isArray(entries)) throw err
+
+  const leveled = entries.some((x) => typeof x === 'object' && x !== null && 'level' in x)
+  const lines = entries.map((x) => (typeof x === 'string' ? x : (findingLines([x as Finding])[0] ?? '').trim()))
+  if (ownDraft && entries.some((x) => (x as Finding)?.code === 'roster.empty')) {
+    lines.push(`a key publishes its own draft — run \`frontera chat-app draft ${ref} --from ./app.json\` first`)
+  }
+  throw new CliError(leveled ? 'the configuration cannot be published yet' : (e.message ?? 'Invalid Chat App configuration'), {
+    code: 'VALIDATION_ERROR',
+    hint: lines.join('; '),
+  })
+}
+
+function appRef(ctx: { positional: string[] }, verb: string): string {
+  const ref = ctx.positional[0]
+  if (!ref) throw new UsageError('missing <app>', `frontera chat-app list — then frontera chat-app ${verb} <slug>`)
+  return ref
+}
+
+const list: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List Chat Apps in this workspace',
+    examples: ['frontera chat-app list', 'frontera chat-app list --json'],
+  },
+  async run(ctx) {
+    const rows = await chatApps(new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId))
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No Chat Apps in this workspace. Create one with `frontera chat-app create <slug> --name <name>`.'
+          : table(
+              ['slug', 'name', 'live', 'status', 'id'],
+              rows.map((a) => [
+                a.slug ?? '?',
+                a.displayName ?? '',
+                a.deployedVersionId ? 'yes' : 'no',
+                a.status ?? '',
+                a.id ?? '',
+              ]),
+            ),
+    }
+  },
+}
+
+const create: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'create',
+    args: [{ name: 'slug', required: true, description: 'lowercase letters, digits and hyphens' }],
+    flags: { name: 'string', description: 'string', accent: 'string' },
+    summary: 'Create a Chat App, or return the one that already has this slug',
+    examples: ['frontera chat-app create support-desk --name "Support Desk"'],
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0]
+    if (!slug) throw new UsageError('missing <slug>', 'frontera chat-app create support-desk --name "Support Desk"')
+    if (!/^[a-z0-9-]+$/.test(slug) || slug.length > 60) {
+      throw new UsageError(`"${slug}" is not a valid slug`, 'lowercase letters, digits and hyphens, up to 60 — e.g. support-desk')
+    }
+    const displayName = flagString(ctx, 'name') ?? slug
+    const accent = flagString(ctx, 'accent')
+    if (accent && !ACCENTS.includes(accent)) {
+      throw new UsageError(`unknown accent "${accent}"`, `one of: ${ACCENTS.join(', ')}`)
+    }
+    const description = flagString(ctx, 'description')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const result = await api.ensureChatApp({
+      slug,
+      displayName,
+      ...(description ? { description } : {}),
+      ...(accent ? { accent } : {}),
+    })
+
+    // `ensure` matches on slug and kind, and the built-in Chat is a Chat App by
+    // kind — so its slug hands back its id, which no editor route will accept.
+    // Checked only on the `exists` path; a new App cannot be the built-in.
+    if (!result.created) {
+      const hit = ((await api.platformApps()) as ChatAppRow[]).find((a) => a.id === result.id)
+      if (hit?.systemKey) {
+        throw new CliError(`"${slug}" is the built-in Chat, not an editable Chat App`, {
+          code: 'CONFLICT',
+          hint: 'pick another slug — e.g. frontera chat-app create support-desk --name "Support Desk"',
+        })
+      }
+    }
+
+    // `ensure` returns an existing App untouched, so presentation flags passed
+    // with its slug did nothing — say so rather than imply they landed.
+    const ignored = result.created ? [] : (['name', 'description', 'accent'] as const).filter((f) => flagString(ctx, f))
+    return {
+      data: result,
+      text: [
+        `${result.created ? 'created' : 'exists'} ${result.slug}  ${result.id}`,
+        ...(ignored.length
+          ? [`  exists — ${ignored.map((f) => `--${f}`).join(', ')} not applied; change presentation in the App editor`]
+          : []),
+        // A new App opens to the whole workspace but has no roster, so it cannot
+        // publish yet — the next step is the configuration, not the audience.
+        `  next: frontera chat-app get ${result.slug} --json | jq .draft.configuration > app.json`,
+      ].join('\n'),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'get',
+    args: [{ name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' }],
+    flags: {},
+    summary: 'Show a Chat App: live version, draft findings, roster, audience and endpoints',
+    examples: [
+      'frontera chat-app get support-desk',
+      'frontera chat-app get support-desk --json | jq .draft.configuration > app.json',
+    ],
+  },
+  async run(ctx) {
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const state = (await api.chatAppEditor(await resolveChatAppRef(api, appRef(ctx, 'get')))) as EditorState
+
+    const findings = state.findings ?? []
+    const grants = state.grants ?? []
+    const lines = [
+      `${state.app?.displayName ?? state.app?.slug ?? '?'}  (${state.app?.slug ?? ''})`,
+      `  live: ${state.live ? `v${state.live.version}` : 'not published'}`,
+      `  draft: ${state.draft?.saved ? `saved ${state.draft.updatedAt ?? ''}`.trim() : 'none saved — shows the live configuration'}`,
+      `  access: ${
+        grants.length === 0
+          ? 'nobody'
+          : grants.map((g) => (g.principalKind === 'workspace' ? 'workspace' : `${g.principalKind}:${g.principalId}`)).join(', ')
+      }`,
+      `  endpoints: ${(state.endpoints ?? []).map((e) => `${e.kind} ${e.enabled ? 'on' : 'off'}`).join(', ') || 'defaults'}`,
+      '',
+      (state.agents ?? []).length === 0
+        ? '  no Agents on the roster'
+        : table(
+            ['agent', 'name', 'published'],
+            (state.agents ?? []).map((a) => [a.slug ?? '?', a.name ?? '', a.publishedVersion ? `v${a.publishedVersion}` : 'no']),
+          ),
+      ...(findings.length ? ['', 'findings:', ...findingLines(findings)] : []),
+    ]
+
+    return { data: state, text: lines.join('\n') }
+  },
+}
+
+const draft: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'draft',
+    args: [{ name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' }],
+    flags: { from: 'string' },
+    aliases: { f: 'from' },
+    summary: 'Stage a draft configuration from a JSON file, and report what blocks publishing',
+    examples: [
+      'frontera chat-app draft support-desk --from ./app.json',
+      'cat app.json | frontera chat-app draft support-desk --from -',
+    ],
+  },
+  async run(ctx) {
+    const ref = appRef(ctx, 'draft')
+    const from = flagString(ctx, 'from')
+    if (!from) throw new UsageError('missing --from', 'pass `--from ./config.json`, or `--from -` for stdin')
+    const configuration = await readConfiguration(from)
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const saved = (await api
+      .saveChatAppDraft(await resolveChatAppRef(api, ref), configuration)
+      .catch((err: unknown) => rethrowValidation(err, ref))) as {
+      findings?: Finding[]
+      updatedAt?: string
+    }
+
+    const findings = saved.findings ?? []
+    const blocked = findings.some((f) => f.level === 'error')
+    return {
+      data: saved,
+      text: [
+        `draft saved${saved.updatedAt ? ` ${saved.updatedAt}` : ''}`,
+        ...findingLines(findings),
+        blocked ? '  fix the errors above before publishing' : `  next: frontera chat-app publish ${ref}`,
+      ].join('\n'),
+    }
+  },
+}
+
+const publish: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'publish',
+    args: [{ name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' }],
+    flags: { from: 'string', validate: 'boolean' },
+    aliases: { f: 'from' },
+    summary: 'Publish the staged draft (or a file) as the live version',
+    examples: [
+      'frontera chat-app publish support-desk --validate',
+      'frontera chat-app publish support-desk',
+      'frontera chat-app publish support-desk --from ./app.json',
+    ],
+  },
+  async run(ctx) {
+    const ref = appRef(ctx, 'publish')
+    const from = flagString(ctx, 'from')
+    const dryRun = flagBool(ctx, 'validate')
+    const configuration = from ? await readConfiguration(from) : undefined
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const appId = await resolveChatAppRef(api, ref)
+    let result: { findings?: Finding[]; version?: { id?: string; version?: string } | null }
+    try {
+      result = (await api.publishChatApp(appId, {
+        ...(configuration !== undefined ? { configuration } : {}),
+        ...(dryRun ? { dryRun: true } : {}),
+      })) as typeof result
+    } catch (err) {
+      rethrowValidation(err, ref, configuration === undefined)
+    }
+
+    const findings = result.findings ?? []
+    const text = dryRun
+      ? [
+          findings.some((f) => f.level === 'error') ? 'not ready to publish' : 'ready to publish',
+          ...findingLines(findings),
+        ]
+      : [`published v${result.version?.version ?? '?'}  ${result.version?.id ?? ''}`.trim(), ...findingLines(findings)]
+    return { data: result, text: text.join('\n') }
+  },
+}
+
+const access: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'access',
+    args: [
+      { name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' },
+      {
+        name: 'grants',
+        required: true,
+        description: 'workspace, user:ID or group:ID, one or more — replaces the audience',
+      },
+    ],
+    flags: {},
+    summary: 'Replace who may open a Chat App',
+    examples: [
+      'frontera chat-app access support-desk workspace',
+      'frontera chat-app access help user:4b1f0c2e-8a7d-4c1b-9e2f-3a6d5c7b8e90',
+      'frontera chat-app access help group:9d3e2a1b-5c4f-4e6d-8b7a-0f1e2d3c4b5a',
+    ],
+  },
+  async run(ctx) {
+    const ref = appRef(ctx, 'access')
+    const specs = ctx.positional.slice(1)
+    // No empty form: zero grants closes the App to everyone, which is too
+    // large an effect for an argument someone forgot.
+    if (specs.length === 0) {
+      throw new UsageError('missing <grants>', 'pass `workspace`, or `user:<id>` / `group:<id>` — user ids come from `frontera chat-app members <app>`')
+    }
+    const grants = specs.map((spec) => {
+      if (spec === 'workspace') return { principalKind: 'workspace' as const }
+      const at = spec.indexOf(':')
+      const kind = spec.slice(0, at)
+      const id = spec.slice(at + 1)
+      if (at > 0 && id && (kind === 'user' || kind === 'group')) {
+        return { principalKind: kind as 'user' | 'group', principalId: id }
+      }
+      throw new UsageError(`"${spec}" is not a grant`, 'use `workspace`, `user:<userId>` or `group:<groupId>`')
+    })
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const rows = (await api.setChatAppAccess(await resolveChatAppRef(api, ref), grants)) as Array<{
+      principalKind?: string
+      principalId?: string
+    }>
+
+    return {
+      data: rows,
+      text: `access: ${
+        rows.map((g) => (g.principalKind === 'workspace' ? 'workspace' : `${g.principalKind}:${g.principalId}`)).join(', ') || 'nobody'
+      }`,
+    }
+  },
+}
+
+const endpoint: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'endpoint',
+    args: [
+      { name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' },
+      { name: 'kind', required: true, description: 'platform, standalone or widget' },
+      { name: 'state', required: true, description: 'on or off' },
+    ],
+    flags: {},
+    summary: 'Turn one of a Chat App’s endpoints on or off — effective on the next request',
+    examples: [
+      'frontera chat-app endpoint support-desk standalone on',
+      'frontera chat-app endpoint support-desk widget off',
+    ],
+  },
+  async run(ctx) {
+    const ref = appRef(ctx, 'endpoint')
+    const kind = ctx.positional[1]
+    const state = ctx.positional[2]
+    if (!kind || !(ENDPOINTS as readonly string[]).includes(kind)) {
+      throw new UsageError(kind ? `unknown endpoint "${kind}"` : 'missing <kind>', `one of: ${ENDPOINTS.join(', ')}`)
+    }
+    if (state !== 'on' && state !== 'off') {
+      throw new UsageError(state ? `"${state}" is not on or off` : 'missing <state>', `frontera chat-app endpoint ${ref} ${kind} on`)
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const row = (await api.setChatAppEndpoint(
+      await resolveChatAppRef(api, ref),
+      kind as (typeof ENDPOINTS)[number],
+      state === 'on',
+    )) as { kind?: string; enabled?: boolean }
+
+    return { data: row, text: `${row.kind ?? kind} ${row.enabled ? 'on' : 'off'}` }
+  },
+}
+
+const members: Command = {
+  meta: {
+    noun: 'chat-app',
+    verb: 'members',
+    args: [{ name: 'app', required: true, description: 'slug or id, from `frontera chat-app list`' }],
+    flags: {},
+    summary: 'List workspace members — the user ids `chat-app access` takes',
+    examples: ['frontera chat-app members support-desk', 'frontera chat-app members support-desk --json'],
+  },
+  async run(ctx) {
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const rows = (await api.chatAppMembers(await resolveChatAppRef(api, appRef(ctx, 'members')))) as Array<{
+      userId?: string
+      name?: string
+      email?: string
+      role?: string
+    }>
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No members in this workspace.'
+          : table(
+              ['name', 'email', 'role', 'grant'],
+              rows.map((m) => [m.name ?? '', m.email ?? '', m.role ?? '', `user:${m.userId ?? '?'}`]),
+            ),
+    }
+  },
+}
+
+export const chatAppCommands: Command[] = [list, create, get, draft, publish, access, endpoint, members]

package/src/commands/knowledge/upload-plan.ts

@@ -37,8 +37,8 @@ export function extensionOf(path: string): string {
   return dot === -1 ? '' : path.slice(dot).toLowerCase()
 }
 
-export function isAccepted(path: string): boolean {
-  return (ACCEPTED_EXTENSIONS as readonly string[]).includes(extensionOf(path))
+export function isAccepted(path: string, accepted: readonly string[] = ACCEPTED_EXTENSIONS): boolean {
+  return accepted.includes(extensionOf(path))
 }
 
 /** Content type for a path. Unknown extensions never reach here. */
@@ -50,6 +50,8 @@ export interface PlannedFile {
   path: string
   /** Why it is in the plan — decides how a rejection is reported. */
   source: 'named' | 'scanned'
+  /** For a scanned file, the directory the caller named that it was found under. */
+  root?: string
 }
 
 export interface UploadPlan {
@@ -69,16 +71,20 @@ export interface UploadPlan {
  * make directory upload unusable on any real machine. Both outcomes are
  * reported — the skipped count is printed, never silent.
  */
-export function planUploads(paths: string[]): UploadPlan {
+export function planUploads(
+  paths: string[],
+  /** The extensions the destination accepts. Knowledge's by default; Media Sets pass theirs. */
+  accepted: readonly string[] = ACCEPTED_EXTENSIONS,
+): UploadPlan {
   const files: PlannedFile[] = []
   const rejected: Array<{ path: string; reason: string }> = []
   let skippedByType = 0
   const seen = new Set<string>()
 
-  const push = (path: string, source: PlannedFile['source']): void => {
+  const push = (path: string, source: PlannedFile['source'], root?: string): void => {
     if (seen.has(path)) return
     seen.add(path)
-    files.push({ path, source })
+    files.push(root === undefined ? { path, source } : { path, source, root })
   }
 
   for (const path of paths) {
@@ -92,16 +98,16 @@ export function planUploads(paths: string[]): UploadPlan {
 
     if (info.isDirectory()) {
       for (const found of walk(path)) {
-        if (isAccepted(found)) push(found, 'scanned')
+        if (isAccepted(found, accepted)) push(found, 'scanned', path)
         else skippedByType += 1
       }
       continue
     }
 
-    if (!isAccepted(path)) {
+    if (!isAccepted(path, accepted)) {
       rejected.push({
         path,
-        reason: `unsupported type — accepted: ${ACCEPTED_EXTENSIONS.join(', ')}`,
+        reason: `unsupported type — accepted: ${accepted.join(', ')}`,
       })
       continue
     }