@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/blueprint/editable.ts

@@ -40,7 +40,7 @@ export function nextEditableSelection(
   const base = selection.set ?? [...current]
   const removed = new Set(selection.remove ?? [])
   const next = new Set([...base, ...(selection.add ?? [])].filter((name) => !removed.has(name)))
-  return [...next].sort()
+  return [...next].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 function api(ctx: CommandContext): BlueprintAuthoringApi {
@@ -93,7 +93,7 @@ export const blueprintEditable: Command = {
     // the way out. Mapping them through the property ids again read every one
     // as unknown and reported an empty set — which would have let `--add` post
     // a set containing only the addition, silently dropping the rest.
-    const current = [...detail.editableProperties].sort()
+    const current = [...detail.editableProperties].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 
     if (!hasSet && add.length === 0 && remove.length === 0) {
       return {
@@ -119,7 +119,7 @@ export const blueprintEditable: Command = {
         `${unknown.join(', ')} ${unknown.length === 1 ? 'is not a property' : 'are not properties'} of "${apiName}".`,
         {
           code: 'USAGE',
-          hint: `Properties: ${[...known].sort().join(', ')}`,
+          hint: `Properties: ${[...known].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).join(', ')}`,
         },
       )
     }

package/src/commands/blueprint/get.ts

@@ -124,7 +124,7 @@ export const blueprintGet: Command = {
       },
     ],
     flags: {},
-    summary: 'Show one object type: its properties, relations and metrics',
+    summary: 'Show one object type: its id, properties, relations and metrics',
     examples: ['frontera blueprint get Shipment', 'frontera blueprint get shipment --json'],
   },
 
@@ -221,6 +221,8 @@ export const blueprintGet: Command = {
     const heading = [apiName, type.displayName].filter(Boolean)
     const lines = [
       heading[1] && heading[1] !== heading[0] ? `${heading[0]} — ${heading[1]}` : String(heading[0]),
+      // The runtime's id: what a hard-coded id in an App, a workflow or a test has to equal.
+      `  id ${selfId || (types.ok ? '(not in the object-type catalog)' : `(unavailable: ${types.unavailable})`)}`,
       ...(type.description ? ['', type.description] : []),
       '',
       `Properties (${props.length})`,
@@ -254,7 +256,9 @@ export const blueprintGet: Command = {
 
     return {
       data: {
-        objectType: type,
+        // `id` from the organization catalog; null when it could not be read or does not list the type.
+        objectType: { ...type, id: selfId || null },
+        id: selfId || null,
         properties: props,
         // `null` rather than `[]` for an unreadable section, and a sibling
         // field saying why. A consumer that treats absence as emptiness now has

package/src/commands/blueprint/grants.ts

@@ -25,9 +25,11 @@ async function resolveSubject(
   const byId = candidates.find((candidate) => candidate.id === nameOrId)
   if (byId?.id) return { id: byId.id, name: byId.name ?? byId.id }
 
-  const matches = candidates.filter((candidate) =>
-    candidate.name === nameOrId
-    || (subject === 'workspace' && (candidate as { slug?: string }).slug === nameOrId))
+  // An Agent by its slug too (`agentId`, `dispatcher`), as every other command names it; a
+  // workspace by its slug. A slug names one, so it wins over a display name that matches.
+  const slugOf = (candidate: { slug?: string; agentId?: string }) => (subject === 'workspace' ? candidate.slug : candidate.agentId ?? candidate.slug)
+  const bySlug = candidates.filter((candidate) => slugOf(candidate as { slug?: string; agentId?: string }) === nameOrId)
+  const matches = bySlug.length ? bySlug : candidates.filter((candidate) => candidate.name === nameOrId)
   const only = matches.length === 1 ? matches[0] : undefined
   if (only?.id) return { id: only.id, name: only.name ?? only.id }
   if (matches.length > 1) {
@@ -42,11 +44,47 @@ async function resolveSubject(
   throw new CliError(`No ${subject} named "${nameOrId}" in this organization.`, {
     code: 'NOT_FOUND',
     hint: candidates.length
-      ? `Known ${subject}s: ${candidates.map((candidate) => candidate.name).filter(Boolean).join(', ')}`
+      ? `Known ${subject}s: ${candidates.map((candidate) => { const slug = slugOf(candidate as { slug?: string; agentId?: string }); return slug && slug !== candidate.name ? `${slug} (${candidate.name})` : candidate.name }).filter(Boolean).join(', ')}`
       : `No ${subject}s are visible to this credential.`,
   })
 }
 
+/**
+ * `--permissions`, as the grant's whole list: `read` always, `read_sensitive`
+ * the only other one. A workspace's only: an Agent's clearance is its
+ * bindings.json, and a revoke takes the whole grant.
+ */
+export function grantPermissions(raw: string | boolean | undefined, subject: string, revoke: boolean): string[] | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== 'string' || !raw.trim()) throw new CliError('--permissions takes a list: read,read_sensitive', { code: 'USAGE', hint: 'frontera blueprint grant workspace <name> <apiName…> --permissions read,read_sensitive' })
+  if (subject !== 'workspace') throw new CliError('--permissions is for a workspace grant', { code: 'USAGE', hint: 'an Agent\'s clearance over sensitive fields is `read_sensitive` in its bindings.json' })
+  if (revoke) throw new CliError('--revoke takes the whole grant; --permissions sets what a grant gives', { code: 'USAGE', hint: 'to keep only read, grant again with --permissions read' })
+  const given = raw.split(',').map((p) => p.trim()).filter(Boolean)
+  const unknown = given.filter((p) => p !== 'read' && p !== 'read_sensitive')
+  if (unknown.length) throw new CliError(`${unknown.join(', ')} ${unknown.length === 1 ? 'is not a permission' : 'are not permissions'} a workspace grant takes`, { code: 'USAGE', hint: 'the permissions are read and read_sensitive' })
+  return ['read', ...(given.includes('read_sensitive') ? ['read_sensitive'] : [])]
+}
+
+/**
+ * What a grant without `--permissions` sends, per object type: each grant
+ * replaces the whole permission list, so `read` plus whatever the grant
+ * already holds (`act`, `read_sensitive`), never `read` alone over a grant
+ * that had more. `kept` names what was kept, by object type.
+ */
+export function keptPermissions(apiNames: string[], current: Array<{ objectTypeApiName?: string; permissions?: string[] }>): { send: Map<string, string[] | undefined>; kept: Record<string, string[]> } {
+  const send = new Map<string, string[] | undefined>()
+  const kept: Record<string, string[]> = {}
+  for (const apiName of apiNames) {
+    const held = current.find((g) => g.objectTypeApiName === apiName)?.permissions ?? []
+    const extras = [...new Set(held.filter((p) => p !== 'read'))].sort()
+    if (extras.length) {
+      send.set(apiName, ['read', ...extras])
+      kept[apiName] = extras
+    } else send.set(apiName, undefined)
+  }
+  return { send, kept }
+}
+
 export const blueprintGrant: Command = {
   meta: {
     noun: 'blueprint',
@@ -56,10 +94,15 @@ export const blueprintGrant: Command = {
       { name: 'name', required: false, description: 'Workspace or agent, by name or id' },
       { name: 'apiName...', required: false, description: 'One or more object type API names' },
     ],
-    flags: { revoke: 'boolean' },
+    flags: { revoke: 'boolean', permissions: 'string' },
     summary: 'Grant or revoke an object type for a workspace or an agent',
+    details: [
+      '`--permissions read,read_sensitive` gives a workspace clearance over the type\'s confidential and restricted fields, for the workflows, Functions and Apps that read through it (`read` is always included; `--permissions` sets the grant\'s whole list). An Agent\'s clearance is its bindings.json. In a local project, blueprint/workspace-grants.yaml declares it and `frontera local dev` applies it.',
+      'Without `--permissions`, a grant keeps what it already holds: read, plus the grant\'s `read_sensitive` or an Agent\'s `act` (submit Actions), and the output says what it kept. To take one away: `--permissions read` for a workspace; for an Agent, revoke the grant and grant it again.',
+    ],
     examples: [
       'frontera blueprint grant workspace Ops Customer Policy',
+      'frontera blueprint grant workspace Ops Customer --permissions read_sensitive',
       'frontera blueprint grant agent "Claims bot" Customer --revoke',
       'frontera blueprint grant list',
     ],
@@ -145,15 +188,20 @@ export const blueprintGrant: Command = {
       })
     }
 
-    const resolved = await resolveSubject(client, subject, name)
     const revoke = ctx.flags.revoke === true
+    const permissions = grantPermissions(ctx.flags.permissions, subject, revoke)
+    const resolved = await resolveSubject(client, subject, name)
+    // Each grant replaces the whole list: without --permissions, what each grant holds is read first and kept.
+    const { send, kept } = revoke || permissions
+      ? { send: new Map<string, string[] | undefined>(apiNames.map((n) => [n, permissions])), kept: {} as Record<string, string[]> }
+      : keptPermissions(apiNames, subject === 'workspace' ? await client.workspaceGrants(resolved.id) : await client.agentGrants(resolved.id))
     for (const apiName of apiNames) {
       try {
         if (subject === 'workspace') {
           if (revoke) await client.revokeWorkspace(resolved.id, apiName)
-          else await client.grantWorkspace(resolved.id, apiName)
+          else await client.grantWorkspace(resolved.id, apiName, send.get(apiName))
         } else if (revoke) await client.revokeAgent(resolved.id, apiName)
-        else await client.grantAgent(resolved.id, apiName)
+        else await client.grantAgent(resolved.id, apiName, send.get(apiName))
       } catch (err) {
         /**
          * Grants address the PUBLISHED catalog, and the draft is a different
@@ -166,6 +214,10 @@ export const blueprintGrant: Command = {
          * which step — a comprehension audit read the bare 404 as the whole
          * pipeline being broken.
          */
+        // Grants are a Blueprint Steward's to give, `read_sensitive` above all: said as that.
+        if (err instanceof CliError && err.code === 'FORBIDDEN' && permissions?.includes('read_sensitive')) {
+          throw new CliError(`${err.message} Granting ${apiName} with read_sensitive needs a Blueprint Steward.`, { code: err.code, hint: 'run it with the credential of a Blueprint Steward of this organization', cause: err })
+        }
         const notFound = err instanceof CliError && err.code === 'NOT_FOUND'
         if (!notFound) throw err
         const onDraft = await client.getObjectType(apiName).then((t) => Boolean(t?.id)).catch(() => false)
@@ -182,10 +234,12 @@ export const blueprintGrant: Command = {
       }
     }
 
+    const keptText = Object.entries(kept).map(([apiName, extras]) => `${extras.join(' and ')} on ${apiName}`).join('; ')
     return {
-      data: { subject, id: resolved.id, name: resolved.name, apiNames, revoked: revoke },
+      data: { subject, id: resolved.id, name: resolved.name, apiNames, revoked: revoke, ...(permissions ? { permissions } : {}), ...(keptText ? { kept } : {}) },
       text: `${revoke ? 'Revoked' : 'Granted'} ${apiNames.join(', ')} `
-        + `${revoke ? 'from' : 'to'} ${subject} "${resolved.name}".`,
+        + `${revoke ? 'from' : 'to'} ${subject} "${resolved.name}"${permissions ? ` (${permissions.join(', ')})` : ''}.`
+        + (keptText ? ` Kept what the grant${Object.keys(kept).length === 1 ? '' : 's'} already held: ${keptText} (\`--permissions\` sets the whole list).` : ''),
     }
   },
 }

package/src/commands/blueprint/metric.ts

@@ -0,0 +1,108 @@
+import { PlatformApi } from '../../api/platform-api'
+import { METRIC_GRAINS, metricQueryBody, metricRows, resolveRangeWindow, timeseriesOf, type RangeWindow } from '../../blueprint/metric-query'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * A metric's numbers, through the same route an App's `useMetric` and an
+ * Agent's `blueprint_query_metric` read: so a metric just authored can be
+ * checked from the CLI, as `blueprint query` checks an object type's rows.
+ */
+
+const list = (raw: string | undefined) => (raw === undefined ? undefined : raw.split(',').map((s) => s.trim()).filter(Boolean))
+
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)))
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+export const blueprintMetric: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'metric',
+    // Reads the slice granted to ONE workspace, as `blueprint query` does.
+    scope: 'workspace' as const,
+    args: [
+      { name: 'query', required: true, description: 'query (the one action)' },
+      { name: 'apiName', required: true, description: 'the metric, from `frontera blueprint list` or blueprint/metrics/<apiName>.yaml' },
+    ],
+    flags: { measure: 'string', 'group-by': 'string', grain: 'string', range: 'string', start: 'string', end: 'string', compare: 'boolean' },
+    summary: 'Query the numbers of a Blueprint metric: by grain, over a time window, grouped by its dimensions',
+    details: [
+      'Every measure the metric defines, unless `--measure a,b` names some. `--group-by d1,d2` breaks the numbers down by the metric\'s dimensions.',
+      `\`--grain\` (${METRIC_GRAINS.join(', ')}) gives a series: the metric's timeseries dimension is added to the group-by. \`--range P7D\` is a window as an ISO-8601 duration, counted back from the newest value of the metric's timeseries in the data, not from now (so a load that runs behind does not empty it); the answer says the window it covered. \`--start\` and \`--end\` give a fixed one (a date reads as its midnight UTC; the end is exclusive). \`--compare\` adds the window before: <measure>_prev, <measure>_delta and <measure>_pct.`,
+      'Reads what the workspace is granted, as `blueprint query` does: an unknown or ungranted metric is NOT_FOUND. A metric the runtime is still building says so; run it again shortly.',
+    ],
+    examples: [
+      'frontera blueprint metric query workOrderBacklog',
+      'frontera blueprint metric query workOrderBacklog --group-by state,priority',
+      'frontera blueprint metric query workOrdersOpened --grain day --range P7D',
+      'frontera blueprint metric query workOrdersOpened --range P7D --compare',
+    ],
+  },
+
+  async run(ctx) {
+    const [first, second, ...rest] = ctx.positional
+    // `metric <apiName>` reads as `metric query <apiName>`.
+    const apiName = first === 'query' ? second : first
+    const extra = first === 'query' ? rest : [second, ...rest].filter((x) => x !== undefined)
+    if (!apiName) throw new UsageError('missing <apiName>', 'frontera blueprint list — then `frontera blueprint metric query <apiName>`')
+    if (extra.length) throw new UsageError(`unexpected ${extra.join(' ')}`, 'name one metric: `frontera blueprint metric query <apiName> [--group-by …]`')
+    const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const grain = flagString(ctx, 'grain')
+    // The timeseries dimension, read only when a series is asked for.
+    let timeseries: string | null | undefined
+    let metricRow: unknown
+    if (grain !== undefined) {
+      metricRow = await api.blueprintMetric(apiName).catch(async () => {
+        const all = (await api.blueprintMetrics().catch(() => [])) as Array<{ apiName?: string }>
+        return all.find((m) => m?.apiName === apiName) ?? null
+      })
+      timeseries = metricRow ? timeseriesOf(metricRow) : undefined
+    }
+    let body
+    try {
+      body = metricQueryBody({
+        measures: list(flagString(ctx, 'measure')),
+        dimensions: list(flagString(ctx, 'group-by')),
+        grain,
+        range: flagString(ctx, 'range'),
+        from: flagString(ctx, 'start'),
+        to: flagString(ctx, 'end'),
+        compare: flagBool(ctx, 'compare') || undefined,
+      }, timeseries)
+    } catch (err) {
+      throw new UsageError((err as Error).message.replace(/^(grain|range|compare)\b/, '--$1').replace(/^from\b/, '--start').replace(/^to\b/, '--end').replace(/give a range \(P7D\) or from and to/, 'give --range (P7D) or --start and --end').replace(/as a range \(P7D\) or as from and to/, 'as --range (P7D) or as --start and --end'), 'e.g. `frontera blueprint metric query <apiName> --grain day --range P7D`')
+    }
+    const result = await api.blueprintMetricQuery(apiName, body)
+    const rows = metricRows(result)
+    // A `--range` window ends at the newest record, not at now: say which window it was.
+    const isoDuration = body.timeRange?.isoDuration
+    const window: RangeWindow | undefined = isoDuration
+      ? await resolveRangeWindow(isoDuration, {
+          metric: async () => metricRow ?? api.blueprintMetric(apiName),
+          objectTypes: () => api.blueprintObjectTypes(),
+          aggregate: (aggregate) => api.blueprintAggregate(aggregate),
+        })
+      : undefined
+    const data = window ? (Array.isArray(result) ? { data: result, window } : { ...result, window }) : result
+    const compared = !Array.isArray(result) ? (result?.compareWindow as { start?: string; end?: string } | undefined) : undefined
+    const windowLine = (window ? `\n  Window: ${window.note}` : '')
+      + (compared?.start && compared.end ? `\n  Compared with: ${compared.start} up to ${compared.end} (the _prev, _delta and _pct columns).` : '')
+    if (!rows.length) {
+      return {
+        data,
+        text: `No rows for ${apiName}${body.timeRange ? ' in that window' : ''}.${windowLine}\n  The metric's object type may have no records yet; \`frontera blueprint query <ObjectType> --limit 5\` shows whether it has.`,
+      }
+    }
+    const columns = [...new Set(rows.flatMap((r) => Object.keys(r)))]
+    const truncated = !Array.isArray(result) && result?.truncated ? '\n  Truncated: narrow the window or group by fewer dimensions.' : ''
+    return {
+      data,
+      text: `${table(columns, rows.map((r) => columns.map((c) => cell(r[c]))))}\n\n${rows.length} row${rows.length === 1 ? '' : 's'}.${windowLine}${truncated}`,
+    }
+  },
+}

package/src/commands/blueprint/object-sets.ts

@@ -0,0 +1,71 @@
+import { PlatformApi } from '../../api/platform-api'
+import { findObjectSet, normalizeObjectSets, projectObjectSetNames, type SavedObjectSet } from '../../blueprint/object-sets'
+import { CliError } from '../../errors'
+import { findSolutionRoot } from '../../local/local-project'
+import { table } from '../../table'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * The saved object sets this credential can read: name, id, object type.
+ *
+ * A set is saved from a project file (`blueprint/object-sets/<name>.yaml`) by
+ * `local dev`, or in the Console, and a file or an App names it. An App's
+ * code keeps the id, a workflow file or a query the name: this is where both
+ * are read.
+ */
+export async function savedObjectSets(ctx: Pick<CommandContext, 'apiUrl' | 'token' | 'workspaceId'> & { cwd?: string }): Promise<SavedObjectSet[]> {
+  // In a project, a set a file saves is referenced by that file's name, as `status` names it.
+  const files = ctx.cwd ? projectObjectSetNames(projectRoot(ctx.cwd)) : new Map<string, string>()
+  return normalizeObjectSets(await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).blueprintObjectSets(), files)
+}
+
+/** The project's root when the working directory is in one with object set files; else null. */
+function projectRoot(cwd: string): string | null {
+  try {
+    return findSolutionRoot(cwd)
+  } catch {
+    return null
+  }
+}
+
+/** The set a flag names, by id, name or reference; a refusal that lists the sets otherwise. */
+export async function resolveObjectSet(ctx: Pick<CommandContext, 'apiUrl' | 'token' | 'workspaceId' | 'cwd'>, wanted: string, sets?: SavedObjectSet[]): Promise<SavedObjectSet> {
+  const all = sets ?? (await savedObjectSets(ctx))
+  const found = findObjectSet(all, wanted, projectObjectSetNames(projectRoot(ctx.cwd)))
+  if ('set' in found) return found.set
+  const listed = (found.ambiguous ?? all).slice(0, 8).map((s) => `${s.name} (${s.ref}, ${s.id})`)
+  throw new CliError(found.problem, {
+    code: found.ambiguous ? 'AMBIGUOUS_OBJECT_SET' : 'UNKNOWN_OBJECT_SET',
+    hint: all.length
+      ? `${found.ambiguous ? 'pass its id; they are' : 'the sets here are'}: ${listed.join('; ')}${all.length > 8 && !found.ambiguous ? ` and ${all.length - 8} more` : ''} — \`frontera blueprint object-sets\` lists them`
+      : 'no saved object set is readable here: add blueprint/object-sets/<name>.yaml and run `frontera local dev`, or save one in the Console',
+  })
+}
+
+export const blueprintObjectSetsList: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'object-sets',
+    scope: 'workspace' as const,
+    args: [],
+    flags: {},
+    summary: 'List the saved object sets: name, id, object type and the reference a file names it by',
+    details: [
+      'Pass a set to `frontera blueprint query --object-set <name|ref|id>` to read its rows. A workflow file names it as `objectSet/<ref>` or by its name; an App keeps its id.',
+    ],
+    examples: ['frontera blueprint object-sets', 'frontera blueprint object-sets --json'],
+  },
+
+  async run(ctx) {
+    const sets = await savedObjectSets(ctx)
+    return {
+      data: sets,
+      text: sets.length
+        ? table(
+            ['name', 'id', 'object type', 'kind', 'reference'],
+            sets.map((s) => [s.name, s.id, s.objectType, s.kind, s.ref]),
+          )
+        : 'No saved object sets are readable with this credential. Add blueprint/object-sets/<name>.yaml and run `frontera local dev`, or save one in the Console.',
+    }
+  },
+}