@frontera-sdk/cli 1.44.1 → 1.45.0

package/src/commands/blueprint/query.ts

@@ -0,0 +1,294 @@
+import { readFileSync } from 'node:fs'
+
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command } from '../types'
+
+/**
+ * Read rows through the ontology.
+ *
+ * The CLI could author an object type, bind it to a dataset revision and
+ * publish a release without ever seeing a row, so a binding that resolved to
+ * nothing was indistinguishable from one that worked — the authoring verbs all
+ * reported success either way. This is the verb that settles it.
+ *
+ * Reads resolve through the same granted slice as `blueprint list`, so what
+ * comes back here is exactly what an app or an agent will see at runtime.
+ * Nothing this returns is a preview of a wider set.
+ */
+
+/** Constructed per call: the credential is per-invocation, not per-process. */
+function api(ctx: { apiUrl: string; token: string }): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token)
+}
+
+/** `status:open` and `amount:>:1000` — the two forms worth typing by hand. */
+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
+  // rather than a punctuation language invented here to avoid it.
+  if (trimmed.startsWith('{')) {
+    try {
+      return JSON.parse(trimmed)
+    } catch (e) {
+      throw new UsageError(
+        `--where is not valid JSON: ${(e as Error).message}`,
+        'pass a where-node like \'{"property":"status","op":"eq","value":"open"}\', '
+        + 'or the shorthand <property>:<value>',
+      )
+    }
+  }
+
+  const parts = trimmed.split(':')
+  if (parts.length === 2) {
+    return { property: parts[0], op: 'eq', value: parts[1] }
+  }
+  if (parts.length === 3) {
+    return { property: parts[0], op: parts[1], value: parts[2] }
+  }
+  throw new UsageError(
+    `cannot read --where "${raw}"`,
+    'use <property>:<value>, <property>:<op>:<value>, or a JSON where-node',
+  )
+}
+
+export function parseOrder(raw: string): Array<{ property: string; dir: 'asc' | 'desc' }> {
+  return raw.split(',').map((clause) => {
+    const [property, dir = 'asc'] = clause.trim().split(':')
+    if (!property) throw new UsageError(`cannot read --order "${raw}"`, 'use <property>:asc or <property>:desc')
+    if (dir !== 'asc' && dir !== 'desc') {
+      throw new UsageError(`--order direction must be asc or desc, not "${dir}"`, `try ${property}:desc`)
+    }
+    return { property, dir }
+  })
+}
+
+/**
+ * Give the shorthand's value the type the property actually has.
+ *
+ * A flag is always a string, and the query compiler is strictly typed:
+ * `--where salesIdr:gt:9000000` reached it as `"9000000"` and came back
+ * "expected a finite number", so the shorthand could not filter a numeric
+ * column at all.
+ *
+ * Driven by the declared `dataType`, never by how the value LOOKS. This
+ * ontology has `cityCode` — a string whose every value parses as a number
+ * (`52.01`) — so guessing from the literal would have silently broken equality
+ * on it while appearing to fix the numeric case.
+ *
+ * An unknown property is left as written: the service names it better than a
+ * guess here would, and a property that is absent is the caller's real error.
+ */
+export function coerceWhereValue(value: unknown, dataType: string | undefined): unknown {
+  if (typeof value !== 'string') return value
+  if (dataType === 'number' || dataType === 'integer') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : value
+  }
+  if (dataType === 'boolean') {
+    if (value === 'true') return true
+    if (value === 'false') return false
+  }
+  return value
+}
+
+/** `{ property, op, value }` from the shorthand, retyped against the ontology. */
+export function typeWhereNode(node: unknown, types: Map<string, string>): unknown {
+  const condition = node as { property?: string; value?: unknown }
+  if (!condition || typeof condition !== 'object' || typeof condition.property !== 'string') return node
+  if (!('value' in condition)) return node
+  return { ...condition, value: coerceWhereValue(condition.value, types.get(condition.property)) }
+}
+
+export function parseLimit(raw: string): number {
+  const n = Number(raw)
+  // NaN would reach the service as `pageSize: null` and be ignored, returning
+  // the default page and reporting nothing wrong — so it is refused here.
+  if (!Number.isInteger(n) || n < 1) {
+    throw new UsageError(`--limit must be a positive whole number, not "${raw}"`, 'try --limit 20')
+  }
+  return n
+}
+
+/** A cell a terminal can show: objects and arrays collapse rather than sprawl. */
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+export const blueprintQuery: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'query',
+    args: [
+      {
+        name: 'apiName',
+        required: false,
+        description: 'object type to read, from `frontera blueprint list`; omit when using --file',
+      },
+    ],
+    flags: {
+      select: 'string',
+      where: 'string',
+      order: 'string',
+      limit: 'string',
+      'page-token': 'string',
+      file: 'string',
+    },
+    aliases: { f: 'file' },
+    summary: 'Read rows of an object type through the ontology',
+    examples: [
+      'frontera blueprint query Invoice --limit 5',
+      'frontera blueprint query Invoice --where status:open --select id,amount',
+      'frontera blueprint query Invoice --order amount:desc --limit 20',
+      'frontera blueprint query --file ./query.json --json',
+    ],
+  },
+
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    const file = flagString(ctx, 'file')
+
+    if (!apiName && !file) {
+      throw new UsageError(
+        'missing <apiName>',
+        'frontera blueprint list — then `frontera blueprint query <apiName>`',
+      )
+    }
+
+    // `--file` carries a whole QueryRequest, which is the only way to express
+    // a union, a searchAround or a nested boolean filter. The flags build the
+    // common case; they do not try to become the grammar.
+    let body: Parameters<PlatformApi['blueprintQuery']>[0]
+    if (file) {
+      const raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8')
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(raw)
+      } catch (e) {
+        throw new UsageError(
+          `${file === '-' ? 'stdin' : file} is not valid JSON: ${(e as Error).message}`,
+          'the file holds a QueryRequest: { "objectSet": { "type": "base", "objectType": "…" } }',
+        )
+      }
+      const doc = parsed as Record<string, unknown>
+      if (!doc.objectSet) {
+        throw new UsageError(
+          'the query document has no `objectSet`',
+          'the minimum is { "objectSet": { "type": "base", "objectType": "Invoice" } }',
+        )
+      }
+      body = doc as typeof body
+    } else {
+      const where = flagString(ctx, 'where')
+      let node = where ? parseWhere(where) : null
+
+      // 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('{')) {
+        const shape = (await api(ctx).blueprintObjectType(apiName!)) as {
+          properties?: Array<{ apiName?: string; dataType?: string }>
+        }
+        const types = new Map<string, string>()
+        for (const p of shape?.properties ?? []) {
+          if (p.apiName && p.dataType) types.set(p.apiName, p.dataType)
+        }
+        node = typeWhereNode(node, types)
+      }
+
+      body = {
+        objectSet: node
+          ? { type: 'filter', objectSet: { type: 'base', objectType: apiName }, where: node }
+          : { type: 'base', objectType: apiName },
+      }
+    }
+
+    const select = flagString(ctx, 'select')
+    if (select) body.select = select.split(',').map((s) => s.trim()).filter(Boolean)
+    const order = flagString(ctx, 'order')
+    if (order) body.orderBy = parseOrder(order)
+    const limit = flagString(ctx, 'limit')
+    if (limit) body.pageSize = parseLimit(limit)
+    const pageToken = flagString(ctx, 'page-token')
+    if (pageToken) body.pageToken = pageToken
+
+    const result = await api(ctx).blueprintQuery(body)
+    const rows = result.rows ?? []
+
+    if (rows.length === 0) {
+      return {
+        data: result,
+        // An empty result after a successful bind is the confusing case, so it
+        // 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'
+          + `  Check the binding with \`frontera blueprint get ${apiName ?? '<apiName>'}\`.`,
+      }
+    }
+
+    // Columns come from the first row: `select` fixes them when it is given,
+    // and without it the service decides, so echoing the row's own keys is the
+    // only ordering that matches what came back.
+    const columns = Object.keys(rows[0]!)
+    const more = result.nextPageToken
+      ? `\n\nMore rows. Continue with --page-token ${result.nextPageToken}`
+      : ''
+
+    return {
+      data: result,
+      text:
+        table(columns, rows.map((r) => columns.map((c) => cell(r[c]))))
+        + `\n\n${rows.length} row${rows.length === 1 ? '' : 's'}.${more}`,
+    }
+  },
+}
+
+export const blueprintInstance: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'instance',
+    args: [
+      { name: 'apiName', required: true, description: 'object type, from `frontera blueprint list`' },
+      { name: 'pk', required: true, description: 'primary key value of the record to read' },
+    ],
+    flags: {},
+    summary: 'Read one object by primary key',
+    examples: ['frontera blueprint instance Invoice INV-1042', 'frontera blueprint instance Invoice INV-1042 --json'],
+  },
+
+  async run(ctx) {
+    const [apiName, pk] = ctx.positional
+    if (!apiName) throw new UsageError('missing <apiName>', 'frontera blueprint list — then pass an api name')
+    if (!pk) {
+      throw new UsageError(
+        'missing <pk>',
+        `frontera blueprint query ${apiName} --limit 5 — to see primary keys`,
+      )
+    }
+
+    const instance = await api(ctx).blueprintInstance(apiName, pk)
+    if (!instance) {
+      throw new CliError(`no ${apiName} with primary key "${pk}"`, {
+        code: 'NOT_FOUND',
+        hint: `frontera blueprint query ${apiName} --limit 5 — to see which keys exist`,
+      })
+    }
+
+    const fields = instance as Record<string, unknown>
+    return {
+      data: instance,
+      text: table(
+        ['property', 'value'],
+        Object.entries(fields).map(([k, v]) => [k, cell(v)]),
+        [undefined, 80],
+      ),
+    }
+  },
+}

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

@@ -0,0 +1,334 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { table } from '../../table'
+import { resolveAgentRef } from '../agent/resolve'
+import { type Command } from '../types'
+
+/**
+ * What an agent may actually do.
+ *
+ * `agent apply` writes prompts, models, knowledge and skills, and stops here.
+ * The capability graph — which plugin operations an agent is allowed to call —
+ * was Console-only, so "configure an agent from a repo" was never true: the
+ * half that decides what the agent can DO could not be scripted at all.
+ *
+ * Its own noun rather than `agent capability …` because the registry is
+ * noun-and-verb, and because a capability is addressed by its own id: it
+ * belongs to an INSTALL and is granted TO an agent, so neither noun owns it.
+ *
+ * The one thing to know before using any of this: a grant STAGES onto the
+ * agent draft. Nothing reaches the running agent until `frontera agent
+ * publish`, which is the same rule `agent apply` follows and the reason both
+ * are safe to run against a live agent.
+ */
+
+/**
+ * Two endpoints, two shapes for the same thing.
+ *
+ * `/apps/:installId/capabilities` answers a catalog row — `displayName`,
+ * `name`, `kind`. `/apps/agents/:id/capabilities` answers a BINDING joined to
+ * that row and prefixes every borrowed field: `capabilityDisplayName`,
+ * `capabilityKind`. Reading only the short names printed a uuid where the name
+ * belongs and left `kind` blank, which is how this was found — by running it.
+ */
+interface CapabilityRow {
+  id?: string
+  capabilityId?: string
+  name?: string
+  displayName?: string
+  kind?: string
+  capabilityName?: string
+  capabilityDisplayName?: string
+  capabilityKind?: string
+  installId?: string
+  installName?: string
+  catalogKind?: string
+  accountMode?: string
+  requiresApproval?: boolean
+  requiresApprovalOverride?: boolean | null
+}
+
+function rowId(row: CapabilityRow): string {
+  return row.capabilityId ?? row.id ?? ''
+}
+
+function rowLabel(row: CapabilityRow): string {
+  return row.capabilityDisplayName ?? row.displayName
+    ?? row.capabilityName ?? row.name ?? rowId(row)
+}
+
+function rowKind(row: CapabilityRow): string {
+  return row.capabilityKind ?? row.kind ?? ''
+}
+
+const list: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'list',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'List the capabilities one agent holds',
+    examples: ['frontera capability list support-bot', 'frontera capability list support-bot --json'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const agentId = await resolveAgentRef(api, ref)
+    const rows = (await api.agentCapabilities(agentId)) as CapabilityRow[]
+
+    if (rows.length === 0) {
+      return {
+        data: rows,
+        // Not an error state, and the most common one: an agent with no
+        // capabilities can still answer questions, it just cannot act.
+        text:
+          `${ref} holds no capabilities — it can read and answer, but cannot call a plugin.\n`
+          + '  `frontera capability available <plugin>` lists what an install offers.',
+      }
+    }
+
+    return {
+      data: rows,
+      text: table(
+        ['capability', 'kind', 'install', 'mode', 'id'],
+        rows.map((r) => [
+          rowLabel(r),
+          rowKind(r),
+          r.installName ?? r.catalogKind ?? r.installId ?? '',
+          r.accountMode ?? '',
+          rowId(r),
+        ]),
+        [34, 10, 24, 12, undefined],
+      ),
+    }
+  },
+}
+
+const available: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'available',
+    args: [{ name: 'plugin', required: true, description: 'plugin install id, from `frontera plugin list`' }],
+    flags: {},
+    summary: 'List the capabilities one installed plugin offers',
+    examples: ['frontera capability available <installId>'],
+  },
+  async run(ctx) {
+    const installId = ctx.positional[0]
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list — then pass an install id')
+
+    const rows = (await new PlatformApi(ctx.apiUrl, ctx.token)
+      .pluginCapabilities(installId)) as CapabilityRow[]
+
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? 'This install exposes no capabilities.\n'
+          + '  `frontera plugin verify <installId>` — an unconnected install discovers none.'
+        : table(
+            ['capability', 'kind', 'id'],
+            rows.map((r) => [rowLabel(r), rowKind(r), rowId(r)]),
+            [40, 12, undefined],
+          ),
+    }
+  },
+}
+
+const grant: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'grant',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'capability', required: true, description: 'capability id, from `frontera capability available`' },
+    ],
+    flags: {},
+    summary: 'Give an agent one capability — staged onto its draft',
+    examples: ['frontera capability grant support-bot <capabilityId>'],
+  },
+  async run(ctx) {
+    const [ref, capabilityId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+    if (!capabilityId) {
+      throw new UsageError(
+        'missing <capability>',
+        'frontera capability available <installId> — to see capability ids',
+      )
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const agentId = await resolveAgentRef(api, ref)
+    const result = await api.grantAgentCapability(agentId, capabilityId)
+
+    return {
+      data: result,
+      // Both facts stated every time. The staging is why nothing appears to
+      // happen to the live agent, and the auto-bind is why an install the
+      // caller never mentioned shows up in `agent diff`.
+      text:
+        `Granted to the ${ref} draft.\n`
+        + '  The parent install was bound too, if it was not already.\n\n'
+        + 'Next:\n'
+        + `  frontera agent diff ${ref}\n`
+        + `  frontera agent publish ${ref}   # nothing reaches the running agent until this`,
+    }
+  },
+}
+
+const revoke: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'revoke',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'capability', required: true, description: 'capability id, from `frontera capability list`' },
+    ],
+    flags: {},
+    summary: 'Take one capability away from an agent — staged onto its draft',
+    examples: ['frontera capability revoke support-bot <capabilityId>'],
+  },
+  async run(ctx) {
+    const [ref, capabilityId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+    if (!capabilityId) {
+      throw new UsageError('missing <capability>', `frontera capability list ${ref}`)
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const agentId = await resolveAgentRef(api, ref)
+    const result = await api.revokeAgentCapability(agentId, capabilityId)
+
+    return {
+      data: result,
+      text:
+        `Revoked on the ${ref} draft.\n`
+        + '  The install binding is left in place — revoking one capability is not uninstalling.\n\n'
+        + `Publish it with \`frontera agent publish ${ref}\`.`,
+    }
+  },
+}
+
+const installs: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'installs',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'List the plugin installs an agent is bound to',
+    examples: ['frontera capability installs support-bot'],
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const rows = (await api.agentInstalls(await resolveAgentRef(api, ref))) as Array<{
+      install?: { installName?: string }
+      catalog?: { name?: string; kind?: string }
+      accountMode?: string
+      enabled?: boolean
+      agentOwnedConnected?: boolean
+      installId?: string
+    }>
+
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? `${ref} is bound to no plugin installs.`
+        : table(
+            // `install` and `catalog` are NESTED here, unlike every other row
+            // this noun renders — reading the name off the top level printed
+            // "?" for every install.
+            ['install', 'mode', 'connected', 'id'],
+            rows.map((r) => [
+              String(r.install?.installName ?? r.catalog?.name ?? r.catalog?.kind ?? '?'),
+              String(r.accountMode ?? ''),
+              // `enabled` is the binding switch; whether the shared credential
+              // actually resolved is the thing that decides if a call works.
+              String(r.enabled === false ? 'disabled' : (r.agentOwnedConnected ?? '')),
+              String(r.installId ?? ''),
+            ]),
+            [30, 14, 11, undefined],
+          ),
+    }
+  },
+}
+
+const bind: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'bind',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'plugin', required: true, description: 'plugin install id, from `frontera plugin list`' },
+    ],
+    flags: { 'end-user': 'boolean' },
+    summary: 'Bind a whole plugin install to an agent, without granting capabilities',
+    examples: [
+      'frontera capability bind support-bot <installId>',
+      'frontera capability bind support-bot <installId> --end-user',
+    ],
+  },
+  async run(ctx) {
+    const [ref, installId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+    if (!installId) throw new UsageError('missing <plugin>', 'frontera plugin list')
+
+    // Not a preference. `agent_owned` reaches data through one credential the
+    // workspace holds; `end_user` makes every caller connect their own, and
+    // switching later does not migrate anything already connected.
+    const accountMode = ctx.flags['end-user'] === true ? 'end_user' : 'agent_owned'
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const agentId = await resolveAgentRef(api, ref)
+    const result = await api.bindAgentInstall(agentId, installId, accountMode)
+
+    return {
+      data: result,
+      text:
+        `Bound ${installId} to ${ref} as ${accountMode}.\n`
+        + '  Binding grants nothing on its own — `frontera capability grant` is what lets the\n'
+        + '  agent call an operation.',
+    }
+  },
+}
+
+const unbind: Command = {
+  meta: {
+    noun: 'capability',
+    verb: 'unbind',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'plugin', required: true, description: 'plugin install id' },
+    ],
+    flags: {},
+    summary: 'Unbind a plugin install from an agent, with the capabilities it carried',
+    examples: ['frontera capability unbind support-bot <installId>'],
+  },
+  async run(ctx) {
+    const [ref, installId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list — then pass an id or slug')
+    if (!installId) throw new UsageError('missing <plugin>', `frontera capability installs ${ref}`)
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const agentId = await resolveAgentRef(api, ref)
+    const result = await api.unbindAgentInstall(agentId, installId).catch((e: unknown) => {
+      throw new CliError((e as Error).message, {
+        code: 'FAILURE',
+        hint: `frontera capability installs ${ref} — to see what is bound`,
+      })
+    })
+
+    return {
+      data: result,
+      text: `Unbound ${installId} from ${ref}. Its capabilities went with it.`,
+    }
+  },
+}
+
+export const capabilityCommands: Command[] = [list, available, installs, grant, revoke, bind, unbind]
+
+/** Exported for the shape test — the two projections must both resolve. */
+export const rowLabelForTest = rowLabel