@frontera-sdk/cli 1.52.27 → 1.52.29

package/src/local/local-themes.ts

@@ -0,0 +1,201 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+import type { LocalCredentials } from './local-state'
+import type { SyncClient } from './local-sync-client'
+import type { RemoteItem } from './local-sync-plan'
+import { refName } from './local-sync-remote'
+
+/**
+ * Slide themes: the workspace's imported decks and custom themes, which an
+ * Agent's slides and images are made in (`createSlides`, `createImage`).
+ * Built-in themes live in code on every runtime; a workspace's own come down
+ * as `themes/<name>/theme.json` (name, style, tokens, layouts, reusable
+ * images) with the images beside it, and `local dev` saves each on the local
+ * runtime, so the Agent's decks look as they do in the workspace.
+ */
+
+/** A theme as `/v1/sync/slide-themes` lists it. */
+export interface ThemeRow {
+  id: string
+  name: string
+  styleDescription?: string | null
+  source?: string | null
+  tokens: Record<string, unknown>
+  slideCount?: number | null
+  layouts?: Array<{ kind: string; hint: string; imageKey?: string }>
+  assets?: Array<{ imageKey: string; name: string; mime: string }>
+  thumbnailKey?: string | null
+}
+
+/** The file a theme keeps in a project. */
+export interface ThemeFile {
+  name: string
+  styleDescription?: string
+  source?: string
+  tokens: Record<string, unknown>
+  slideCount?: number
+  layouts?: Array<{ kind: string; hint: string; image?: string }>
+  assets?: Array<{ name: string; mime: string; file: string }>
+  thumbnail?: string
+}
+
+/** Each theme's name in a project (`theme/acme-brand`), numbered when two would share one: the index's rule. */
+export function themeNames(rows: Array<{ id: string; name: string }>): Map<string, string> {
+  const out = new Map<string, string>()
+  const taken = new Set<string>()
+  for (const row of [...rows].sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id))) {
+    const base = refName(row.name)
+    let name = base
+    for (let n = 2; taken.has(name); n++) name = `${base}-${n}`
+    taken.add(name)
+    out.set(row.id, name)
+  }
+  return out
+}
+
+/** A storage key's last segment, as the theme's folder names the file. */
+const fileOf = (key: string) => basename(key).replace(/[^A-Za-z0-9._-]/g, '-').replace(/^[^A-Za-z0-9]+/, '') || 'file'
+
+/** An image larger than this stays on the platform, named in the theme's notes. */
+const IMAGE_LIMIT = 20 * 1024 * 1024
+
+/**
+ * The workspace's themes as project items: `theme.json`, and each image as an
+ * asset beside it, read from the theme's file route. An image that cannot be
+ * read is left out of the file too, and named.
+ */
+export async function readThemes(ws: SyncClient, rows: ThemeRow[], wanted: (ref: string) => boolean, warnings: string[]): Promise<RemoteItem[]> {
+  const names = themeNames(rows)
+  const out: RemoteItem[] = []
+  for (const row of rows) {
+    const name = names.get(row.id)!
+    const ref = `theme/${name}`
+    if (!wanted(ref)) continue
+    const it: RemoteItem = { ref, kind: 'theme', name, title: row.name, files: {}, unresolved: [], notes: [], requires: [], id: row.id, assets: [] }
+    const files = new Map<string, string>()
+    const left: string[] = []
+    const fetch = async (key: string | null | undefined): Promise<string | undefined> => {
+      if (!key) return undefined
+      if (files.has(key)) return files.get(key)
+      let file = fileOf(key)
+      for (let n = 2; [...files.values()].includes(file); n++) file = `${n}-${fileOf(key)}`
+      try {
+        const bytes = await ws.getBytes(`/v1/sync/slide-themes/${encodeURIComponent(row.id)}/file?key=${encodeURIComponent(key)}`)
+        if (bytes.byteLength > IMAGE_LIMIT) throw new Error('larger than 20 MB')
+        it.assets!.push({ path: `themes/${name}/${file}`, bytes })
+        files.set(key, file)
+        return file
+      } catch (err) {
+        warnings.push(`Slide theme ${row.name}: ${file}: ${(err as Error).message}`)
+        left.push(file)
+        return undefined
+      }
+    }
+    const layouts: NonNullable<ThemeFile['layouts']> = []
+    for (const l of row.layouts ?? []) {
+      const image = await fetch(l.imageKey)
+      layouts.push({ kind: l.kind, hint: l.hint, ...(image ? { image } : {}) })
+    }
+    const assets: NonNullable<ThemeFile['assets']> = []
+    for (const a of row.assets ?? []) {
+      const file = await fetch(a.imageKey)
+      if (file) assets.push({ name: a.name, mime: a.mime, file })
+    }
+    const thumbnail = await fetch(row.thumbnailKey)
+    const doc: ThemeFile = {
+      name: row.name,
+      ...(row.styleDescription ? { styleDescription: row.styleDescription } : {}),
+      ...(row.source ? { source: row.source } : {}),
+      tokens: row.tokens,
+      ...(row.slideCount ? { slideCount: row.slideCount } : {}),
+      ...(layouts.length ? { layouts } : {}),
+      ...(assets.length ? { assets } : {}),
+      ...(thumbnail ? { thumbnail } : {}),
+    }
+    it.files[`themes/${name}/theme.json`] = `${JSON.stringify(doc, null, 2)}\n`
+    const n = it.assets!.length
+    if (n) it.notes.push(n === 1 ? '1 image (a slide reference, background or logo) comes too; a copy the project already has is kept' : `${n} images (slide references, backgrounds, logos) come too; any the project already has are kept`)
+    if (left.length) it.notes.push(`Not brought, so the theme is used without ${left.length === 1 ? 'it' : 'them'} here: ${left.join(', ')}`)
+    if (!it.assets!.length) delete it.assets
+    out.push(it)
+  }
+  return out
+}
+
+/** What `local dev` reads of a theme's folder: its file and the images it names. */
+export function readThemeFolder(root: string, name: string): { doc: ThemeFile; files: Array<{ name: string; mime: string; data: string }>; missing: string[] } | null {
+  const dir = join(root, 'themes', name)
+  const path = join(dir, 'theme.json')
+  if (!existsSync(path)) return null
+  const doc = JSON.parse(readFileSync(path, 'utf8')) as ThemeFile
+  const named = [...new Set([...(doc.layouts ?? []).flatMap((l) => (l.image ? [l.image] : [])), ...(doc.assets ?? []).map((a) => a.file), ...(doc.thumbnail ? [doc.thumbnail] : [])])]
+  const present = new Set(readdirSync(dir))
+  const missing = named.filter((n) => !present.has(n))
+  const mimeOf = (file: string) => doc.assets?.find((a) => a.file === file)?.mime ?? (/\.png$/i.test(file) ? 'image/png' : /\.jpe?g$/i.test(file) ? 'image/jpeg' : /\.svg$/i.test(file) ? 'image/svg+xml' : /\.gif$/i.test(file) ? 'image/gif' : 'application/octet-stream')
+  const files = named.filter((n) => present.has(n)).map((n) => ({ name: n, mime: mimeOf(n), data: readFileSync(join(dir, n)).toString('base64') }))
+  return { doc, files, missing }
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+export function themeCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Call {
+  return async (method, path, body) => {
+    const res = await fetcher(new URL(path, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${creds.session}`,
+        'x-org-id': creds.organizationId,
+        'x-workspace-id': creds.workspaceId,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
+const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown } | null
+  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+}
+
+/**
+ * Save a project's theme on the runtime: the runtime's theme of the same name
+ * is replaced (themes have no edit), so the Agent's gallery holds one. An
+ * image the file names but the folder lacks is said, and the theme is saved
+ * without it.
+ */
+export async function applyTheme(root: string, name: string, call: Call): Promise<{ ok: boolean; output: string }> {
+  const read = readThemeFolder(root, name)
+  if (!read) return { ok: false, output: `error [THEME]: themes/${name}/theme.json is missing` }
+  const { doc, files, missing } = read
+  const lines: string[] = []
+  const keep = new Set(files.map((f) => f.name))
+  const theme = {
+    ...doc,
+    layouts: doc.layouts?.map((l) => (l.image && !keep.has(l.image) ? { kind: l.kind, hint: l.hint } : l)),
+    assets: doc.assets?.filter((a) => keep.has(a.file)),
+    thumbnail: doc.thumbnail && keep.has(doc.thumbnail) ? doc.thumbnail : undefined,
+  }
+  for (const m of missing) lines.push(`  warning: theme ${name}: ${m} is not in themes/${name}/, so the theme is used without it`)
+  const listed = await call('GET', '/v1/slide-themes')
+  if (listed.status >= 400) return { ok: false, output: `error [THEME]: ${errorOf(listed)}` }
+  const existing = (((listed.body as { data?: unknown })?.data ?? listed.body) as Array<{ id: string; name: string; source?: string; canDelete?: boolean }>) ?? []
+  const saved = await call('POST', '/v1/slide-themes', { theme, files })
+  if (saved.status >= 400) return { ok: false, output: `error [THEME]: ${errorOf(saved)}` }
+  // The new one is saved; the one it replaces goes (built-ins cannot, and are never named alike).
+  for (const old of existing.filter((t) => t.name === doc.name && t.source !== 'builtin' && t.canDelete !== false)) {
+    const gone = await call('DELETE', `/v1/slide-themes/${encodeURIComponent(old.id)}`)
+    if (gone.status >= 400 && gone.status !== 404) lines.push(`  warning: theme ${name}: the earlier copy could not be removed (${errorOf(gone)})`)
+  }
+  lines.unshift(`  saved slide theme ${doc.name}`)
+  return { ok: true, output: lines.join('\n') }
+}

package/src/local/local-workflow-state.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { promoteWorkflow } from './local-dev-references'
+import type { LocalProject } from './local-project'
+import { readLock } from './local-sync-plan'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * A workflow on the local runtime as it is in the workspace (design §8).
+ *
+ * `local dev` pushes every workflow as a draft. One that is live in the
+ * workspace (the lock records it at the pull) is promoted after each push,
+ * so its cron, webhook and Plugin triggers fire locally too, and its
+ * triggers are switched on or off as they are there.
+ *
+ * Safe locally: a trigger that fires on its own (a schedule, a Plugin's
+ * event) in a workflow with a step that calls another system directly (an
+ * HTTP step, a Plugin step) would make the same calls the workspace's runs
+ * make, twice over. Such a workflow is promoted with its triggers off here,
+ * and says so; it runs when started by hand, an Agent or a webhook.
+ */
+
+type Doc = Record<string, unknown>
+
+/** The kinds of the triggers that start runs on their own. */
+export function selfFiringTriggers(doc: unknown): string[] {
+  // The definition lists them under `trigger`, as the service's schema names it.
+  const triggers = Array.isArray((doc as Doc | null)?.trigger) ? ((doc as Doc).trigger as Doc[]) : []
+  return [...new Set(triggers.flatMap((t) => (t?.kind === 'cron' || t?.kind === 'plugin' ? [String(t.kind)] : [])))]
+}
+
+/** The ids of steps that call another system directly, at any depth (branches, loops, parallel arms). */
+export function externalSteps(doc: unknown): string[] {
+  const out: string[] = []
+  const visit = (v: unknown, inNodes: boolean) => {
+    if (Array.isArray(v)) return v.forEach((x) => visit(x, inNodes))
+    if (!v || typeof v !== 'object') return
+    const o = v as Doc
+    if (inNodes && (o.kind === 'http' || o.kind === 'plugin') && typeof o.id === 'string') out.push(o.id)
+    for (const [k, x] of Object.entries(o)) if (k !== 'trigger' && k !== 'layout') visit(x, true)
+  }
+  visit((doc as Doc | null)?.nodes ?? [], true)
+  return out
+}
+
+const WORDS: Record<string, string> = { cron: 'schedule', plugin: 'Plugin trigger' }
+
+/** What a workflow's triggers should be here: on as in the workspace, unless firing them would reach outside. */
+export function localTriggersOn(doc: unknown, enabledInWorkspace: boolean): { on: boolean; why?: string } {
+  if (!enabledInWorkspace) return { on: false }
+  const firing = selfFiringTriggers(doc)
+  const external = externalSteps(doc)
+  if (!firing.length || !external.length) return { on: true }
+  const which = firing.map((k) => WORDS[k] ?? k).join(' and ')
+  return { on: false, why: `Its ${which} doesn’t fire here: steps ${external.join(', ')} call other systems, as the workspace’s runs do; start it by hand, from an Agent or by its webhook` }
+}
+
+/** The `decide` steps of a workflow, at any depth: id and the model each asks. */
+export function decideSteps(doc: unknown): Array<{ id: string; model: string }> {
+  const out: Array<{ id: string; model: string }> = []
+  const visit = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Doc
+    if (o.kind === 'decide' && typeof o.id === 'string') out.push({ id: o.id, model: String((o.params as Doc | undefined)?.model ?? DECIDE_DEFAULT_MODEL) })
+    for (const x of Object.values(o)) visit(x)
+  }
+  visit((doc as Doc | null)?.nodes ?? [])
+  return out
+}
+
+/** The model a `decide` step asks when it names none (the service's `DECIDE_DEFAULT_MODEL`). */
+const DECIDE_DEFAULT_MODEL = 'typesafe/jev-1.13'
+
+/**
+ * A decide step asks its model through OpenRouter's decisions API with the
+ * organization's OpenRouter key, whatever model the Agents use, so its model
+ * is not swapped for one in the runtime's catalog: it needs that key here.
+ * Without one, it says so (an adaptation) instead of failing at the first run.
+ */
+export function decideStepNotes(project: LocalProject, file: string, creds: LocalCredentials): string[] {
+  let doc: unknown = null
+  try {
+    doc = parseYaml(readFileSync(join(project.root, file), 'utf8'))
+  } catch {
+    return []
+  }
+  const steps = decideSteps(doc)
+  if (!steps.length || creds.modelProviders?.includes('openrouter')) return []
+  return [`  warning: Decide step${steps.length === 1 ? '' : 's'} ${steps.map((s) => s.id).join(', ')} ask${steps.length === 1 ? 's' : ''} ${[...new Set(steps.map((s) => s.model))].join(', ')} through OpenRouter, and this runtime has no OpenRouter key: add one in Forge → Models`]
+}
+
+async function setEnabled(serviceUrl: string, creds: LocalCredentials, slug: string, enabled: boolean): Promise<string | null> {
+  try {
+    const res = await fetch(new URL(`/v1/workflows/${encodeURIComponent(slug)}`, serviceUrl), {
+      method: 'PATCH',
+      headers: { authorization: `Bearer ${creds.workspaceKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ enabled }),
+    })
+    return res.ok ? null : `${res.status} ${(await res.text()).slice(0, 200)}`
+  } catch (err) {
+    return (err as Error).message
+  }
+}
+
+/**
+ * After a push: promote and switch triggers as in the workspace, for a
+ * workflow the lock says is live there. Returns lines for the apply's output;
+ * a `warning:` line is an adaptation in the build.
+ */
+export async function mirrorWorkflowState(project: LocalProject, slug: string, file: string, serviceUrl: string, creds: LocalCredentials): Promise<string[]> {
+  const state = readLock(project.root)?.items[`workflow/${slug}`]?.state
+  if (!state?.live || !creds.workspaceKey) return []
+  let doc: unknown = null
+  try {
+    doc = parseYaml(readFileSync(join(project.root, file), 'utf8'))
+  } catch {
+    return []
+  }
+  const lines: string[] = []
+  const promoted = await promoteWorkflow(serviceUrl, creds, slug)
+  if (promoted) lines.push(`  promoted workflow ${slug} v${promoted}: it is live in the workspace`)
+  const want = localTriggersOn(doc, state.enabled)
+  const failed = await setEnabled(serviceUrl, creds, slug, want.on)
+  if (failed) lines.push(`  warning: Its triggers could not be switched ${want.on ? 'on' : 'off'} here: ${failed}`)
+  else if (want.why) lines.push(`  warning: ${want.why}`)
+  return lines
+}