@frontera-sdk/cli 1.50.79 → 1.50.81

package/src/commands/action/decide.ts

@@ -0,0 +1,54 @@
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { UsageError } from '../../errors'
+import { flagString, type Command, type CommandContext } from '../types'
+import { requestSummary } from './request-summary'
+
+/**
+ * Approve or reject a request waiting on approval.
+ *
+ * Session-lane, and a person's decision in a stronger sense than submit: the
+ * approver needs `actionApproval: ['approve' | 'reject']` in their stored
+ * organization role, membership in the request's workspace, and — when the
+ * Action declares separation of duties — not to be the person who raised it.
+ * That last refusal reads "Approval separation of duties was not satisfied."
+ * With a threshold above one, an approval can leave the request still
+ * `awaiting_approval` until enough other people decide.
+ */
+
+function decision(verb: 'approve' | 'reject'): Command {
+  return {
+    meta: {
+      noun: 'action',
+      verb,
+      authLane: 'session',
+      // The Requests tab of the Actions page carries the same two decisions.
+      sessionAlternative: 'Blueprint → Actions → Requests',
+      scope: 'workspace' as const,
+      args: [{ name: 'requestId', required: true, description: `The request to ${verb}` }],
+      flags: { reason: 'string' },
+      summary: verb === 'approve'
+        ? 'Approve an Action request waiting on approval'
+        : 'Reject an Action request waiting on approval',
+      examples: [`frontera action ${verb} <requestId> --reason "Checked against the ticket"`],
+    },
+
+    async run(ctx: CommandContext) {
+      const requestId = ctx.positional[0]
+      if (!requestId) {
+        throw new UsageError('missing <requestId>', 'frontera action requests --lifecycle awaiting_approval')
+      }
+      // Required by the service, and recorded with the decision.
+      const reason = flagString(ctx, 'reason')
+      if (!reason) {
+        throw new UsageError('missing --reason', `frontera action ${verb} ${requestId} --reason "…"`)
+      }
+
+      const result = await new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+        .decideApproval(requestId, verb, reason)
+      return { data: result, text: requestSummary(result.request) }
+    },
+  }
+}
+
+export const actionApprove = decision('approve')
+export const actionReject = decision('reject')

package/src/commands/action/deploy.ts

@@ -23,7 +23,10 @@ export const actionDeploy: Command = {
   meta: {
     noun: 'action',
     verb: 'deploy',
-    authLane: 'session',
+    // The three writes and the catalog reads are on programmatic routers
+    // (`governed-action-deployment-router.ts`, `blueprint-router.ts`), so an
+    // organization key carrying `actionMutationPlan`/`actionBinding` runs this.
+    authLane: 'api-key',
     args: [{ name: 'action', required: true, description: 'The published Action’s API name' }],
     flags: { 'dry-run': 'boolean', 'plan-id': 'string', 'binding-id': 'string' },
     summary: 'Build and validate the write path for a published Action',

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

@@ -1,9 +1,13 @@
+import { actionAvailable } from './available'
+import { actionCancel } from './cancel'
+import { actionApprove, actionReject } from './decide'
 import { actionDeploy } from './deploy'
 import { actionGrant } from './grant'
 import { actionList } from './list'
 import { actionPrepare } from './prepare'
 import { actionRequests } from './requests'
 import { actionReview } from './review'
+import { actionSubmit } from './submit'
 import type { Command } from '../types'
 
 /**
@@ -16,13 +20,14 @@ import type { Command } from '../types'
  * review and a state-machine activation. Five admin calls with hand-minted
  * UUIDs, or nothing.
  *
- * Invoking is deliberately absent. Both CLI credential kinds present a
- * non-member principal — `wskey:…` and `orgkey:…` — and the invoke check joins
- * organization membership, so a `submit` verb here would refuse every call it
- * ever made. It belongs to a credential that represents a person.
+ * Invoking — `available`, `submit`, `approve`, `reject`, `cancel` — is
+ * session-lane. Both key kinds present a non-member principal — `wskey:…` and
+ * `orgkey:…` — and the invoke check joins organization membership, so those
+ * verbs need the credential of a person: a session token in `FRONTERA_TOKEN`,
+ * which `frontera login` cannot store.
  *
- * READING those invocations is not the same boundary, and `requests` is here:
- * the list gates on `actionRequest: ['read']` rather than on membership. The
+ * READING those invocations is not the same boundary, and `requests` runs on a
+ * key: the list gates on `actionRequest: ['read']` rather than on membership. The
  * distinction matters because an armed path that fails every request looks
  * exactly like one nothing has tried, and until now nothing in the CLI could
  * tell the two apart.
@@ -30,6 +35,11 @@ import type { Command } from '../types'
 export const actionCommands: readonly Command[] = [
   actionList,
   actionRequests,
+  actionAvailable,
+  actionSubmit,
+  actionApprove,
+  actionReject,
+  actionCancel,
   actionPrepare,
   actionDeploy,
   actionReview,

package/src/commands/action/prepare.ts

@@ -17,7 +17,9 @@ export const actionPrepare: Command = {
   meta: {
     noun: 'action',
     verb: 'prepare',
-    authLane: 'session',
+    // `POST /deployments` moved to the programmatic deployment router, so an
+    // organization key carrying `actionBinding` runs this.
+    authLane: 'api-key',
     args: [{ name: 'action', required: true, description: 'The drafted Action’s API name' }],
     flags: { reason: 'string' },
     summary: 'Record that a drafted Action ships disabled, so it can be published',

package/src/commands/action/request-summary.ts

@@ -0,0 +1,13 @@
+import type { ActionRequestSummary } from '../../api/governed-action-api'
+
+/**
+ * One line for a request a write verb just changed.
+ *
+ * `lifecycle` is what the caller acts on next — `awaiting_approval` means
+ * someone else has to `action approve`, `ready` means dispatch is queued.
+ */
+export function requestSummary(request: ActionRequestSummary): string {
+  return `Request ${request.id ?? '?'} is ${request.lifecycle ?? 'unknown'}`
+    + (request.effectCertainty ? ` (effect ${request.effectCertainty})` : '')
+    + '.'
+}

package/src/commands/action/requests.ts

@@ -11,9 +11,9 @@ import { flagString, type Command } from '../types'
  * armed path that every caller's request fails against looks identical to one
  * nothing has tried yet. This is the only verb that can tell them apart.
  *
- * Read-only, and that is a boundary rather than an omission: invoking joins
- * organization membership, which no CLI credential satisfies. Listing gates on
- * `actionRequest: ['read']`, which a key can hold.
+ * Read-only, so it runs on a key: listing gates on `actionRequest: ['read']`,
+ * which a key can hold. Invoking joins organization membership and needs a
+ * session — see `action submit`.
  */
 export const actionRequests: Command = {
   meta: {
@@ -83,8 +83,9 @@ export const actionRequests: Command = {
         text: filtered
           ? `No requests with lifecycle "${filtered}".`
           : 'No Action requests recorded.\n'
-            + '  Nothing has invoked a deployed Action yet — invoking needs a credential\n'
-            + '  that represents a person, so it happens from an agent or the Console.',
+            + '  Nothing has invoked a deployed Action yet. Raise one with\n'
+            + '  `frontera action submit`, which acts as a person: set FRONTERA_TOKEN\n'
+            + '  to your session token and FRONTERA_API_URL.',
       }
     }
 

package/src/commands/action/submit.ts

@@ -0,0 +1,183 @@
+import { GovernedActionApi, type ActionDiscovery } from '../../api/governed-action-api'
+import { CliError, UsageError } from '../../errors'
+import { toEnvelope } from '../../exit'
+import { parseInputFlag } from '../automation/run'
+import { flagString, type Command } from '../types'
+import { requestSummary } from './request-summary'
+
+/**
+ * Raise one request against a deployed Action — the step `action review`
+ * arms and `action requests` reads back.
+ *
+ * Session-lane: the invoke check joins organization and workspace membership,
+ * which no `wskey:` or `orgkey:` principal satisfies.
+ *
+ * The CLI assembles the envelope so the caller never writes it: parameters
+ * under `input`, the subject under `subjectRef` with the object type the
+ * Action itself declares, and the version under `expectedSubjectVersion`.
+ * The service refuses a wrong envelope without naming the field it disliked,
+ * so everything the discovery schema can check is checked here first.
+ */
+
+/**
+ * `priority=2` is the number 2 and `title=Broken` the string — unless the
+ * Action declares the input a string, when the text is taken as written, so
+ * `ticketId=123` stays "123".
+ */
+function pair(raw: string, stringInputs: ReadonlySet<string>): [string, unknown] {
+  const eq = raw.indexOf('=')
+  if (eq < 1) {
+    throw new UsageError(`"${raw}" is not a key=value parameter`, 'frontera action submit <apiName> title=Broken priority=2')
+  }
+  const key = raw.slice(0, eq)
+  const text = raw.slice(eq + 1)
+  if (stringInputs.has(key)) return [key, text]
+  try {
+    return [key, JSON.parse(text)]
+  } catch {
+    return [key, text]
+  }
+}
+
+export const actionSubmit: Command = {
+  meta: {
+    noun: 'action',
+    verb: 'submit',
+    authLane: 'session',
+    scope: 'workspace' as const,
+    args: [
+      { name: 'apiName', required: true, description: 'The Action to submit, as `action available` lists it' },
+      { name: 'key=value...', required: false, description: 'Parameters; text for string inputs, otherwise read as JSON when it parses' },
+    ],
+    flags: {
+      input: 'string',
+      subject: 'string',
+      'subject-version': 'string',
+      reason: 'string',
+      'idempotency-key': 'string',
+    },
+    summary: 'Submit a request to a deployed Action',
+    examples: [
+      'frontera action submit createTicket title=Broken priority=2',
+      'frontera action submit escalateTicket --subject TKT-1 --subject-version 0',
+      'frontera action submit createTicket --input @params.json',
+      'frontera action submit createTicket --idempotency-key retry-2026-09-26-01',
+    ],
+  },
+
+  async run(ctx) {
+    const [apiName, ...pairs] = ctx.positional
+    if (!apiName) {
+      throw new UsageError('missing <apiName>', 'frontera action available — to list the Actions you can submit')
+    }
+    const subject = flagString(ctx, 'subject')
+    const version = flagString(ctx, 'subject-version')
+    if ((subject === undefined) !== (version === undefined)) {
+      throw new UsageError(
+        '--subject and --subject-version go together',
+        `pass both: frontera action submit ${apiName} --subject <objectId> --subject-version <version>`,
+      )
+    }
+
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    // One read before the write: the schema is what lets a wrong envelope be
+    // refused here, by name, instead of by the service without one.
+    const action = (await client.discover()).find((a) => a.apiName === apiName)
+    if (!action) {
+      throw new CliError(`You cannot submit "${apiName}" in this workspace.`, {
+        code: 'NOT_FOUND',
+        hint: 'frontera action available — to list the Actions you can submit',
+      })
+    }
+
+    const input = {
+      ...(await parseInputFlag(ctx)),
+      ...Object.fromEntries(pairs.map((raw) => pair(raw, stringInputs(action)))),
+    }
+    const missing = (action.inputSchema?.properties?.input?.required ?? []).filter((name) => !(name in input))
+    if (missing.length > 0) {
+      throw new UsageError(
+        `"${apiName}" needs ${missing.join(', ')}`,
+        `frontera action submit ${apiName} ${missing.map((name) => `${name}=…`).join(' ')}`,
+      )
+    }
+
+    const invocation: Record<string, unknown> = { input }
+    const existing = action.subject?.mode === 'existing' && action.subject.objectTypeId
+    if (existing && subject === undefined) {
+      throw new UsageError(
+        `"${apiName}" acts on an existing object`,
+        `name it: frontera action submit ${apiName} --subject <objectId> --subject-version <version>`,
+      )
+    }
+    if (!existing && subject !== undefined) {
+      throw new UsageError(
+        `"${apiName}" does not act on an existing object`,
+        `drop --subject and --subject-version: frontera action submit ${apiName} key=value…`,
+      )
+    }
+    if (existing) {
+      // The object type is the Action's, not the caller's to choose.
+      invocation.subjectRef = { objectTypeId: action.subject!.objectTypeId, objectId: subject }
+      invocation.expectedSubjectVersion = version
+    }
+    const reason = flagString(ctx, 'reason')
+    if (reason !== undefined) invocation.reason = reason
+    else if (action.inputSchema?.required?.includes('reason')) {
+      throw new UsageError(`"${apiName}" requires a reason`, `frontera action submit ${apiName} … --reason "…"`)
+    }
+
+    const idempotencyKey = flagString(ctx, 'idempotency-key') ?? `cli-${crypto.randomUUID()}`
+    if (!/^[!-~]{16,255}$/.test(idempotencyKey)) {
+      throw new UsageError(
+        '--idempotency-key must be 16–255 printable characters with no spaces',
+        'omit it to have one generated',
+      )
+    }
+
+    // Announced BEFORE the request: the retry it enables is for exactly the
+    // case where no response ever arrives — a timeout, a dropped connection,
+    // Ctrl-C — and a key printed only on success is lost in all three.
+    ctx.output.note(`idempotency key ${idempotencyKey}`)
+    const retry = `retry with --idempotency-key ${idempotencyKey} to get the same request back, never a second one`
+    let request
+    try {
+      request = await client.submit(apiName, invocation, idempotencyKey)
+    } catch (err) {
+      // Only where the outcome is unknown. A refusal the service answered
+      // (400, 403, 404, 409) is replayed identically under the same key, so
+      // naming the retry there would invite a loop; it is rethrown as is.
+      if (!transient(err)) throw err
+      const envelope = toEnvelope(err)
+      throw new CliError(envelope.message, {
+        code: err instanceof CliError ? envelope.code : 'FAILURE',
+        hint: envelope.hint ? `${envelope.hint}; ${retry}` : retry,
+        cause: err,
+      })
+    }
+    return {
+      data: { request, idempotencyKey },
+      text: `${requestSummary(request)}\n`
+        + `  idempotency key ${idempotencyKey} — reuse it with --idempotency-key to retry safely\n`
+        + `  frontera action requests ${request.id ?? '<requestId>'}`,
+    }
+  },
+}
+
+/**
+ * No answer, or one that says "not now": a network error or timeout (anything
+ * that is not a CliError never reached a response), a 5xx, or a 429.
+ */
+function transient(err: unknown): boolean {
+  if (!(err instanceof CliError)) return true
+  const status = (err.cause as { status?: unknown } | undefined)?.status
+  return typeof status === 'number' && (status >= 500 || status === 429)
+}
+
+/** Inputs the Action declares as strings, whose text must not be read as JSON. */
+function stringInputs(action: ActionDiscovery): ReadonlySet<string> {
+  const properties = action.inputSchema?.properties?.input?.properties ?? {}
+  return new Set(Object.entries(properties)
+    .filter(([, schema]) => (schema as { type?: unknown } | null)?.type === 'string')
+    .map(([name]) => name))
+}

package/src/commands/blueprint/get.ts

@@ -29,6 +29,57 @@ interface ObjectTypeRow {
   description?: string | null
 }
 
+interface Relation {
+  apiName?: string
+  direction: 'outbound' | 'inbound'
+  otherObjectType: string
+  cardinality?: string
+}
+
+/**
+ * One catalog read: the rows, or why they are missing.
+ *
+ * `unavailable` is not an error path — the command still prints. It is the
+ * difference between "this type has no relations" and "nobody could tell",
+ * which a bare `[]` erased.
+ */
+type CatalogRead<T> =
+  | { ok: true; rows: T[] }
+  | { ok: false; unavailable: string }
+
+/**
+ * Describe a failed read in the terms the caller can act on.
+ *
+ * The message is carried as well as the status and code, because the two say
+ * different things and only one of them is ever actionable: `403 FORBIDDEN`
+ * alone hides "Blueprint Steward assignment required", which is the sentence
+ * that tells the operator what to go and do. `detail` is appended where the
+ * service sent one — `org-key-route-ungated` is the case where no grant change
+ * will help, and saying so stops the reader hunting for a permission to add.
+ */
+function describeFailure(cause: unknown): string {
+  const error = cause as
+    | { code?: string; status?: number; message?: string; details?: { detail?: string } }
+    | null
+  const status = [error?.status ? String(error.status) : null, error?.code ?? null]
+    .filter(Boolean)
+    .join(' ')
+  const parts = [
+    status || null,
+    error?.message ?? null,
+    error?.details?.detail ?? null,
+  ].filter(Boolean)
+  return parts.length > 0 ? parts.join(' — ') : String(cause)
+}
+
+async function readCatalog<T>(fetch: () => Promise<T[]>): Promise<CatalogRead<T>> {
+  try {
+    return { ok: true, rows: await fetch() }
+  } catch (cause) {
+    return { ok: false, unavailable: describeFailure(cause) }
+  }
+}
+
 /**
  * Resolve what the caller typed to a real api name.
  *
@@ -99,29 +150,70 @@ export const blueprintGet: Command = {
     // Both key on object-type UUIDs, not api names, so the catalog is fetched
     // to resolve them. Matching on names silently produced "Relations (0)" for
     // a type with eight of them.
+    //
+    // Degrade rather than crash — one unreadable catalog route should not stop
+    // the command printing the properties it already has. But a failure is
+    // reported as a failure: an empty list and an unreadable one are different
+    // facts, and rendering both as "(none)" told the caller a type had no
+    // relations when the truth was that nothing could check.
     const [links, metrics, types] = await Promise.all([
-      api.blueprintLinkTypes().catch(() => [] as unknown[]),
-      api.blueprintMetrics().catch(() => [] as unknown[]),
-      api.blueprintObjectTypes().catch(() => [] as unknown[]),
+      readCatalog(() => api.blueprintLinkTypes()),
+      readCatalog(() => api.blueprintMetrics()),
+      readCatalog(() => api.blueprintObjectTypes()),
     ])
 
+    // Relations and metrics key on object-type UUIDs, so both depend on the
+    // object-type list to resolve an id to a name. If THAT read failed there is
+    // no id to match on, and every link would silently drop — so its failure
+    // makes both sections unavailable, not empty.
+    const typeRows = types.ok
+      ? (types.rows as Array<{ id?: string; apiName?: string }>)
+      : []
     const nameById = new Map<string, string>()
-    for (const t of types as Array<{ id?: string; apiName?: string }>) {
-      if (t.id && t.apiName) nameById.set(t.id, t.apiName)
+    for (const row of typeRows) {
+      if (row.id && row.apiName) nameById.set(row.id, row.apiName)
     }
-    const selfId = (types as Array<{ id?: string; apiName?: string }>)
-      .find((candidate) => candidate.apiName === apiName)?.id ?? ''
-
-    const related = (links as Link[]).flatMap((link) => {
-      if (link.fromObjectTypeId !== selfId && link.toObjectTypeId !== selfId) return []
-      const outbound = link.fromObjectTypeId === selfId
-      const other = nameById.get((outbound ? link.toObjectTypeId : link.fromObjectTypeId) ?? '')
-      if (!other || !grantedNames.has(other)) return []
-      return [{ apiName: link.apiName, direction: outbound ? 'outbound' as const : 'inbound' as const, otherObjectType: other, cardinality: link.cardinality }]
-    })
-    const own = (metrics as Metric[])
-      .filter((metric) => metric.objectTypeId === selfId)
-      .map((metric) => ({ apiName: metric.apiName, displayName: metric.displayName }))
+    // `apiName` was resolved against `/schema` (the workspace-granted slice) while
+    // the id comes from `/object-types` (the organization catalog) — two sources,
+    // so a type can be present in the first and missing from the second even when
+    // BOTH reads succeeded. Without this, `selfId` fell back to `''`, matched no
+    // link, and printed the same confident `Relations (0)` this command exists to
+    // stop. A read that worked but cannot answer is still "cannot answer".
+    const selfRow = typeRows.find((candidate) => candidate.apiName === apiName)
+    const selfId = selfRow?.id ?? ''
+    const unresolvedSelf = types.ok && !selfId
+      ? `could not resolve ${apiName} in the object-type catalog — it is in this workspace's schema but absent from the catalog list`
+      : null
+
+    const relations: CatalogRead<Relation> = !types.ok
+      ? { ok: false, unavailable: `could not read object types: ${types.unavailable}` }
+      : unresolvedSelf
+        ? { ok: false, unavailable: unresolvedSelf }
+        : !links.ok
+        ? { ok: false, unavailable: `could not read link types: ${links.unavailable}` }
+        : {
+            ok: true,
+            rows: (links.rows as Link[]).flatMap((link) => {
+              if (link.fromObjectTypeId !== selfId && link.toObjectTypeId !== selfId) return []
+              const outbound = link.fromObjectTypeId === selfId
+              const other = nameById.get((outbound ? link.toObjectTypeId : link.fromObjectTypeId) ?? '')
+              if (!other || !grantedNames.has(other)) return []
+              return [{ apiName: link.apiName, direction: outbound ? 'outbound' as const : 'inbound' as const, otherObjectType: other, cardinality: link.cardinality }]
+            }),
+          }
+
+    const own: CatalogRead<{ apiName?: string; displayName?: string }> = !types.ok
+      ? { ok: false, unavailable: `could not read object types: ${types.unavailable}` }
+      : unresolvedSelf
+        ? { ok: false, unavailable: unresolvedSelf }
+        : !metrics.ok
+        ? { ok: false, unavailable: `could not read metrics: ${metrics.unavailable}` }
+        : {
+            ok: true,
+            rows: (metrics.rows as Metric[])
+              .filter((metric) => metric.objectTypeId === selfId)
+              .map((metric) => ({ apiName: metric.apiName, displayName: metric.displayName })),
+          }
 
     const props = type.properties as Property[]
     const heading = [apiName, type.displayName].filter(Boolean)
@@ -137,21 +229,39 @@ export const blueprintGet: Command = {
               `  ${(p.apiName ?? '?').padEnd(26)}${(p.dataType ?? '').padEnd(12)}${p.propertyType ?? ''}`,
           )),
       '',
-      `Relations (${related.length})`,
-      ...(related.length === 0
-        ? ['  (none)']
-        : related.map((relation) => {
-            return `  ${(relation.apiName ?? '?').padEnd(26)}${relation.direction === 'outbound' ? '→' : '←'} ${relation.otherObjectType.padEnd(18)}${relation.cardinality ?? ''}`
-          })),
+      ...(relations.ok
+        ? [
+            `Relations (${relations.rows.length})`,
+            ...(relations.rows.length === 0
+              ? ['  (none)']
+              : relations.rows.map((relation) => {
+                  return `  ${(relation.apiName ?? '?').padEnd(26)}${relation.direction === 'outbound' ? '→' : '←'} ${relation.otherObjectType.padEnd(18)}${relation.cardinality ?? ''}`
+                })),
+          ]
+        : ['Relations (unavailable)', `  ${relations.unavailable}`]),
       '',
-      `Metrics (${own.length})`,
-      ...(own.length === 0
-        ? ['  (none)']
-        : own.map((m) => `  ${(m.apiName ?? '?').padEnd(26)}${m.displayName ?? ''}`)),
+      ...(own.ok
+        ? [
+            `Metrics (${own.rows.length})`,
+            ...(own.rows.length === 0
+              ? ['  (none)']
+              : own.rows.map((m) => `  ${(m.apiName ?? '?').padEnd(26)}${m.displayName ?? ''}`)),
+          ]
+        : ['Metrics (unavailable)', `  ${own.unavailable}`]),
     ]
 
     return {
-      data: { objectType: type, properties: props, relations: related, metrics: own },
+      data: {
+        objectType: type,
+        properties: props,
+        // `null` rather than `[]` for an unreadable section, and a sibling
+        // field saying why. A consumer that treats absence as emptiness now has
+        // to opt into it; the old `[]` gave it no choice.
+        relations: relations.ok ? relations.rows : null,
+        ...(relations.ok ? {} : { relationsUnavailable: relations.unavailable }),
+        metrics: own.ok ? own.rows : null,
+        ...(own.ok ? {} : { metricsUnavailable: own.unavailable }),
+      },
       text: lines.join('\n'),
     }
   },