@frontera-sdk/cli 1.52.23 → 1.52.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.23",
+  "version": "1.52.25",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.52.23",
-    "@frontera-sdk/core": "1.52.23",
+    "@frontera-sdk/functions": "1.52.25",
+    "@frontera-sdk/core": "1.52.25",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.52.23",
+    "@frontera-sdk/forge-contracts": "1.52.25",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/dataset-api.ts

@@ -117,10 +117,14 @@ export class DatasetApi {
         // to re-read their file sends them to the wrong place entirely: the
         // service dials the database itself, from wherever it runs.
         hint: detail
-          ?? (response.status === 409
-            ? 'the service dials the database itself — check host and port are reachable '
-              + 'from where the service runs, and that the password on stdin is current'
-            : 'check the document against `frontera source create --help`'),
+          ?? (response.status === 409 && /already in use|already exists/i.test(payload?.message ?? '')
+            // The same status for a name that is taken, which no connection check fixes.
+            ? 'pick another apiName, or load new rows into the existing dataset with '
+              + '`frontera dataset upload <apiName> <file.csv>`'
+            : response.status === 409
+              ? 'the service dials the database itself — check host and port are reachable '
+                + 'from where the service runs, and that the password on stdin is current'
+              : 'check the document against `frontera source create --help`'),
       })
     }
     return (payload?.data ?? payload) as T

package/src/automation-template.ts

@@ -35,6 +35,9 @@ export const AUTOMATION_SDK_FILES = [
   // in, shared with the runner.
   'frontera/automation/messages.ts',
   'frontera/automation/testing.ts',
+  // `testing.ts` imports the file-handle helpers from it; without it every
+  // scaffolded project failed to build with `Could not resolve: "./runtime-context"`.
+  'frontera/automation/runtime-context.ts',
   // `inputs.ts` is authoring surface too: `validateInputValue` is what a
   // handler's own tests and the Console call to check a value against the
   // manifest's `inputs` schema, and `index.ts` re-exports it — so omitting it

package/src/blueprint/tree.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, extname, join } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { BLUEPRINT_DATA_TYPES } from '../blueprint-types'
 import { CliError } from '../errors'
 import {
   ARTIFACT_KINDS,
@@ -47,6 +48,9 @@ export function readTree(root: string): AuthoredFile[] {
     for (const entry of readdirSync(directory).sort()) {
       const extension = extname(entry)
       if (!READABLE.has(extension)) continue
+      // Hidden files are not the author's: an editor's lock (Emacs `.#Name.yaml`
+      // is a dangling symlink) or swap file would otherwise fail the whole tree.
+      if (entry.startsWith('.') || entry.startsWith('#')) continue
       const relative = `${KIND_DIRECTORY[kind]}/${entry}`
       const document = parseDocument(relative, readFileSync(join(directory, entry), 'utf8'))
       const stem = entry.slice(0, -extension.length)
@@ -66,12 +70,35 @@ export function readTree(root: string): AuthoredFile[] {
           },
         )
       }
+      checkValueTypes(kind, relative, document)
       files.push({ kind, apiName, path: relative, document })
     }
   }
   return files
 }
 
+/**
+ * A value type the service does not know is refused here, naming the file,
+ * the field and the types there are. Left to the service it surfaced as
+ * "command — Expected union value", with neither the file nor the field.
+ */
+function checkValueTypes(kind: ArtifactKind, path: string, document: Record<string, unknown>): void {
+  const known = BLUEPRINT_DATA_TYPES as readonly string[]
+  const check = (field: string, valueType: unknown) => {
+    if (valueType === undefined || (typeof valueType === 'string' && known.includes(valueType))) return
+    throw new CliError(`${path}: ${field} has valueType "${String(valueType)}", which is not a Blueprint value type.`, {
+      code: 'USAGE',
+      hint: `Use one of: ${known.join(', ')}.`,
+    })
+  }
+  if (kind === 'object-type' && Array.isArray(document.properties)) {
+    for (const property of document.properties as Array<Record<string, unknown>>) {
+      check(`property "${String(property?.apiName ?? '?')}"`, property?.valueType)
+    }
+  }
+  if (kind === 'shared-field') check('the shared field', document.valueType)
+}
+
 /**
  * Delete a file the tree should no longer contain.
  *

package/src/commands/local/check.ts

@@ -0,0 +1,64 @@
+import { spawn } from 'node:child_process'
+
+import { CliError } from '../../errors'
+import { localProject } from '../../local/local-project'
+import { isAlive, readState } from '../../local/local-state'
+import { flagBool, type Command } from '../types'
+
+/**
+ * `frontera local check`: the whole loop as one command with one exit code,
+ * for a pre-push hook or CI (like `supabase start` then `supabase test`):
+ * start the runtime if it is not running, apply the solution, run the
+ * Agents' test cases. `--stop` stops the runtime afterwards.
+ */
+
+/** Run this CLI once more, its output passed straight through. */
+function runSelf(cwd: string, args: string[]): Promise<number> {
+  const compiled = Bun.main.startsWith('/$bunfs') || Bun.main.startsWith('B:\\~BUN')
+  const self = compiled ? [process.execPath] : [process.execPath, Bun.main]
+  return new Promise((resolve) => {
+    const child = spawn(self[0]!, [...self.slice(1), ...args], { cwd, stdio: ['ignore', 'inherit', 'inherit'] })
+    child.on('error', () => resolve(1))
+    child.on('close', (code) => resolve(code ?? 1))
+  })
+}
+
+export const localCheck: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'check',
+    args: [],
+    flags: { stop: 'boolean' },
+    summary: 'Start the runtime if needed, apply the project and run its test cases, with one exit code',
+    examples: ['frontera local check', 'frontera local check --stop'],
+    offline: true,
+    internal: true,
+  },
+
+  async run(ctx) {
+    const project = localProject(ctx.cwd)
+    const state = readState(project)
+    const running = state?.phase === 'ready' && !!state.supervisorPid && isAlive(state.supervisorPid)
+    const steps: Array<{ label: string; args: string[] }> = [
+      ...(running ? [] : [{ label: 'start', args: ['local', 'start'] }]),
+      { label: 'apply', args: ['local', 'dev', '--once'] },
+      { label: 'test', args: ['local', 'test'] },
+    ]
+    let failed: string | null = null
+    for (const step of steps) {
+      ctx.output.note(`── frontera ${step.args.join(' ')}`)
+      if ((await runSelf(project.root, step.args)) !== 0) {
+        failed = step.label
+        break
+      }
+    }
+    if (flagBool(ctx, 'stop')) {
+      ctx.output.note('── frontera local stop')
+      await runSelf(project.root, ['local', 'stop'])
+    }
+    if (failed) {
+      throw new CliError(`the check failed at ${failed}`, { code: 'LOCAL_CHECK_FAILED', hint: 'the output above names the cause' })
+    }
+    return { data: { passed: true }, text: 'Check passed: the project applies and its test cases pass.' }
+  },
+}

package/src/commands/local/dev.ts

@@ -0,0 +1,301 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import { existsSync, lstatSync, readFileSync, rmSync, watch, writeFileSync } from 'node:fs'
+import { join, sep } from 'node:path'
+
+import { CliError } from '../../errors'
+import { contentHash, loadHashes, saveHashes } from '../../local/local-applied'
+import { localProfileName } from '../../local/local-control'
+import {
+  allTargets,
+  blueprintObjectTypes,
+  byApplyOrder,
+  commandFor,
+  fallbackFor,
+  describeTarget,
+  followUpsFor,
+  targetFor,
+  type SyncProfiles,
+  type SyncTarget,
+} from '../../local/local-dev-sync'
+import { applyOperatingConfig } from '../../local/local-operating'
+import { localProject, type LocalProject } from '../../local/local-project'
+import { isAlive, readState, recordApplied } from '../../local/local-state'
+import { applyErrorText } from '../../local/local-apply-error'
+import { flagBool, type Command, type CommandContext } from '../types'
+
+/**
+ * `frontera local dev`: the inner loop. Applies the whole project to the
+ * local runtime once, then watches the folder and applies each saved file with
+ * the command an FDE would run by hand (`agent apply`, `workflow push`,
+ * `function deploy`, `blueprint apply`), one at a time, through the local
+ * profiles only. A Blueprint change is published and granted to the local
+ * workspace as well, unless `--no-publish` keeps it as a draft.
+ */
+
+const DEBOUNCE_MS = 300
+
+interface RunResult {
+  ok: boolean
+  output: string
+}
+
+/** The commands running now, so stopping `local dev` stops them too. */
+const children = new Set<ChildProcess>()
+
+function stopChildren(): void {
+  for (const child of children) child.kill('SIGTERM')
+}
+
+/** The local runtime's address and its keys by profile name, from the project's own state. */
+interface LocalAuth {
+  serviceUrl: string
+  keys: ReadonlyMap<string, string>
+}
+
+/**
+ * A command's credentials go in its environment (`FRONTERA_TOKEN` with
+ * `FRONTERA_API_URL`), taken from the project's state, in place of its
+ * `--profile`. So applying never reads or writes the person's CLI config or
+ * Keychain, and works inside a coding agent's sandbox (Codex's, Claude
+ * Code's), which allows the project folder and nothing else.
+ */
+function withLocalAuth(args: string[], auth: LocalAuth | undefined): { args: string[]; env: Record<string, string> } {
+  const at = args.indexOf('--profile')
+  const key = at >= 0 ? auth?.keys.get(args[at + 1] ?? '') : undefined
+  if (!auth || at < 0 || !key) return { args, env: {} }
+  return { args: [...args.slice(0, at), ...args.slice(at + 2)], env: { FRONTERA_TOKEN: key, FRONTERA_API_URL: auth.serviceUrl } }
+}
+
+/** Run this CLI once more, at low priority, in the solution folder. */
+function runCli(project: LocalProject, command: string[], auth?: LocalAuth): Promise<RunResult> {
+  const compiled = Bun.main.startsWith('/$bunfs') || Bun.main.startsWith('B:\\~BUN')
+  const self = compiled ? [process.execPath] : [process.execPath, Bun.main]
+  const { args, env } = withLocalAuth(command, auth)
+  return new Promise((resolve) => {
+    const child = spawn('nice', ['-n', '10', ...self, ...args], {
+      cwd: project.root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ...env, NO_COLOR: '1' },
+    })
+    children.add(child)
+    let output = ''
+    child.stdout.on('data', (chunk) => (output += chunk))
+    child.stderr.on('data', (chunk) => (output += chunk))
+    child.on('error', (err) => resolve({ ok: false, output: err.message }))
+    child.on('close', (code) => {
+      children.delete(child)
+      resolve({ ok: code === 0, output })
+    })
+  })
+}
+
+interface ApplyOptions {
+  profiles: SyncProfiles
+  auth: LocalAuth
+  publish: boolean
+  workspaceId: string
+  serviceUrl: string
+}
+
+async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptions): Promise<RunResult> {
+  const { profiles } = opts
+  if (target.kind === 'operating') {
+    // Read fresh: the owner session is renewed on every runtime start.
+    const creds = readState(project)?.credentials
+    if (!creds) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return applyOperatingConfig({ serviceUrl: opts.serviceUrl, creds, slug: target.slug, file: join(project.root, target.file) })
+  }
+  let result = await runCli(project, commandFor(target, profiles), opts.auth)
+  const fallback = fallbackFor(target, profiles, project.root)
+  if (!result.ok && fallback?.when.test(result.output)) {
+    // An empty fallback means there was nothing more to do.
+    result = { ok: true, output: '' }
+    for (const args of fallback.then) {
+      result = await runCli(project, args, opts.auth)
+      if (!result.ok) return result
+    }
+  }
+  if (!result.ok) return result
+  const objectTypes = target.kind === 'blueprint' ? blueprintObjectTypes(project.root) : []
+  for (const step of followUpsFor(target, profiles, { publish: opts.publish, workspaceId: opts.workspaceId, objectTypes })) {
+    const done = await runCli(project, step.args, opts.auth)
+    if (!done.ok && !step.alreadyDone?.test(done.output)) return done
+  }
+  return result
+}
+
+async function dev(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) {
+    throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
+  }
+  // The profile was registered when the runtime started; applying needs only the keys in the project's state.
+  const workspace = localProfileName(project)
+  const profiles: SyncProfiles = { workspace, organization: `${workspace}-org`.slice(0, 64) }
+  const creds = state.credentials!
+  const serviceUrl = `http://127.0.0.1:${state.ports.service}`
+  const options: ApplyOptions = {
+    profiles,
+    auth: {
+      serviceUrl,
+      keys: new Map([...(creds.workspaceKey ? [[profiles.workspace, creds.workspaceKey] as const] : []), [profiles.organization, creds.orgKey] as const]),
+    },
+    publish: !flagBool(ctx, 'no-publish'),
+    workspaceId: state.credentials!.workspaceId,
+    serviceUrl,
+  }
+
+  const organizationId = state.credentials!.organizationId
+  const applied = flagBool(ctx, 'reapply') ? new Map<string, string | null>() : loadHashes(project, organizationId)
+  let unchanged = 0
+  const pending = new Map<string, SyncTarget>()
+  // Files refused while something they depend on was missing; tried again after the next success.
+  const failed = new Map<string, SyncTarget>()
+  let failures = 0
+  let busy = false
+  let stopping = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const runOne = async (target: SyncTarget) => {
+    if (stopping) return
+    if (target.kind !== 'blueprint' && !existsSync(join(project.root, target.file))) return
+    const hash = contentHash(project, target)
+    if (hash && applied.get(target.key) === hash) {
+      unchanged += 1
+      return
+    }
+    const started = Date.now()
+    const result = await apply(project, target, options)
+    if (stopping) return
+    const ms = Date.now() - started
+    recordApplied(project, { at: new Date().toISOString(), what: describeTarget(target), ok: result.ok })
+    if (result.ok) {
+      // A draft-only Blueprint is not what a plain `local dev` would leave, so it is not recorded as applied.
+      if (target.kind === 'blueprint' && !options.publish) applied.delete(target.key)
+      else applied.set(target.key, hash)
+      saveHashes(project, organizationId, applied)
+      failed.delete(target.key)
+      ctx.output.note(`  ✓ ${describeTarget(target)} applied (${ms} ms)`)
+      for (const [key, retry] of failed) if (!pending.has(key)) pending.set(key, retry)
+      failed.clear()
+    } else {
+      failures += 1
+      failed.set(target.key, target)
+      ctx.output.note(`  ✕ ${describeTarget(target)}: ${applyErrorText(result.output)}`)
+    }
+  }
+
+  /** Apply what is queued, dependencies first, one at a time. Never throws: a bad file must not end the loop. */
+  const drain = async () => {
+    if (busy) return
+    busy = true
+    try {
+      while (pending.size && !stopping) {
+        const next = [...pending.values()].sort(byApplyOrder)[0]!
+        pending.delete(next.key)
+        try {
+          await runOne(next)
+        } catch (err) {
+          ctx.output.note(`  ✕ ${describeTarget(next)}: ${(err as Error).message}`)
+        }
+      }
+    } finally {
+      busy = false
+    }
+  }
+
+  const schedule = () => {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => void drain(), DEBOUNCE_MS)
+  }
+
+  /** What a changed path means: one file, every Function (a helper or the SDK changed), or a moved folder. */
+  const queuePath = (rel: string) => {
+    const absolute = join(project.root, rel)
+    const direct = targetFor(project.root, absolute)
+    if (direct) {
+      pending.set(direct.key, direct)
+      return
+    }
+    const top = rel.split(sep)[0]
+    const isDir = (() => {
+      try {
+        return lstatSync(absolute).isDirectory()
+      } catch {
+        return false
+      }
+    })()
+    const helper = (top === 'functions' || top === 'vendor') && /\.ts$/.test(rel) && !rel.endsWith('.test.ts')
+    if (!isDir && !helper) return
+    for (const target of allTargets(project.root)) {
+      const path = target.kind === 'blueprint' ? 'blueprint' : target.file
+      if (helper ? target.kind === 'function' : path === rel || path.startsWith(rel + sep)) pending.set(target.key, target)
+    }
+  }
+
+  // Watch from the start, so a save during the first sync is not missed.
+  const once = flagBool(ctx, 'once')
+  // One watcher per project (Forge keeps one running; a second would apply every change twice). `--once` is always allowed.
+  const pidFile = join(project.root, '.frontera', 'local', 'dev.pid')
+  if (!once) {
+    const other = existsSync(pidFile) ? Number(readFileSync(pidFile, 'utf8').trim()) : 0
+    if (other && other !== process.pid && isAlive(other)) {
+      throw new CliError(`\`frontera local dev\` is already watching this project (pid ${other})`, {
+        code: 'LOCAL_DEV_RUNNING',
+        hint: 'saved files are already being applied; run `frontera local dev --once` to apply now',
+      })
+    }
+    writeFileSync(pidFile, String(process.pid))
+  }
+  const watcher = once
+    ? null
+    : watch(project.root, { recursive: true }, (_event, filename) => {
+        if (!filename || stopping) return
+        queuePath(filename.toString())
+        if (!busy) schedule()
+      })
+
+  const targets = allTargets(project.root)
+  ctx.output.note(targets.length ? `Applying ${targets.length} item${targets.length === 1 ? '' : 's'} to the local runtime` : 'Nothing to apply yet')
+  for (const target of targets) pending.set(target.key, target)
+  await drain()
+  if (unchanged) ctx.output.note(`  ${unchanged} unchanged since the last apply (--reapply applies them again)`)
+
+  if (once) {
+    if (failures) throw new CliError(`${failures} of ${targets.length} failed to apply`, { code: 'LOCAL_APPLY_FAILED', hint: 'fix the files above and run again' })
+    const done = targets.length - unchanged
+    return { data: { applied: done, unchanged }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}` }
+  }
+
+  ctx.output.note('Watching datasets/, blueprint/, functions/, workflows/ and agents/ (Ctrl+C to stop)')
+  if (pending.size) schedule()
+
+  await new Promise<void>((resolve) => {
+    const stop = () => {
+      stopping = true
+      rmSync(pidFile, { force: true })
+      if (timer) clearTimeout(timer)
+      watcher?.close()
+      stopChildren()
+      resolve()
+    }
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+  })
+  return { data: { applied: applied.size }, text: 'Stopped watching' }
+}
+
+export const localDev: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'dev',
+    args: [],
+    flags: { once: 'boolean', 'no-publish': 'boolean', reapply: 'boolean' },
+    summary: 'Apply the project to the local runtime, then apply each saved file',
+    examples: ['frontera local dev', 'frontera local dev --once', 'frontera local dev --no-publish', 'frontera local dev --once --reapply'],
+    offline: true,
+    internal: true,
+  },
+  run: dev,
+}

package/src/commands/local/docs-mcp.ts

@@ -0,0 +1,36 @@
+import { docsCopyPath, serveDocsMcp } from '../../local/local-docs'
+import { localProject } from '../../local/local-project'
+import { cliSchema, readKeptSchema } from '../../local/local-schemas'
+import type { Command } from '../types'
+
+/**
+ * Frontera's documentation as an MCP server on stdio, for the coding agents
+ * working in this project. `local init` registers it in `.mcp.json` (Claude
+ * Code) and `.cursor/mcp.json`; Codex takes the same command. It reads the
+ * documentation `local start` copied for the release the runtime runs, and
+ * the formats of the project's files that start kept, so it needs no key and
+ * keeps working while the runtime is stopped. Nothing but protocol goes to
+ * stdout.
+ */
+export const localDocsMcp: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'docs-mcp',
+    args: [],
+    flags: {},
+    summary: "Serve Frontera's documentation to coding agents over MCP (stdio), for the local runtime's release",
+    examples: ['frontera local docs-mcp'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const project = localProject(ctx.cwd)
+    // Not started yet: it still speaks MCP, and each tool call says what to do.
+    await serveDocsMcp({
+      docsPath: docsCopyPath(project),
+      schemaFor: (kind) => cliSchema(kind) ?? readKeptSchema(project, kind),
+    })
+    // The stream is the protocol: exit here, before the CLI renders a result onto it.
+    process.exit(0)
+  },
+}