@frontera-sdk/cli 1.50.19 → 1.50.20

package/src/commands/workflow/push.ts

@@ -0,0 +1,172 @@
+import { readFile } from 'node:fs/promises'
+import { parse as parseYaml } from 'yaml'
+
+import { WorkflowApi, type LineageEdge } from '../../api/workflow-api'
+import { CliError, UsageError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * The slug a verb acts on, refused early rather than sent as an empty segment.
+ *
+ * `/v1/workflows//versions` is a different route from the one intended and
+ * answers something unrelated, so a missing slug has to fail here.
+ */
+export function requireSlug(ctx: CommandContext): string {
+  const slug = ctx.positional[0]
+  if (!slug) {
+    throw new UsageError(
+      'missing <slug>',
+      'run `frontera workflow list` — then pass the slug of the one you mean',
+    )
+  }
+  return slug
+}
+
+/**
+ * Read a definition file as YAML or JSON.
+ *
+ * One parser for both: YAML is a superset of JSON, so a `.json` file parses
+ * correctly here and a caller never has to think about which flag to pass.
+ * The failure is reported against the FILE, because a parse error forwarded to
+ * the service arrives as "definition must be an object" — true, and useless
+ * for finding the line with the bad indent.
+ */
+export async function readDefinitionFile(path: string): Promise<unknown> {
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch {
+    throw new UsageError(`cannot read ${path}`, 'pass the path to the workflow definition, YAML or JSON')
+  }
+  try {
+    return parseYaml(text)
+  } catch (err) {
+    throw new UsageError(`${path} is not valid YAML or JSON`, (err as Error).message)
+  }
+}
+
+function requireFile(ctx: CommandContext): string {
+  const path = ctx.positional[1]
+  if (!path) {
+    throw new UsageError(
+      'missing <file>',
+      'frontera workflow push <slug> workflow.yaml',
+    )
+  }
+  return path
+}
+
+/**
+ * What a definition reaches, as the author should read it before promoting.
+ *
+ * Grants and lineage are DERIVED from the definition — nobody writes them —
+ * so the push is the first and only chance to notice that a step reaches an
+ * object type or an Action the author did not intend to touch.
+ */
+export function describeReach(grants: string[] = [], lineage: LineageEdge[] = []): string {
+  const lines: string[] = []
+  if (grants.length > 0) lines.push(`  grants  ${grants.join(', ')}`)
+  for (const edge of lineage) {
+    const property = edge.property ? `.${edge.property}` : ''
+    const where = edge.nodeId ? `  (${edge.nodeId})` : ''
+    lines.push(`  ${edge.kind.padEnd(7)} ${edge.resourceKind} ${edge.label ?? edge.resourceId}${property}${where}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Push a definition as a new draft version.
+ *
+ * A push never runs anything and never changes what is live — it validates,
+ * derives the grants and lineage, and stores a draft. `promote` is the verb
+ * that arms it, deliberately separate, because the definition an author is
+ * still editing and the one their organization executes should not be the
+ * same act.
+ *
+ * The workflow is created on first push, the way a Function's first deploy
+ * creates its shell. There is no `create` verb for that reason.
+ */
+export const workflowPush: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'push',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug' },
+      { name: 'file', required: true, description: 'definition file, YAML or JSON' },
+    ],
+    flags: {},
+    summary: 'Validate a definition and store it as a new draft version',
+    examples: [
+      'frontera workflow push invoice-intake workflow.yaml',
+      'frontera workflow push invoice-intake workflow.yaml --json',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const definition = await readDefinitionFile(requireFile(ctx))
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const result = await client.push(slug, definition)
+
+    const reach = describeReach(result.grants, result.lineage)
+    return {
+      data: result,
+      text: `${slug}: pushed draft v${result.version?.number}\n`
+        + (reach ? `${reach}\n` : '')
+        + `  frontera workflow promote ${slug} ${result.version?.number}   # to make it live`,
+    }
+  },
+}
+
+/**
+ * Check a definition without writing anything.
+ *
+ * Separate from `push --dry-run` because the two answer different questions and
+ * one of them is used in a loop: this is the verb an author runs while editing,
+ * and it must not leave a trail of draft versions behind. The service supports
+ * it directly (`?dryRun=true`), including the grants and lineage — so a reach
+ * an author did not intend is visible BEFORE a draft exists.
+ */
+export const workflowValidate: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'validate',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug the definition is for' },
+      { name: 'file', required: true, description: 'definition file, YAML or JSON' },
+    ],
+    flags: {},
+    summary: 'Validate a definition and report its reach — writes nothing',
+    examples: ['frontera workflow validate invoice-intake workflow.yaml'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const definition = await readDefinitionFile(requireFile(ctx))
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    // A dry run reports problems as DATA, not as a 400 — the service does this
+    // so the Console can show them beside the draft. So the refusal arrives
+    // here as `ok: false` and has to be rendered, not thrown.
+    const result = await client.push(slug, definition, { dryRun: true })
+
+    // Thrown, not returned. A command result carries no exit code, so a
+    // rendered refusal would leave `validate` exiting 0 on an invalid
+    // definition — and the one place this verb is worth having is a CI step
+    // that must fail. `push` gets the same status for the same input, from the
+    // 400 the non-dry route answers with.
+    if (!result.ok) {
+      throw new CliError(`${slug}: the definition is not valid`, {
+        code: 'INVALID_DEFINITION',
+        hint: (result.errors ?? []).join('\n  '),
+      })
+    }
+
+    const reach = describeReach(result.grants, result.lineage)
+    return {
+      data: result,
+      text: `${slug}: the definition is valid\n`
+        + (reach ? `${reach}\n` : '')
+        + `  frontera workflow push ${slug} ${ctx.positional[1]}   # to store it as a draft`,
+    }
+  },
+}

package/src/commands/workflow/run.ts

@@ -0,0 +1,247 @@
+import { WorkflowApi, type RunRequest, type RunTree, type RunTreeNode } from '../../api/workflow-api'
+import { CliError, UsageError } from '../../errors'
+import { readSecretValue } from '../../secrets'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+import { requireSlug } from './push'
+
+/**
+ * How long to wait for a run to reach a terminal state.
+ *
+ * The same budget `function run` uses, for the same reason: a CLI that blocks
+ * for the engine's own ceiling reads as hung, and giving up here loses
+ * nothing — the run is recorded and the timeout message says where to read it.
+ * Bounding the WAIT is not bounding the RUN.
+ */
+const WAIT_TIMEOUT_MS = 120_000
+const POLL_INTERVAL_MS = 2_000
+
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled'])
+
+/** Has this run stopped, or might it still change? */
+export function isTerminal(status: string): boolean {
+  return TERMINAL.has(status)
+}
+
+/**
+ * Is this the refusal that will still be a refusal in two seconds?
+ *
+ * The two codes `credentialFailure` mints. Kept as a predicate rather than an
+ * `instanceof CliError` check because most CliErrors ARE worth retrying — it
+ * is specifically the credential ones that are not.
+ */
+export function isCredentialFailure(err: unknown): boolean {
+  const code = (err as { code?: string } | null)?.code
+  return code === 'UNAUTHORIZED' || code === 'FORBIDDEN'
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * A run id, refused locally when it is not one.
+ *
+ * The same principle `promote` applies to a version number: both run routes
+ * declare `t.String({ format: 'uuid' })`, and a bad value forwarded to them
+ * comes back as Elysia's validation payload — which is not shaped like the
+ * `details.errors` the definition routes send, so it renders as "Validation
+ * failed" plus a JSON dump of the validator's internals. The author typed a
+ * wrong id; that is the answer, and it is available here.
+ */
+export function requireRunId(raw: string | undefined): string {
+  if (!raw) {
+    throw new UsageError(
+      'missing <runId>',
+      'run `frontera workflow runs <slug>` — the last column is the id',
+    )
+  }
+  if (!UUID.test(raw)) {
+    throw new UsageError(`"${raw}" is not a run id`, 'a run id is a uuid — the last column of `frontera workflow runs <slug>`')
+  }
+  return raw
+}
+
+/**
+ * `--input '<json>'`, `--input @file.json`, or `--input @-` (stdin).
+ *
+ * Parsed locally, before anything is sent, so a typo fails against the text
+ * the author typed rather than as a schema violation against a run that was
+ * already started. `@…` reads through `readSecretValue`, the helper the rest
+ * of the CLI's `@`-prefixed arguments use — which is also what makes `@-`
+ * work here without a second stdin implementation.
+ */
+export async function parseInputFlag(ctx: CommandContext): Promise<Record<string, unknown> | undefined> {
+  const raw = flagString(ctx, 'input')
+  if (raw === undefined) return undefined
+  const text = raw.startsWith('@') ? await readSecretValue(raw) : raw
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new UsageError('--input must be a JSON object (or @file.json)', '--input \'{"key": "value"}\'')
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new UsageError('--input must be a JSON object', '--input \'{"key": "value"}\'')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * `--version N`, or undefined for the live one.
+ *
+ * Rejected here rather than forwarded for the reason `promote` rejects its
+ * argument: `--version abc` arriving as `NaN` comes back naming a field the
+ * author never typed.
+ */
+export function parseVersionFlag(ctx: CommandContext): number | undefined {
+  const raw = flagString(ctx, 'version')
+  if (raw === undefined) return undefined
+  const parsed = Number(raw)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new UsageError(`"${raw}" is not a version number`, 'frontera workflow get <slug> lists the versions')
+  }
+  return parsed
+}
+
+/** One line per node, nested under the run each child step started. */
+export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
+  const lines: string[] = []
+  for (const node of nodes) {
+    const indent = '  '.repeat(depth)
+    const failed = node.status === 'failed' ? ' ✗' : ''
+    lines.push(`${indent}${node.nodeId}  ${node.kind}  ${node.status}${failed}`)
+    // A `forEach` or a `workflow` step is a run of its own, and its steps are
+    // where its failure is explained — flattening them would report a failed
+    // parent with no reason anywhere in the output.
+    if (node.childRun) lines.push(...describeNodes(node.childRun.nodes, depth + 1))
+  }
+  return lines
+}
+
+/**
+ * The subject of a bound run, as "<type> <pk>".
+ *
+ * NOT `label ?? pk`. `label` is the object TYPE's display name
+ * (`workflow-run-tree.ts:209` reads `subjectType.displayName`), and the type
+ * and the pk are set together — so a fallback means the pk never renders and
+ * every run of one workflow reads identically as "Shipment". The pk is the
+ * part that says WHICH shipment, and it is the part a caller needs.
+ */
+export function describeSubject(subject: { pk: string; label: string | null } | null): string {
+  if (!subject) return ''
+  return [subject.label, subject.pk].filter(Boolean).join(' ')
+}
+
+/** A finished run, its steps, and what it returned. */
+export function describeRun(run: RunTree): string {
+  const lines = [`${run.status} — v${run.versionNumber ?? '?'}, ${run.nodeCalls} node call(s)`]
+  if (run.subject) lines.push(`  subject ${describeSubject(run.subject)}`)
+  // The error before the steps: it is the reason the reader opened this, and
+  // burying it under a trail of successful steps is how it gets missed.
+  if (run.error) lines.push(`  error ${typeof run.error === 'string' ? run.error : JSON.stringify(run.error)}`)
+  lines.push(...describeNodes(run.nodes))
+  if (run.output !== null && run.output !== undefined) lines.push(`  returned ${JSON.stringify(run.output)}`)
+  return lines.join('\n')
+}
+
+/**
+ * Start a run of the live version and, by default, wait for it.
+ *
+ * Waiting is the default because the reason to start a workflow by hand is to
+ * find out what it does; `--no-wait` is for the caller who only needs the id.
+ *
+ * There is no baseline-and-compare here, unlike `function run`: the route
+ * answers with the `runId` it created, so the run this command reports on is
+ * the run it started, even when a cron fires into the same second.
+ *
+ * A run that ends `failed` exits 0, deliberately. The command succeeded — it
+ * started a run and reported the outcome — and this is what `function run`
+ * already does, so the two sibling verbs cannot disagree about what an exit
+ * code means. It does read oddly beside `validate`, which throws so a CI step
+ * fails; the difference is that an invalid definition is a broken INPUT, while
+ * a failed run is a true ANSWER. A caller gating on the outcome should read
+ * `.status` from `--json`.
+ */
+export const workflowRun: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'run',
+    args: [{ name: 'slug', required: true, description: 'workflow slug' }],
+    flags: { 'no-wait': 'boolean', input: 'string', subject: 'string', version: 'string' },
+    summary: 'Run the live version now — or a named one — and report what it did',
+    examples: [
+      'frontera workflow run invoice-intake',
+      'frontera workflow run invoice-intake --input \'{"threshold": 500}\'',
+      'frontera workflow run invoice-intake --input @input.json',
+      'frontera workflow run shipment-review --subject SHP-0000001',
+      'frontera workflow run invoice-intake --version 3 --no-wait',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+
+    const body: RunRequest = {}
+    const input = await parseInputFlag(ctx)
+    if (input) body.input = input
+    const subject = flagString(ctx, 'subject')
+    // The primary key, not a JSON object. A subject-bound workflow takes one
+    // pk and nothing else, and asking for `{"pk":"…"}` on a command line would
+    // be quoting ceremony around a single value.
+    if (subject) body.subject = { pk: subject }
+    const version = parseVersionFlag(ctx)
+    if (version !== undefined) body.version = version
+
+    const started = await client.run(slug, body)
+
+    if (flagBool(ctx, 'no-wait')) {
+      return {
+        data: started,
+        text: `Started ${slug} v${started.versionNumber}.\n`
+          + `  ${started.runId}\n`
+          + `  frontera workflow runs ${slug} ${started.runId}   # to see how it went`,
+      }
+    }
+
+    const deadline = Date.now() + WAIT_TIMEOUT_MS
+    let seen: RunTree | undefined
+    let pollFailure: Error | undefined
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+      // A failed POLL must not be reported as a failed RUN. The run was
+      // started — the id above is the only handle on it — and throwing here
+      // would lose that id to an error describing something else entirely.
+      // The concrete case is a key holding `execute` but not `view`: it starts
+      // the run and is then refused the read, which `credentialFailure` words
+      // as a rejected credential. A transient 5xx reads the same way.
+      try {
+        seen = await client.runById(started.runId)
+      } catch (err) {
+        pollFailure = err as Error
+        // A credential refusal will not heal, so retrying it only delays the
+        // answer by the rest of the wait budget. Anything else might be
+        // transient and is worth another poll.
+        if (isCredentialFailure(err)) break
+        continue
+      }
+      pollFailure = undefined
+      if (isTerminal(seen.status)) {
+        // The id, on the human path too. A failed run exits 0 by design, so
+        // this is the common way a caller learns something went wrong — and
+        // without the id printed here they have nothing to pass to
+        // `workflow runs` or `workflow cancel`. `--json` always carried it.
+        return { data: seen, text: `${slug}: ${describeRun(seen)}\n  ${seen.id}` }
+      }
+    }
+
+    // An error about the WAIT, not about the workflow. The run may still
+    // succeed, and reporting a slow run as a failed one sends an author to
+    // debug working steps. Either way the run id is carried out, because it is
+    // the only way back to what was started.
+    throw new CliError(
+      pollFailure
+        ? `the run started, but reading it back failed: ${pollFailure.message}`
+        : `the run started but was still ${seen?.status ?? 'queued'} after ${WAIT_TIMEOUT_MS / 1000}s`,
+      { code: 'REQUEST_FAILED', hint: `frontera workflow runs ${slug} ${started.runId}` },
+    )
+  },
+}

package/src/commands/workflow/runs.ts

@@ -0,0 +1,84 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { CliError } from '../../errors'
+import { table } from '../../table'
+import type { Command } from '../types'
+import { describeRun, describeSubject, requireRunId } from './run'
+import { requireSlug } from './push'
+
+/**
+ * Recent runs, newest first — or one run and its steps.
+ *
+ * One verb rather than two, the way `function runs` does it: the list is where
+ * a failure is noticed and the step trail is where it is explained, and
+ * splitting them puts a second command name between the two halves of one
+ * question.
+ */
+export const workflowRuns: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'runs',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug' },
+      {
+        name: 'runId',
+        required: false,
+        description: 'one run to open, with its steps; omit to list recent runs',
+      },
+    ],
+    flags: {},
+    summary: 'List recent runs, newest first — or open one run and its steps',
+    examples: [
+      'frontera workflow runs invoice-intake',
+      'frontera workflow runs invoice-intake 0f2c8b1e-7a41-4c96-9d3e-52b0c4a7e118',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+
+    if (ctx.positional[1] !== undefined) {
+      const runId = requireRunId(ctx.positional[1])
+      // `depth: 'all'`, so a step that started a child workflow explains itself
+      // here rather than pointing at another id to look up.
+      const run = await client.runById(runId, 'all')
+      // The route is workspace-global — it takes the id and ignores the slug —
+      // so without this check a mistyped slug silently prints a DIFFERENT
+      // workflow's run, and nothing in the output reveals it. The slug is not
+      // dropped from the signature instead, because it is what makes the
+      // `runs <slug>` listing and this detail view one verb.
+      if (run.slug !== slug) {
+        throw new CliError(`run ${runId} belongs to "${run.slug}", not to "${slug}"`, {
+          code: 'NOT_FOUND',
+          hint: `frontera workflow runs ${run.slug} ${runId}`,
+        })
+      }
+      return { data: run, text: describeRun(run) }
+    }
+
+    const rows = await client.runs(slug)
+    if (rows.length === 0) {
+      return {
+        data: { runs: [] },
+        text: `No runs recorded for ${slug}.\n  frontera workflow run ${slug}   # to start one`,
+      }
+    }
+
+    return {
+      data: { runs: rows },
+      text: table(
+        ['STARTED', 'STATUS', 'VERSION', 'TRIGGER', 'SUBJECT', 'RUN ID'],
+        rows.map((r) => [
+          r.startedAt,
+          r.status,
+          `v${r.versionNumber}`,
+          r.triggerSource,
+          describeSubject(r.subjectPk ? { pk: r.subjectPk, label: r.subjectLabel } : null),
+          // Never truncated: an id cut to fit the terminal cannot be pasted
+          // into the detail view, which is the only reason it is printed.
+          r.id,
+        ]),
+      ),
+    }
+  },
+}

package/src/flag-help.ts

@@ -75,8 +75,16 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'no-install': 'scaffold without running `bun install` — for an offline machine or a sandbox',
   'no-git': 'scaffold without creating a repository and an initial commit',
   'no-components': 'scaffold without fetching the baseline shadcn components',
-  version: 'version to publish, overriding the one in package.json',
-  input: "JSON object of the automation's declared inputs — inline ('{\"key\": 1}') or @file.json",
+  // Worded for every consumer, not for the first one. `FLAG_HELP` is keyed by
+  // flag name globally, and `--version` is now read by three commands: two
+  // choose which version to RUN, one chooses which to publish. The old text
+  // described only the third, so `workflow run --help` and `function run
+  // --help` both advertised package.json.
+  version: 'the version to act on — the one to run, or on a deploy the one to publish',
+  input: "JSON object of the declared inputs — inline ('{\"key\": 1}') or @file.json",
+  // The primary key alone. A subject-bound workflow takes exactly one, so the
+  // flag spends no characters on the `{"pk": …}` the route models it as.
+  subject: 'primary key of the object a subject-bound workflow runs for',
   'no-promote': 'publish the version without moving the live pointer',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
   // Named for what it RUNS, not where it runs: an author reads this to decide
@@ -172,7 +180,10 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   plan: 'path',
   dir: 'path',
   file: 'path',
-  version: 'semver',
+  // Not `semver`: `app deploy` takes one, but `function run` and `workflow run`
+  // take an integer version number, and this map is keyed by flag name for all
+  // three. `<version>` is the only placeholder true of every consumer.
+  version: 'version',
   framework: 'next|react',
   port: 'number',
   origin: 'url',