@frontera-sdk/cli 1.43.6 → 1.43.7

package/src/commands/automation/run.ts

@@ -5,7 +5,7 @@ import {
   type AutomationRunSummary,
   type RegistryStatus,
 } from '../../api/automation-api'
-import { flagBool, type Command, type CommandContext } from '../types'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
 /**
  * How long to wait for a queued run to reach a terminal state.
@@ -114,9 +114,68 @@ export function describeTrail(steps: AutomationRunStep[]): string[] {
   return lines
 }
 
+/**
+ * `--version N`, or undefined for the live one.
+ *
+ * Exported so the parsing is testable without a network client. Rejects here
+ * rather than forwarding a bad value: `--version abc` sent onward arrives as a
+ * schema violation naming `version` as an integer, which is true and useless —
+ * the author typed a word, and the message should say so.
+ */
+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`,
+      'versions are whole numbers from 1 — `frontera automation versions <slug>` lists them',
+    )
+  }
+  return parsed
+}
+
+
+/**
+ * Wait for the run this invoke started, and read its trail.
+ *
+ * Shared by the live and dev paths because the question is the same one — the
+ * only difference is how the run was started. Identified by id against a
+ * baseline taken BEFORE the invoke: counting rows would claim a concurrently
+ * firing cron's run as this one, which on a five-minute schedule is not a rare
+ * race.
+ */
+async function waitForRun(
+  client: AutomationApi,
+  slug: string,
+  priorId: string | null,
+  mode: 'live' | 'dev' = 'live',
+): Promise<{ run: AutomationRunSummary | undefined; steps: AutomationRunStep[] }> {
+  const deadline = Date.now() + WAIT_TIMEOUT_MS
+  let seen: AutomationRunSummary | undefined
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+    const [latest] = await client.runs(slug, 1, mode)
+    if (isNewRun(priorId, latest) && latest) {
+      seen = latest
+      if (isTerminal(latest.status)) {
+        // Best-effort: a run that finished is the answer, and failing to read its
+        // trail must not turn a successful run into a failed command.
+        const steps = await client.runSteps(latest.id).catch(() => [])
+        return { run: latest, steps }
+      }
+    }
+  }
+  return { run: seen, steps: [] }
+}
+
 /** One line describing a finished run, its trail, and its output. */
 export function describeRun(run: AutomationRunSummary, steps: AutomationRunStep[] = []): string {
-  const lines = [`${run.status} — v${run.version}, ${run.ctxCalls} ctx call(s)`]
+  // A dev run has no version — its code never left the author's machine — and
+  // `v${null}` printed `vnull` on the first line the author reads. Named rather
+  // than dashed here, because the CLI has room for the reason.
+  const where = run.version === null ? 'from a dev session' : `v${run.version}`
+  const lines = [`${run.status} — ${where}, ${run.ctxCalls} ctx call(s)`]
   if (run.errorMessage) lines.push(`  ${run.errorMessage}`)
   // The trail is why an author ran this by hand: which steps executed, in what
   // order, and where the time went. Without it the CLI reported an outcome and
@@ -147,10 +206,12 @@ export const automationRun: Command = {
     noun: 'automation',
     verb: 'run',
     args: [{ name: 'slug', required: true, description: 'automation slug' }],
-    flags: { 'no-wait': 'boolean' },
-    summary: 'Run the live version now and report what it did',
+    flags: { 'no-wait': 'boolean', version: 'string', dev: 'boolean' },
+    summary: 'Run the live version now — or a named one, or the dev session — and report what it did',
     examples: [
       'frontera automation run daily-digest',
+      'frontera automation run daily-digest --dev',
+      'frontera automation run daily-digest --version 7',
       'frontera automation run daily-digest --no-wait',
     ],
   },
@@ -158,6 +219,46 @@ export const automationRun: Command = {
   async run(ctx) {
     const slug = requireSlug(ctx)
     const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    // Parsed here rather than passed through as a string: a typo should fail
+    // before the registry wait, not after it, and `--version abc` reaching the
+    // service as `NaN` would come back as a schema error naming a field the
+    // author never typed.
+    const version = parseVersionFlag(ctx)
+    const dev = flagBool(ctx, 'dev')
+    if (dev && version !== undefined) {
+      throw new UsageError(
+        '--dev and --version name different things to run',
+        'a dev run executes the file on the machine holding the session; it has no version',
+      )
+    }
+
+    // A dev run never reaches the broker, so the registry wait below is not just
+    // unnecessary — it would refuse a perfectly good dev run in an environment
+    // that has no runner deployed at all, which is exactly where a dev loop is
+    // most useful.
+    if (dev) {
+      // `'dev'` on BOTH the baseline and the wait. Without it each reads live
+      // history: the command sits out its whole timeout for a run that finished
+      // seconds in, and a cron fire during the wait is reported as if it were
+      // the dev run.
+      const before = await client.runs(slug, 1, 'dev')
+      const priorId = before[0]?.id ?? null
+      const queued = await client.run(slug, undefined, true)
+      if (flagBool(ctx, 'no-wait')) {
+        return {
+          data: queued,
+          text: `Queued a dev run of ${slug}.\n`
+            + `  frontera automation runs ${slug}   # to see how it went`,
+        }
+      }
+      const seen = await waitForRun(client, slug, priorId, 'dev')
+      return {
+        data: seen.run ? { ...seen.run, steps: seen.steps } : queued,
+        text: seen.run
+          ? `${slug}: ${describeRun(seen.run, seen.steps)}`
+          : `${slug}: the dev run did not finish within ${WAIT_TIMEOUT_MS / 1000}s`,
+      }
+    }
 
     // Wait for the runner BEFORE invoking, not after. An event sent early is
     // dropped rather than queued, so there is nothing to wait for afterwards.
@@ -188,7 +289,7 @@ export const automationRun: Command = {
     const before = await client.runs(slug, 1)
     const priorId = before[0]?.id ?? null
 
-    const queued = await client.run(slug)
+    const queued = await client.run(slug, version)
 
     if (flagBool(ctx, 'no-wait')) {
       return {
@@ -202,6 +303,8 @@ export const automationRun: Command = {
     let seen: AutomationRunSummary | undefined
     while (Date.now() < deadline) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+      // The LIVE path. No mode to pass — `runs()` defaults to live, which is
+      // what this loop is waiting for.
       const [latest] = await client.runs(slug, 1)
       if (isNewRun(priorId, latest) && latest) {
         seen = latest
@@ -237,20 +340,34 @@ export const automationRuns: Command = {
     noun: 'automation',
     verb: 'runs',
     args: [{ name: 'slug', required: true, description: 'automation slug' }],
-    flags: {},
+    flags: { dev: 'boolean' },
     summary: 'List recent runs, newest first, with what each one returned',
-    examples: ['frontera automation runs daily-digest'],
+    examples: [
+      'frontera automation runs daily-digest',
+      'frontera automation runs daily-digest --dev',
+    ],
   },
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).runs(slug)
+    // The two histories are separate rows and the route defaults to live, so
+    // without this a dev run is invisible from the CLI — the same blind spot
+    // that made `run --dev` wait out its timeout.
+    const dev = flagBool(ctx, 'dev')
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).runs(
+      slug,
+      undefined,
+      dev ? 'dev' : 'live',
+    )
 
     if (rows.length === 0) {
       return {
         data: rows,
-        text: `No runs recorded for ${slug}.\n`
-          + `  frontera automation run ${slug}   # to start one`,
+        text: dev
+          ? `No dev runs recorded for ${slug}.\n`
+            + `  frontera automation dev <entry-file>   # to serve one`
+          : `No runs recorded for ${slug}.\n`
+            + `  frontera automation run ${slug}   # to start one`,
       }
     }