@frontera-sdk/cli 1.43.6 → 1.43.8

package/src/commands/automation/build-entry.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import { UsageError } from '../../errors'
+
+/**
+ * Building an automation entry file, extracted from `index-commands`.
+ *
+ * Its own module because two verbs need it — `deploy` and `dev` — and
+ * `index-commands` imports `dev` to register the command. Left where it was,
+ * that is a require cycle whose resolution order is Bun-version-dependent: the
+ * command list evaluated before `automationDev` was initialised and threw
+ * `Cannot access 'automationDev' before initialization`. The same class of bug
+ * `binary-smoke.test.ts` exists to catch, and the same reason
+ * `function-builder.ts` takes its executor as a parameter.
+ */
+
+/**
+ * Build the entry file, then read the manifest off the BUILT module.
+ *
+ * The artifact is the thing the runner will execute, so it is the thing worth
+ * inspecting: a manifest read from the source could differ from the one that
+ * ships. The cost is that importing it evaluates the module here, so anything
+ * an author does at import time runs on this machine — calling `automation()`
+ * and nothing else is the contract.
+ */
+export async function buildAndExtract(file: string): Promise<{
+  manifest: Record<string, unknown>
+  code: string
+}> {
+  const entry = resolve(file)
+  if (!existsSync(entry)) {
+    throw new UsageError(`no such file: ${file}`, 'pass the path to the automation entry file')
+  }
+
+  // `throw: false`. The default raises an AggregateError whose message is the
+  // bare string "Bundle failed" — no file, no reason — and it escapes as an
+  // INTERNAL_ERROR, telling the caller to RETRY a build that will never
+  // succeed. A build error is something the caller fixes, so it exits 2.
+  const built = await Bun.build({
+    entrypoints: [entry],
+    target: 'bun',
+    minify: false,
+    throw: false,
+  })
+  if (!built.success) {
+    throw new UsageError(
+      `could not build ${file}: ${built.logs.map((l) => l.message).join('; ')}`,
+      'fix the errors above, then run the command again',
+    )
+  }
+
+  const code = await built.outputs[0]!.text()
+
+  const dir = mkdtempSync(join(tmpdir(), 'frontera-automation-'))
+  try {
+    const bundle = join(dir, 'bundle.js')
+    await Bun.write(bundle, code)
+    const mod = (await import(bundle)) as { default?: { manifest?: unknown } }
+    const manifest = mod.default?.manifest
+
+    if (!manifest || typeof manifest !== 'object') {
+      throw new UsageError(
+        `${file} has no automation as its default export`,
+        'export the result of `automation({ … }, handler)` as the default export',
+      )
+    }
+    return { manifest: manifest as Record<string, unknown>, code }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}

package/src/commands/automation/dev.ts

@@ -0,0 +1,453 @@
+import { mkdtempSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import { buildContext } from '@frontera-sdk/automation/runtime'
+import { AutomationApi } from '../../api/automation-api'
+import { CliError, UsageError } from '../../errors'
+import { type Command, type CommandContext } from '../types'
+import { validateManifest } from '@frontera-sdk/automation'
+import { buildAndExtract } from './build-entry'
+
+/**
+ * `frontera automation dev` — run the handler in THIS file, from this machine,
+ * triggered from the Console.
+ *
+ * The loop it replaces is a deploy: build, upload, mint a version, bump the
+ * registry, wait for the broker. Fifteen seconds and an immutable row, for
+ * questions as small as "is this field a number or a string". Measured on
+ * 2026-08-10: five versions to get one automation working, four of them
+ * discarded, none of them logic bugs.
+ *
+ * Resumption IS reproduced — see `localStepTools`. The handler is re-entered
+ * after every step, exactly as production does, so code outside a step repeats
+ * here the way it repeats live.
+ *
+ * What this still does NOT test, and why one real deploy before promoting
+ * remains worth doing: the bundle (this imports the module directly), and broker
+ * registration (nothing here reaches Inngest). And every ctx call is DRY, so the
+ * data a handler branches on is empty rather than real.
+ */
+
+/** How often to ask for work. Fast enough that pressing Run feels immediate,
+ *  slow enough that an idle session is not a busy loop against the service. */
+const POLL_MS = 1_000
+
+/** Lease renewal rides on the same poll, so there is no second timer to get out
+ *  of step with it. */
+export interface DevPollResult {
+  held: boolean
+  run: { runId: string; runToken: string; grants: string[]; workspaceId: string } | null
+}
+
+/**
+ * Thrown to end an execution the moment a new step completes.
+ *
+ * Not an error the author can see or catch meaningfully — `runHandlerToCompletion`
+ * is the only thing that ever observes it. A class rather than a sentinel value
+ * so a handler wrapping its body in `try/catch` and swallowing everything is
+ * caught by the driver as the determinism bug it is, rather than silently
+ * finishing an execution that was supposed to yield.
+ */
+class StepYield extends Error {
+  constructor() {
+    super('step yielded')
+    this.name = 'StepYield'
+  }
+}
+
+/**
+ * A backstop, not a policy.
+ *
+ * Every yield memoizes exactly one step, so a handler with N steps settles in
+ * N+1 executions and this is never reached — the case it looks like it guards
+ * against, a step name built from a counter, is caught by the determinism check
+ * instead, which says something far more useful. It stays because the driver is
+ * an unbounded loop around author code, and an unbounded loop wants a ceiling
+ * even when the reasoning says it cannot spin.
+ */
+const MAX_EXECUTIONS = 1_000
+
+export interface DevStepState {
+  /** Step name → its JSON-round-tripped result, in completion order. */
+  memo: Map<string, unknown>
+  /** Names in the order the handler produced them, for the determinism check. */
+  order: string[]
+}
+
+export function newDevStepState(): DevStepState {
+  return { memo: new Map(), order: [] }
+}
+
+/**
+ * Step tools that resume, the way the deployed runner's do.
+ *
+ * They used to just call the body: the dev worker invoked the handler ONCE,
+ * straight through, and memoization had nothing to replay. That made dev a
+ * different execution model from production, which re-enters the handler after
+ * every step (`function-builder.ts` hands Inngest's own `step` down to `ctx`, so
+ * the author's `ctx.step.run` calls ARE the run's steps).
+ *
+ * The difference was not academic. Code OUTSIDE a step runs once per resumption
+ * in production and once in total here, so a counter incremented between two
+ * steps read `40` on a laptop and `120` live — no error, no warning, and only
+ * visible after a promote. Any `ctx` call outside a step cost 1 here and N+1
+ * there, so an automation that fitted the budget in dev could exceed it live.
+ *
+ * So: one new step per execution. A completed step is memoized and returns its
+ * stored value without running the body again; a step that has not run yet runs
+ * and then YIELDS, ending the execution. `runHandlerToCompletion` calls the
+ * handler again, and again, until it returns without yielding.
+ *
+ * Two things this buys beyond fidelity:
+ *
+ *   - The memo is a JSON round trip, because that is what the platform stores
+ *     and replays. `Date` comes back a string and `undefined` disappears, here,
+ *     rather than after a deploy.
+ *   - Re-execution makes non-determinism VISIBLE. A handler that produces a
+ *     different step order on the second pass is broken in production in a way
+ *     that reports nothing; here it names the step that moved.
+ */
+export function localStepTools(
+  state: DevStepState = newDevStepState(),
+): { run<T>(id: string, fn: () => Promise<T>): Promise<unknown> } {
+  // Reset per EXECUTION, not per run: it counts what this pass has replayed, so
+  // the next unmemoized name can be checked against the recorded order.
+  let replayed = 0
+  return {
+    async run<T>(id: string, fn: () => Promise<T>): Promise<unknown> {
+      // The determinism check, and the reason re-execution is worth its cost.
+      // Production replays memoized results POSITIONALLY; a handler that emits a
+      // different order on the second pass gets another step's result handed to
+      // it, silently. Named here instead.
+      const expected = state.order[replayed]
+      if (expected !== undefined && expected !== id) {
+        throw new Error(
+          `this automation is not deterministic: step ${replayed + 1} was `
+            + `"${expected}" on an earlier execution and is "${id}" now. The platform `
+            + 'replays completed steps by position, so the two runs would be handed '
+            + "each other's results. Move anything conditional INSIDE a step.",
+        )
+      }
+
+      if (state.memo.has(id)) {
+        replayed += 1
+        return state.memo.get(id)
+      }
+
+      const out = await fn()
+      // Through JSON, because that is the boundary the platform puts here — the
+      // author gets back what a resumption would give them, not the object the
+      // body happened to return.
+      //
+      // Stringify FIRST and check. `JSON.stringify` returns `undefined` for a
+      // function, a symbol, or an object whose `toJSON()` returns undefined —
+      // and `JSON.parse(undefined)` then throws `SyntaxError: "undefined" is
+      // not valid JSON`, which escaped as the author's own error and failed the
+      // run naming neither the step nor the cause. The platform stores an
+      // unserialisable value as nothing rather than exploding, so parsing
+      // blindly was also a divergence in the one helper built for fidelity.
+      let json: string | undefined
+      try {
+        json = JSON.stringify(out)
+      } catch (err) {
+        // A `BigInt` or a circular structure cannot be stored by the platform
+        // either, so failing is right — anonymously is not. Named, because the
+        // author otherwise reads a `TypeError` from a line they did not write.
+        throw new Error(
+          `step "${id}" returned a value the platform cannot store: ${(err as Error).message}. `
+            + 'Step results make a JSON round trip between resumptions.',
+        )
+      }
+      state.memo.set(id, json === undefined ? undefined : JSON.parse(json))
+      state.order.push(id)
+      // Ends the execution. Everything after this call in the author's handler
+      // belongs to the NEXT one, which is precisely the production behaviour
+      // this exists to reproduce.
+      throw new StepYield()
+    },
+  }
+}
+
+/**
+ * Call the handler until it finishes without yielding.
+ *
+ * The other half of `localStepTools`. One execution ends at the first step that
+ * has not run before; this brings it back, with that step now memoized, and the
+ * handler gets one step further. For N steps the handler is entered N+1 times —
+ * the same shape as a production run, and the reason code outside a step is now
+ * seen to repeat.
+ *
+ * `buildContext` is called per execution rather than once, because production
+ * builds a fresh `ctx` on every resumption too — the duplicate-step-name set
+ * inside it is scoped to one execution, and reusing a context would make the
+ * second pass reject every name it had already seen.
+ */
+export async function runHandlerToCompletion(
+  handler: (ctx: unknown) => Promise<unknown>,
+  buildContextFor: (step: ReturnType<typeof localStepTools>) => unknown,
+  state: DevStepState = newDevStepState(),
+): Promise<unknown> {
+  for (let execution = 0; ; execution += 1) {
+    if (execution > MAX_EXECUTIONS) {
+      throw new Error(
+        `this automation did not settle after ${MAX_EXECUTIONS} executions, which `
+          + 'should not be reachable — please report it with the handler that caused it.',
+      )
+    }
+    try {
+      return await handler(buildContextFor(localStepTools(state)))
+    } catch (err) {
+      // Anything that is NOT the yield is the author's error, and belongs to
+      // them: it fails the run and reaches the Console with its message.
+      if (!(err instanceof StepYield)) throw err
+    }
+  }
+}
+
+/**
+ * A fresh module path per build.
+ *
+ * Bun's module registry is keyed by resolved PATH: re-writing the same path with
+ * new bytes and importing again returns the FIRST module — stale code, with no
+ * error to read. The deployed runner escapes this by accident of design, since
+ * every deploy mints a random version id and therefore a new path. A worker
+ * rebuilding one slug has no such key and must make one.
+ */
+export function devModulePath(dir: string, counter: number): string {
+  return join(dir, `build-${counter}.js`)
+}
+
+
+/**
+ * Close a dev run.
+ *
+ * A plain `fetch`, not the workspace client: this is the runner protocol, and
+ * the only credential the local process holds for it is the RUN token the claim
+ * handed over. Routing it through `FronteraClient` would attach the workspace
+ * key to a call that must not need one.
+ */
+async function finishDevRun(
+  apiUrl: string,
+  runId: string,
+  runToken: string,
+  body: { status: 'succeeded' | 'failed'; result?: unknown; errorMessage?: string },
+): Promise<void> {
+  await fetch(`${apiUrl}/v1/automations/runner/runs/${runId}/finish`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-automation-run-token': runToken },
+    body: JSON.stringify(body),
+  })
+}
+
+/**
+ * How often to rebuild the entry so the manifest sent with each poll is current.
+ *
+ * Not every poll: `Bun.build` is milliseconds but a second is a lot of them, and
+ * an idle session would spend its life rebuilding a file nobody touched. The
+ * entry's mtime is the cheap proxy — an edit moves it, and nothing else does.
+ */
+function mtimeOf(path: string): number {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+export const automationDev: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'dev',
+    args: [
+      {
+        name: 'file',
+        required: true,
+        description: 'entry file whose default export is an `automation(…)`',
+      },
+    ],
+    flags: {},
+    summary: 'Serve this file to dev runs — no deploy, no version',
+    examples: ['frontera automation dev src/index.ts'],
+  },
+
+  async run(ctx: CommandContext) {
+    const file = ctx.positional[0]
+    if (!file) {
+      throw new UsageError('missing <file>', 'frontera automation dev <file>')
+    }
+    const entry = resolve(file)
+
+    // Built once up front for its MANIFEST: the slug is what the session is
+    // opened against, and building later would mean claiming a session for a
+    // name the file may not carry. The bundle from this build is discarded —
+    // every run rebuilds, so an edit made while waiting is picked up.
+    let { manifest } = await buildAndExtract(entry)
+    const invalid = validateManifest(manifest)
+    if (!invalid.valid) {
+      throw new UsageError(
+        `${file} does not describe a valid automation:\n  ${invalid.errors.join('\n  ')}`,
+        'fix the manifest, then run the command again',
+      )
+    }
+    let lastMtime = mtimeOf(entry)
+    // VALIDATED HERE, once, before a session is opened.
+    //
+    // The comment this replaces said `validateManifest` had already run inside
+    // the build. It had not: `buildAndExtract` only asserts the default export
+    // carries a `manifest` object, and `automation()` checks `name` and nothing
+    // else. So a file with no trigger, or a six-field cron, built fine, opened a
+    // session fine, and then failed EVERY poll — which the worker printed as
+    // "poll failed, retrying" until the lease lapsed and the author was told
+    // they had been taken over.
+    const slug = typeof manifest.name === 'string' ? manifest.name : ''
+    if (!slug) {
+      throw new UsageError(
+        `${file} does not name an automation`,
+        'the default export must be `automation({ name: "…" }, handler)`',
+      )
+    }
+
+    const api = new AutomationApi(ctx.apiUrl, ctx.token)
+    // Identity of THIS process, minted once and sent with every dev call.
+    //
+    // The session id cannot serve: take-over is an upsert on the automation, so
+    // the row and its id outlive the hand-over and a displaced worker's
+    // heartbeat still matches. Nor can the user id, which two terminals belonging
+    // to one developer share — the common case, and how this was found.
+    const holderId = crypto.randomUUID()
+    const session = await api.devSessionOpen(slug, entry, holderId)
+
+    const out = ctx.output
+    out.note(`[dev] ${slug} — running from ${file}`)
+    out.note(`[dev] connected to ${ctx.apiUrl}`)
+    // The first question an author has is whether this disturbs production, and
+    // no verb name can answer it. Stated before anything else happens.
+    out.note(
+      session.liveVersionId
+        ? '[dev] the live version keeps running on schedule; this only serves dev runs'
+        : '[dev] nothing is deployed yet, so nothing runs on a schedule',
+    )
+    // Said at START, not only on the run line. An author reads the header once
+    // and then watches runs scroll past; a caveat printed per run is noise, and
+    // one printed nowhere is a surprise the first time they wonder why a query
+    // came back empty.
+    out.note('[dev] runs are DRY — ctx.agent, ctx.http and ctx.blueprint return empty and send nothing')
+    if (session.created) out.note(`[dev] created the automation "${slug}" (no version yet)`)
+    out.note(`[dev] waiting — press Run dev in the Console, or \`frontera automation run ${slug} --dev\``)
+
+    const workDir = mkdtempSync(join(tmpdir(), 'frontera-dev-'))
+    let builds = 0
+    let stopping = false
+
+    // Released explicitly so the Console banner clears at once rather than
+    // waiting out the lease. Best-effort by nature — SIGKILL never arrives here,
+    // and the lease is what covers that.
+    const release = async () => {
+      if (stopping) return
+      stopping = true
+      out.note('\n[dev] releasing the session')
+      await api.devSessionClose(slug, session.sessionId, holderId).catch(() => {})
+      process.exit(0)
+    }
+    process.on('SIGINT', () => void release())
+    process.on('SIGTERM', () => void release())
+
+    while (!stopping) {
+      // Rebuild only when the file moved. The manifest goes up with every
+      // poll so the service can set a claimed run's grants from what the file
+      // says NOW — but rebuilding once a second for an idle session would be
+      // work nobody asked for.
+      const mtime = mtimeOf(entry)
+      if (mtime !== lastMtime) {
+        try {
+          manifest = (await buildAndExtract(entry)).manifest
+          lastMtime = mtime
+        } catch (err) {
+          // A broken file must not end the session — the author is mid-edit.
+          // The previous manifest stays in force until the file parses again.
+          out.note(`[dev] build failed, keeping the last manifest: ${(err as Error).message}`)
+          lastMtime = mtime
+        }
+      }
+
+      let poll: DevPollResult
+      try {
+        poll = await api.devPoll(slug, session.sessionId, holderId, manifest)
+      } catch (err) {
+        // A service blip must not end a session the author still has open.
+        out.note(`[dev] poll failed, retrying: ${(err as Error).message}`)
+        await new Promise((r) => setTimeout(r, POLL_MS))
+        continue
+      }
+
+      if (!poll.held) {
+        throw new CliError(
+          'this dev session is no longer held — another `automation dev` took it over, '
+            + 'or the lease expired',
+          {
+            code: 'REQUEST_FAILED',
+            // Re-opening silently would let two processes ping-pong a session
+            // neither can keep, and a run would execute against whichever file
+            // won the last exchange.
+            hint: 'start it again if you still want to serve this automation',
+          },
+        )
+      }
+
+      if (!poll.run) {
+        await new Promise((r) => setTimeout(r, POLL_MS))
+        continue
+      }
+
+      const run = poll.run
+      out.note(`[dev] run ${run.runId.slice(0, 8)} — building`)
+      const started = Date.now()
+      try {
+        // REBUILT per run, not once at startup. `Bun.build` on one automation is
+        // milliseconds, and the alternative — edit, press Run, watch the
+        // previous code execute — is silent staleness with no error to read.
+        const built = await buildAndExtract(entry)
+        const path = devModulePath(workDir, ++builds)
+        await Bun.write(path, built.code)
+        const mod = (await import(path)) as {
+          default?: { handler?: (c: unknown) => Promise<unknown> }
+        }
+        if (typeof mod.default?.handler !== 'function') {
+          throw new Error(`${file} has no automation() default export`)
+        }
+
+        // Entered once per step, not once per run — see `localStepTools`. A
+        // fresh context each time, because production builds one per resumption
+        // and its duplicate-name set is scoped to a single execution.
+        const result = await runHandlerToCompletion(mod.default.handler, (step) =>
+          buildContext({
+            runId: run.runId,
+            workspaceId: run.workspaceId,
+            runToken: run.runToken,
+            grants: run.grants,
+            step,
+            serviceUrl: ctx.apiUrl,
+          }),
+        )
+        await finishDevRun(ctx.apiUrl, run.runId, run.runToken, { status: 'succeeded', result })
+        // "succeeded" is the wrong word for a run whose every ctx call returned
+        // empty. It finished; whether it works is not something a dry run can
+        // say, and the terminal is where an author decides to promote.
+        out.note(`[dev] run ${run.runId.slice(0, 8)} finished (dry) in ${Date.now() - started}ms`)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        // A build error is reported as a FAILED RUN, not only here: the person
+        // who pressed Run is looking at the Console, and an error that appears
+        // only in a terminal they may not be watching reads as a hang.
+        await finishDevRun(ctx.apiUrl, run.runId, run.runToken, {
+          status: 'failed',
+          errorMessage: message,
+        }).catch(() => {})
+        out.note(`[dev] run ${run.runId.slice(0, 8)} failed: ${message}`)
+      }
+    }
+
+    return { data: { slug, sessionId: session.sessionId }, text: '' }
+  },
+}

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

@@ -10,6 +10,10 @@ import { packDirectory } from '../../pack'
 import { automationInit } from './init'
 import { automationPull } from './pull'
 import { automationRun, automationRuns } from './run'
+import { automationDev } from './dev'
+import { buildAndExtract } from './build-entry'
+
+export { buildAndExtract } from './build-entry'
 import { findAutomationProjectRoot } from './project-root'
 import { formatBytes } from '../../packaging'
 import { table } from '../../table'
@@ -27,61 +31,6 @@ function requireSlug(ctx: CommandContext): string {
   return slug
 }
 
-/**
- * Build the entry file, then read the manifest off the BUILT module.
- *
- * The artifact is the thing the runner will execute, so it is the thing worth
- * inspecting: a manifest read from the source could differ from the one that
- * ships. The cost is that importing it evaluates the module here, so anything
- * an author does at import time runs on this machine — calling `automation()`
- * and nothing else is the contract.
- */
-export async function buildAndExtract(file: string): Promise<{
-  manifest: Record<string, unknown>
-  code: string
-}> {
-  const entry = resolve(file)
-  if (!existsSync(entry)) {
-    throw new UsageError(`no such file: ${file}`, 'pass the path to the automation entry file')
-  }
-
-  // `throw: false`. The default raises an AggregateError whose message is the
-  // bare string "Bundle failed" — no file, no reason — and it escapes as an
-  // INTERNAL_ERROR, telling the caller to RETRY a build that will never
-  // succeed. A build error is something the caller fixes, so it exits 2.
-  const built = await Bun.build({
-    entrypoints: [entry],
-    target: 'bun',
-    minify: false,
-    throw: false,
-  })
-  if (!built.success) {
-    throw new UsageError(
-      `could not build ${file}: ${built.logs.map((l) => l.message).join('; ')}`,
-      'fix the errors above, then run the command again',
-    )
-  }
-
-  const code = await built.outputs[0]!.text()
-
-  const dir = mkdtempSync(join(tmpdir(), 'frontera-automation-'))
-  try {
-    const bundle = join(dir, 'bundle.js')
-    await Bun.write(bundle, code)
-    const mod = (await import(bundle)) as { default?: { manifest?: unknown } }
-    const manifest = mod.default?.manifest
-
-    if (!manifest || typeof manifest !== 'object') {
-      throw new UsageError(
-        `${file} has no automation as its default export`,
-        'export the result of `automation({ … }, handler)` as the default export',
-      )
-    }
-    return { manifest: manifest as Record<string, unknown>, code }
-  } finally {
-    rmSync(dir, { recursive: true, force: true })
-  }
-}
 
 /** How stale a registry poll may be before a deploy is worth warning about.
  *  The runner's default interval is 15s, so a minute is several missed polls —
@@ -363,4 +312,5 @@ export const automationCommands: Command[] = [
   automationRuns,
   automationPull,
   automationInit,
+  automationDev,
 ]