@frontera-sdk/cli 0.1.0 → 1.43.6

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

@@ -1,7 +1,10 @@
 import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
-import type { Command } from '../types'
+import { resolveAgentRef } from '../agent/resolve'
+import { flagString, type Command } from '../types'
+import { renderUploadSummary, summarizeUploads, uploadAll } from './upload-batch'
+import { planUploads } from './upload-plan'
 
 interface KnowledgeRow {
   id?: string
@@ -10,19 +13,25 @@ interface KnowledgeRow {
   description?: string
 }
 
-/** 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 me = await client.whoami()
+/** 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',
     })
   }
-  const rows = (await client.knowledgeBases(me.workspaceId)) as KnowledgeRow[]
+  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 rows = (await client.knowledgeBases(workspaceId)) as KnowledgeRow[]
   const match = rows.find((k) => (k.name ?? '').toLowerCase() === ref.toLowerCase())
   if (match?.id) return match.id
 
@@ -45,14 +54,8 @@ const list: Command = {
     const api = new PlatformApi(ctx.apiUrl, ctx.token)
     // The route takes the workspace explicitly, and a key holder cannot see
     // its own workspace id from anywhere else — hence /v1/whoami.
-    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',
-      })
-    }
-    const rows = (await api.knowledgeBases(me.workspaceId)) as KnowledgeRow[]
+    const workspaceId = await requireWorkspaceId(api)
+    const rows = (await api.knowledgeBases(workspaceId)) as KnowledgeRow[]
     return {
       data: rows,
       text:
@@ -108,20 +111,259 @@ const sources: Command = {
   },
 }
 
+const create: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'create',
+    args: [{ name: 'name', required: true, description: 'base name — lowercase, the value every other knowledge command takes' }],
+    flags: { description: 'string' },
+    summary: 'Create a knowledge base',
+    examples: [
+      'frontera knowledge create logistics-policies',
+      'frontera knowledge create policies --description "SOPs and tariffs"',
+    ],
+  },
+  async run(ctx) {
+    const name = ctx.positional[0]
+    if (!name) {
+      throw new UsageError('missing <name>', 'frontera knowledge create <name> [--description <text>]')
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const workspaceId = await requireWorkspaceId(api)
+
+    // Checked here rather than left to the unique constraint: the service
+    // answers a duplicate with a bare CONFLICT, whose generic hint ("resolve
+    // what conflicted") sends a caller looking for a race that did not happen.
+    const existing = (await api.knowledgeBases(workspaceId)) as KnowledgeRow[]
+    if (existing.some((k) => (k.name ?? '').toLowerCase() === name.toLowerCase())) {
+      throw new CliError(`a knowledge base named "${name}" already exists`, {
+        code: 'CONFLICT',
+        hint: `upload into it with \`frontera knowledge upload ${name} <path…>\``,
+      })
+    }
+
+    const description = flagString(ctx, 'description')
+    const created = (await api.createKnowledgeBase(
+      workspaceId,
+      description ? { name, description } : { name },
+    )) as { data?: KnowledgeRow } | KnowledgeRow
+    const row = ((created as { data?: KnowledgeRow }).data ?? created) as KnowledgeRow
+
+    return {
+      data: row,
+      text: [
+        `created ${row.name ?? name}${row.id ? `  ${row.id}` : ''}`,
+        `  next: frontera knowledge upload ${row.name ?? name} <path…>`,
+      ].join('\n'),
+    }
+  },
+}
+
+const upload: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'upload',
+    args: [
+      { name: 'base', required: true, description: 'knowledge base name or id' },
+      { name: 'path...', required: true, description: 'files or directories; directories are walked, unsupported types skipped' },
+    ],
+    flags: { strategy: 'string' },
+    summary: 'Upload files into a knowledge base',
+    examples: [
+      'frontera knowledge upload logistics-policies ./policies',
+      'frontera knowledge upload logistics-policies tariffs.pdf sop.md',
+      'frontera knowledge upload logistics-policies ./scans --strategy ocr',
+    ],
+  },
+  async run(ctx) {
+    const [ref, ...paths] = ctx.positional
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+    if (paths.length === 0) {
+      throw new UsageError(
+        'missing <path...>',
+        'frontera knowledge upload <base> <file-or-directory…>',
+      )
+    }
+
+    const strategy = flagString(ctx, 'strategy')
+    if (strategy && !['auto', 'text', 'ocr'].includes(strategy)) {
+      throw new UsageError(
+        `unknown --strategy "${strategy}"`,
+        'auto (default), text, or ocr — ocr needs an OCR engine configured on the base',
+      )
+    }
+
+    const plan = planUploads(paths)
+    if (plan.rejected.length > 0) {
+      // A path the caller NAMED and cannot be uploaded is a mistake in the
+      // command, so nothing is uploaded — a batch half-run on a typo leaves the
+      // base in a state the caller did not ask for and cannot infer.
+      const first = plan.rejected[0]!
+      throw new UsageError(
+        `cannot upload ${first.path}: ${first.reason}`,
+        plan.rejected.length > 1
+          ? `${plan.rejected.length} named paths are unusable — fix them, or pass a directory and let unsupported types be skipped`
+          : '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 api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(api, ref)
+    const outcomes = await uploadAll(api, baseId, plan.files, strategy)
+    const summary = summarizeUploads(ref, baseId, outcomes, plan)
+
+    // Nothing landed: the mechanism is wrong, not the batch. Fail so the exit
+    // code says so, and name the first cause rather than a count.
+    if (summary.uploaded === 0) {
+      const first = outcomes.find((o) => o.status === 'failed')
+      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',
+      })
+    }
+
+    return { data: summary, text: renderUploadSummary(summary) }
+  },
+}
+
+const attach: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'attach',
+    args: [
+      { name: 'base', required: true, description: 'knowledge base name or id' },
+      { name: 'agent', required: true, description: 'agent slug or id, from `frontera agent list`' },
+    ],
+    flags: {},
+    summary: 'Give an agent access to a knowledge base',
+    examples: ['frontera knowledge attach logistics-policies ava'],
+  },
+  async run(ctx) {
+    const [baseRef, agentRef] = ctx.positional
+    if (!baseRef) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+    if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(api, baseRef)
+    const agentId = await resolveAgentRef(api, agentRef)
+    await api.attachKnowledgeAgent(baseId, agentId)
+
+    return {
+      data: { baseId, agentId, attached: true },
+      text: [
+        `attached ${baseRef} to ${agentRef}`,
+        // Attachment is what makes knowledge reachable — including from an
+        // automation, which has no knowledge capability of its own and reads a
+        // corpus only through an agent that has one attached.
+        `  verify: frontera agent get ${agentRef}`,
+      ].join('\n'),
+    }
+  },
+}
+
+const detach: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'detach',
+    args: [
+      { name: 'base', required: true, description: 'knowledge base name or id' },
+      { name: 'agent', required: true, description: 'agent slug or id' },
+    ],
+    flags: {},
+    summary: 'Take an agent’s access to a knowledge base away',
+    examples: ['frontera knowledge detach logistics-policies ava'],
+  },
+  async run(ctx) {
+    const [baseRef, agentRef] = ctx.positional
+    if (!baseRef) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+    if (!agentRef) throw new UsageError('missing <agent>', 'frontera agent list — then pass a slug or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(api, baseRef)
+    const agentId = await resolveAgentRef(api, agentRef)
+    await api.detachKnowledgeAgent(baseId, agentId)
+
+    return {
+      data: { baseId, agentId, attached: false },
+      // Said explicitly because the reverse — deleting the corpus — is what a
+      // reader might assume from a word like detach.
+      text: `detached ${baseRef} from ${agentRef} — the base and its sources are unchanged`,
+    }
+  },
+}
+
+const agents: Command = {
+  meta: {
+    noun: 'knowledge',
+    verb: 'agents',
+    args: [{ name: 'base', required: true, description: 'knowledge base name or id' }],
+    flags: {},
+    summary: 'List the agents that can read one knowledge base',
+    examples: ['frontera knowledge agents logistics-policies'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge list — then pass a name or id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const baseId = await resolveKnowledgeRef(api, ref)
+    const rows = (await api.knowledgeAttachments(baseId)) as Array<Record<string, unknown>>
+
+    // The attachment row carries only `agentId`, so the slug — the value every
+    // other agent command takes — has to be looked up. Worth one extra request:
+    // a table of bare uuids cannot be acted on without a second command.
+    const slugs = new Map<string, string>()
+    if (rows.length > 0) {
+      const agentRows = (await api.agents().catch(() => [])) as Array<{
+        id?: string
+        agentId?: string
+        name?: string
+      }>
+      for (const a of agentRows) {
+        if (a.id && (a.agentId || a.name)) slugs.set(a.id, a.agentId ?? a.name ?? '')
+      }
+    }
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? `No agent can read ${ref} — attach one with \`frontera knowledge attach ${ref} <agent>\`.`
+          : table(
+              ['agent', 'id'],
+              rows.map((r) => {
+                const id = String(r.agentId ?? '')
+                // An agent still in `configuring` is absent from `agent list`,
+                // so print the id rather than a "?" that reads as corruption.
+                return [slugs.get(id) ?? id, id]
+              }),
+            ),
+    }
+  },
+}
+
 /**
- * `upload` is the strongest case for this noun existing at all — nobody wants
- * to drag two hundred PDFs into a browser — and is reserved rather than
- * half-built: it needs per-file outcome reporting so one unreadable file does
- * not fail a batch, which is the whole reason to prefer it over the UI.
+ * `delete` stays reserved.
+ *
+ * Deleting a base destroys its chunks and every agent attachment with it, and
+ * the route takes no confirmation of what is about to be lost — so the CLI
+ * would be the easiest way to do the most damage. It waits for the count of
+ * what will go with it.
  */
-const RESERVED = 'knowledge writes are not available in this release; list and sources are read-only'
+const RESERVED = 'deleting a knowledge base is not available in this release; delete it from the Console'
 
 const reserved: Command[] = (
-  [
-    ['create', 'Create a knowledge base'],
-    ['upload', 'Upload files into a knowledge base'],
-    ['delete', 'Delete a knowledge base'],
-  ] as const
+  [['delete', 'Delete a knowledge base']] as const
 ).map(([verb, summary]) => ({
   meta: {
     noun: 'knowledge',
@@ -137,4 +379,13 @@ const reserved: Command[] = (
   },
 }))
 
-export const knowledgeCommands: Command[] = [list, sources, ...reserved]
+export const knowledgeCommands: Command[] = [
+  list,
+  sources,
+  create,
+  upload,
+  attach,
+  detach,
+  agents,
+  ...reserved,
+]

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

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs'
+
+import { table } from '../../table'
+import { mimeFor, type PlannedFile, type UploadPlan } from './upload-plan'
+
+export interface UploadOutcome {
+  file: string
+  status: 'uploaded' | 'failed'
+  sourceId?: string
+  error?: string
+}
+
+/** What `uploadAll` needs from `PlatformApi`, so a test can supply it. */
+export interface SourceUploader {
+  uploadKnowledgeSource(
+    baseId: string,
+    file: { bytes: Uint8Array; filename: string; mime: string },
+    opts?: { extractionStrategy?: string },
+  ): Promise<{ id?: string; status?: string }>
+}
+
+/**
+ * Four at a time.
+ *
+ * Each upload is a whole file over the wire followed by an S3 put, so serial
+ * uploads make a 200-file seed minutes of mostly waiting. Four keeps the burst
+ * small enough that a wrong credential or a spent quota shows up in a short
+ * report rather than after 200 attempts.
+ */
+export const UPLOAD_CONCURRENCY = 4
+
+export function basename(path: string): string {
+  const slash = path.lastIndexOf('/')
+  return slash === -1 ? path : path.slice(slash + 1)
+}
+
+/**
+ * Upload every planned file, and report each one.
+ *
+ * A failure NEVER ends the batch — that is the whole reason to prefer this over
+ * the browser upload it replaces, where one unreadable file in two hundred
+ * meant starting over. Outcomes come back in plan order regardless of the order
+ * they finished in, so two runs of the same directory are comparable.
+ */
+export async function uploadAll(
+  api: SourceUploader,
+  baseId: string,
+  files: PlannedFile[],
+  strategy?: string,
+  readBytes: (path: string) => Uint8Array = (p) => new Uint8Array(readFileSync(p)),
+): Promise<UploadOutcome[]> {
+  const outcomes: UploadOutcome[] = new Array(files.length)
+  let next = 0
+
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = next++
+      const planned = files[index]
+      if (!planned) return
+      try {
+        const source = await api.uploadKnowledgeSource(
+          baseId,
+          {
+            bytes: readBytes(planned.path),
+            filename: basename(planned.path),
+            mime: mimeFor(planned.path),
+          },
+          strategy ? { extractionStrategy: strategy } : {},
+        )
+        outcomes[index] = {
+          file: planned.path,
+          status: 'uploaded',
+          ...(source.id ? { sourceId: source.id } : {}),
+        }
+      } catch (err) {
+        outcomes[index] = {
+          file: planned.path,
+          status: 'failed',
+          error: err instanceof Error ? err.message : String(err),
+        }
+      }
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(UPLOAD_CONCURRENCY, files.length) }, () => worker()),
+  )
+  return outcomes
+}
+
+export interface UploadSummary {
+  base: string
+  baseId: string
+  uploaded: number
+  failed: number
+  skippedByType: number
+  sources: UploadOutcome[]
+}
+
+export function summarizeUploads(
+  base: string,
+  baseId: string,
+  outcomes: UploadOutcome[],
+  plan: UploadPlan,
+): UploadSummary {
+  return {
+    base,
+    baseId,
+    uploaded: outcomes.filter((o) => o.status === 'uploaded').length,
+    failed: outcomes.filter((o) => o.status === 'failed').length,
+    skippedByType: plan.skippedByType,
+    sources: outcomes,
+  }
+}
+
+/**
+ * The text a person reads.
+ *
+ * Failures lead. A partial batch exits 0 — the per-file report IS the useful
+ * answer, and a non-zero exit tells a caller not to parse stdout at all — so
+ * the count of what did not land has to be the first thing on the page rather
+ * than a column someone has to notice.
+ */
+export function renderUploadSummary(summary: UploadSummary): string {
+  const lines: string[] = []
+  const total = summary.sources.length
+
+  if (summary.failed > 0) lines.push(`${summary.failed} of ${total} FAILED — see below`)
+  lines.push(
+    `uploaded ${summary.uploaded} file(s) into ${summary.base}` +
+      (summary.skippedByType > 0
+        ? `, skipped ${summary.skippedByType} of an unsupported type`
+        : ''),
+  )
+  lines.push(
+    table(
+      ['file', 'status', 'detail'],
+      summary.sources.map((o) => [basename(o.file), o.status, o.error ?? o.sourceId ?? '']),
+      [50, undefined, 60],
+    ),
+  )
+  // Ingestion is queued, not done: chunk counts appear minutes later, and a
+  // caller that tests retrieval immediately concludes the upload failed.
+  lines.push(`  ingestion runs asynchronously — frontera knowledge sources ${summary.base}`)
+  return lines.join('\n')
+}

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

@@ -0,0 +1,127 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Which file types the ingestion pipeline accepts.
+ *
+ * A mirror of `packages/service/src/internal/knowledge/accepted-file-types.ts`,
+ * which stays the authority — this exists so a 200-file directory does not
+ * become 200 rejected requests, and so an explicitly named `.zip` fails before
+ * anything is uploaded. Drift makes the CLI stricter or chattier, never more
+ * permissive: the service re-checks every file it is sent.
+ */
+export const ACCEPTED_EXTENSIONS = [
+  '.pdf',
+  '.docx',
+  '.xlsx',
+  '.xls',
+  '.md',
+  '.markdown',
+  '.txt',
+  '.csv',
+] as const
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.xls': 'application/vnd.ms-excel',
+  '.md': 'text/markdown',
+  '.markdown': 'text/markdown',
+  '.txt': 'text/plain',
+  '.csv': 'text/csv',
+}
+
+export function extensionOf(path: string): string {
+  const dot = path.lastIndexOf('.')
+  return dot === -1 ? '' : path.slice(dot).toLowerCase()
+}
+
+export function isAccepted(path: string): boolean {
+  return (ACCEPTED_EXTENSIONS as readonly string[]).includes(extensionOf(path))
+}
+
+/** Content type for a path. Unknown extensions never reach here. */
+export function mimeFor(path: string): string {
+  return MIME_BY_EXTENSION[extensionOf(path)] ?? 'application/octet-stream'
+}
+
+export interface PlannedFile {
+  path: string
+  /** Why it is in the plan — decides how a rejection is reported. */
+  source: 'named' | 'scanned'
+}
+
+export interface UploadPlan {
+  files: PlannedFile[]
+  /** Named paths that cannot be uploaded, with the reason. */
+  rejected: Array<{ path: string; reason: string }>
+  /** Count of scanned files skipped for their type. Not an error. */
+  skippedByType: number
+}
+
+/**
+ * Turn the paths a caller named into the files to upload.
+ *
+ * A named path and a scanned one are treated differently on purpose. Naming
+ * `policy.zip` is a mistake worth failing on; finding `.DS_Store` while walking
+ * a directory the caller pointed at is not, and failing the run for it would
+ * 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 {
+  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 => {
+    if (seen.has(path)) return
+    seen.add(path)
+    files.push({ path, source })
+  }
+
+  for (const path of paths) {
+    let info: ReturnType<typeof statSync>
+    try {
+      info = statSync(path)
+    } catch {
+      rejected.push({ path, reason: 'no such file or directory' })
+      continue
+    }
+
+    if (info.isDirectory()) {
+      for (const found of walk(path)) {
+        if (isAccepted(found)) push(found, 'scanned')
+        else skippedByType += 1
+      }
+      continue
+    }
+
+    if (!isAccepted(path)) {
+      rejected.push({
+        path,
+        reason: `unsupported type — accepted: ${ACCEPTED_EXTENSIONS.join(', ')}`,
+      })
+      continue
+    }
+    push(path, 'named')
+  }
+
+  // Sorted so a re-run reports in the same order, which is what makes two runs
+  // comparable at all.
+  files.sort((a, b) => a.path.localeCompare(b.path))
+  return { files, rejected, skippedByType }
+}
+
+/** Depth-first walk, dotfiles and dot-directories excluded. */
+function walk(dir: string): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...walk(path))
+    else if (entry.isFile()) out.push(path)
+  }
+  return out
+}