@frontera-sdk/cli 1.52.23 → 1.52.25

package/src/local/local-providers.ts

@@ -0,0 +1,268 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { configDir } from '../paths'
+import { HOST_FROM_CONTAINER, loadOrCreateSecrets } from './local-env'
+import { getKey } from './local-keys'
+import { localProject } from './local-project'
+import { call, signIn } from './local-seed'
+import { isAlive, readState } from './local-state'
+
+/**
+ * The model setup an FDE makes for their local runtimes, beyond the built-in
+ * providers' keys: OpenAI-compatible providers of their own (a gateway, Azure,
+ * a model served on this machine), the models Agents can pick, and which
+ * model new Agents and test grading use.
+ *
+ * It belongs to the person, not the project: it lives in the CLI's config
+ * directory, next to the keys, and every project's runtime receives it at
+ * start. Keys never go in this file; a custom provider's key sits in the
+ * keychain under `custom:<slug>`, like a built-in provider's.
+ */
+
+export interface CustomProviderSpec {
+  /** The provider's runtime id is `custom:<slug>`. */
+  slug: string
+  label: string
+  baseUrl: string
+}
+
+export interface ChosenModel {
+  /** `anthropic`, `openrouter`, `custom:<slug>`… */
+  provider: string
+  /** The provider's own id for the model. */
+  modelId: string
+  name: string
+  /** The catalog slug `agent.json` names, as the runtime gave it back. */
+  slug?: string
+}
+
+export interface ProviderSetup {
+  version: 1
+  custom: CustomProviderSpec[]
+  models: ChosenModel[]
+  defaults: {
+    /** The model a new Agent starts with (`frontera local init`, and what AGENTS.md tells coding agents). */
+    agentModel?: string
+    /** The model that grades test cases and evaluations. */
+    judgeModel?: string
+  }
+}
+
+const EMPTY: ProviderSetup = { version: 1, custom: [], models: [], defaults: {} }
+
+/** A custom provider's slug: lowercase letters, digits and hyphens, as the service requires. */
+export const CUSTOM_SLUG = /^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$/
+
+export const customKeyId = (slug: string) => `custom:${slug}`
+
+function setupPath(): string {
+  return process.env.FRONTERA_LOCAL_PROVIDERS_FILE ?? join(configDir(), 'local-providers.json')
+}
+
+export function readProviderSetup(): ProviderSetup {
+  const path = setupPath()
+  if (!existsSync(path)) return structuredClone(EMPTY)
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<ProviderSetup>
+    return { version: 1, custom: parsed.custom ?? [], models: parsed.models ?? [], defaults: parsed.defaults ?? {} }
+  } catch {
+    return structuredClone(EMPTY)
+  }
+}
+
+export function writeProviderSetup(setup: ProviderSetup): void {
+  writeFileAtomic(setupPath(), `${JSON.stringify(setup, null, 2)}\n`, 0o600)
+}
+
+/** A catalog slug from a model's name: `GPT-6 Luna` → `gpt-6-luna`. */
+export function modelSlug(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'model'
+}
+
+/**
+ * A base URL as the runtime's service must dial it: a service in a container
+ * reaches this machine through the host's name, not 127.0.0.1.
+ */
+export function serviceReachable(baseUrl: string, containerHost?: string): string {
+  if (!containerHost) return baseUrl
+  try {
+    const url = new URL(baseUrl)
+    if (url.hostname === '127.0.0.1' || url.hostname === 'localhost') url.hostname = containerHost
+    return url.toString().replace(/\/$/, '')
+  } catch {
+    return baseUrl
+  }
+}
+
+export interface RuntimeTarget {
+  serviceUrl: string
+  password: string
+  organizationId: string
+  workspaceId: string
+  /** Set when the service runs in a container (release images). */
+  containerHost?: string
+}
+
+/** The runtime of the project around `cwd`, when it is up; changes then apply at once instead of at the next start. */
+export function runningTarget(cwd: string): RuntimeTarget | null {
+  const project = localProject(cwd)
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid) || !state.credentials) return null
+  return {
+    serviceUrl: `http://127.0.0.1:${state.ports.service}`,
+    password: loadOrCreateSecrets(project).ownerPassword,
+    organizationId: state.credentials.organizationId,
+    workspaceId: state.credentials.workspaceId,
+    containerHost: state.mode === 'image' ? HOST_FROM_CONTAINER : undefined,
+  }
+}
+
+export interface ApplyResult {
+  custom: string[]
+  /** `provider/modelId` → the catalog slug the runtime uses. */
+  models: Record<string, string>
+  errors: string[]
+}
+
+type Catalog = { data?: Array<{ slug: string; provider: string; modelId: string }> }
+
+/**
+ * Bring a runtime in line with the setup: register each custom provider (with
+ * its key from the keychain), add each chosen model to the catalog, and make
+ * the chosen grading model the judge. Idempotent; it only adds and updates,
+ * and a refusal is reported, not thrown.
+ */
+export async function applyProviderSetup(target: RuntimeTarget, setup = readProviderSetup()): Promise<ApplyResult> {
+  const result: ApplyResult = { custom: [], models: {}, errors: [] }
+  let token: string
+  try {
+    token = await signIn(target.serviceUrl, target.password)
+  } catch (err) {
+    result.errors.push(`could not sign in to the runtime: ${(err as Error).message}`)
+    return result
+  }
+  const scope = { token, orgId: target.organizationId }
+
+  if (setup.custom.length) {
+    const list = await call<{ data?: Array<{ slug: string }> }>(target.serviceUrl, '/v1/admin/custom-providers', scope)
+    const existing = new Set((list.body?.data ?? []).map((p) => p.slug))
+    for (const spec of setup.custom) {
+      const key = getKey(customKeyId(spec.slug))
+      const baseUrl = serviceReachable(spec.baseUrl, target.containerHost)
+      const res = existing.has(spec.slug)
+        ? await call(target.serviceUrl, `/v1/admin/custom-providers/${spec.slug}`, { ...scope, method: 'PUT', body: { label: spec.label, baseUrl, ...(key ? { apiKey: key } : {}) } })
+        : // The service needs a key; an endpoint that takes none gets a placeholder.
+          await call(target.serviceUrl, '/v1/admin/custom-providers', { ...scope, body: { slug: spec.slug, label: spec.label, baseUrl, apiKey: key ?? 'none' } })
+      if (res.status < 300) result.custom.push(spec.slug)
+      else result.errors.push(`${spec.label}: the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+    }
+  }
+
+  if (setup.models.length) {
+    const catalog = await call<Catalog>(target.serviceUrl, '/v1/config/models/catalog', scope)
+    for (const model of setup.models) {
+      const key = `${model.provider}/${model.modelId}`
+      const found = catalog.body?.data?.find((m) => m.provider === model.provider && m.modelId === model.modelId)
+      if (found) {
+        result.models[key] = found.slug
+        continue
+      }
+      const res = await call<{ data?: { slug?: string } }>(target.serviceUrl, '/v1/config/models/catalog', {
+        ...scope,
+        body: { slug: model.slug ?? modelSlug(model.name), provider: model.provider, modelId: model.modelId, name: model.name, kind: 'text' },
+      })
+      // The runtime may answer with another slug (the pair existed, or the slug was taken).
+      if (res.status < 300 && res.body?.data?.slug) result.models[key] = res.body.data.slug
+      else result.errors.push(`${model.name}: the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+    }
+  }
+
+  // Models added before the service described reasoning (or by hand) get the levels their
+  // provider publishes, so an Agent's effort reaches the model. Only rows with none; a
+  // release without the route answers 404, which is fine.
+  const filled = await call(target.serviceUrl, '/v1/config/models/catalog/reasoning/fill', { ...scope, method: 'POST', body: {} })
+  if (filled.status >= 300 && filled.status !== 404) result.errors.push(`describing the models' reasoning: the runtime answered ${filled.status}`)
+
+  if (setup.defaults.judgeModel) {
+    const res = await call(target.serviceUrl, '/v1/eval/settings', {
+      ...scope,
+      workspaceId: target.workspaceId,
+      method: 'PATCH',
+      body: { judgeModelSlug: setup.defaults.judgeModel },
+    })
+    if (res.status >= 300) result.errors.push(`the grading model: the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+  }
+  return result
+}
+
+/** Record the slugs a runtime gave back, so `agent.json` and the defaults use what the runtime knows. */
+export function rememberSlugs(setup: ProviderSetup, applied: ApplyResult): ProviderSetup {
+  return {
+    ...setup,
+    models: setup.models.map((m) => ({ ...m, slug: applied.models[`${m.provider}/${m.modelId}`] ?? m.slug })),
+  }
+}
+
+async function session(target: RuntimeTarget) {
+  return { token: await signIn(target.serviceUrl, target.password), orgId: target.organizationId }
+}
+
+export interface CatalogModel {
+  slug: string
+  name: string
+  provider: string
+  modelId: string
+  kind?: string
+}
+
+/** The chat models Agents in the runtime can pick, by catalog slug. */
+export async function runtimeCatalog(target: RuntimeTarget): Promise<CatalogModel[]> {
+  const res = await call<{ data?: CatalogModel[] }>(target.serviceUrl, '/v1/config/models/catalog', await session(target))
+  return (res.body?.data ?? []).filter((m) => (m.kind ?? 'text') === 'text')
+}
+
+/** The workspace's grading model, read without changing it (an empty update answers with the settings). */
+export async function runtimeJudge(target: RuntimeTarget): Promise<string | null> {
+  const res = await call<{ data?: { judgeModelSlug?: string | null } }>(target.serviceUrl, '/v1/eval/settings', {
+    ...(await session(target)),
+    workspaceId: target.workspaceId,
+    method: 'PATCH',
+    body: {},
+  })
+  return res.body?.data?.judgeModelSlug ?? null
+}
+
+export interface AvailableModel {
+  id: string
+  name: string
+  reasoning?: boolean
+  contextLength?: number | null
+}
+
+/** What a provider offers to add, as the runtime lists it (OpenRouter and custom endpoints are asked live). */
+export async function availableModels(target: RuntimeTarget, provider: string): Promise<AvailableModel[]> {
+  const res = await call<{ data?: AvailableModel[] }>(target.serviceUrl, `/v1/config/providers/${encodeURIComponent(provider)}/models`, await session(target))
+  if (res.status >= 300) throw new Error(`the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+  return (res.body?.data ?? []).map((m) => ({ id: m.id, name: m.name, reasoning: m.reasoning, contextLength: m.contextLength }))
+}
+
+/** Take a model out of the runtime's catalog. */
+export async function removeRuntimeModel(target: RuntimeTarget, slug: string): Promise<void> {
+  const res = await call(target.serviceUrl, `/v1/config/models/catalog?slug=${encodeURIComponent(slug)}`, { ...(await session(target)), method: 'DELETE' })
+  if (res.status >= 300 && res.status !== 404) throw new Error(`the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+}
+
+/** Take a custom provider out of the runtime, with its models first (the runtime refuses it while models use it). */
+export async function removeRuntimeProvider(target: RuntimeTarget, slug: string): Promise<void> {
+  for (const model of (await runtimeCatalog(target)).filter((m) => m.provider === `custom:${slug}`)) await removeRuntimeModel(target, model.slug)
+  const res = await call(target.serviceUrl, `/v1/admin/custom-providers/${slug}`, { ...(await session(target)), method: 'DELETE' })
+  if (res.status >= 300 && res.status !== 404) throw new Error(`the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+}
+
+/** Forget a built-in provider's key in the runtime. */
+export async function removeRuntimeKey(target: RuntimeTarget, provider: string): Promise<void> {
+  const res = await call(target.serviceUrl, `/v1/admin/provider-credentials/${provider}`, { ...(await session(target)), method: 'DELETE' })
+  if (res.status >= 300 && res.status !== 404) throw new Error(`the runtime answered ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`)
+}

package/src/local/local-scaffold.ts

@@ -0,0 +1,404 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { AUTOMATION_SDK_FILES } from '../automation-template'
+import { AGENTS_MD } from '../harness'
+import vendored from '../vendor/sdk-sources.json'
+
+/**
+ * A new project in the layout `frontera local dev` applies: one Agent with a
+ * test case, one workflow, one Function, and a Blueprint object type with the
+ * dataset it reads. Each is small enough to read in a minute and works
+ * against the keyless local model as written.
+ *
+ * The Functions SDK is vendored into `vendor/frontera/` and resolved by the
+ * `paths` in `tsconfig.json`, the way `frontera function init` does it: the
+ * SDK packages are not published, and `function deploy` builds with Bun, which
+ * honours those paths.
+ */
+
+/** The starter Agent, on the model the FDE chose for new Agents; with none chosen yet it has no model until they add one. */
+const AGENT = (name: string, modelSlug?: string) =>
+  JSON.stringify(
+    {
+      config: { name: 'Assistant', description: `Answers questions for ${name}`, defaultMode: modelSlug ? 'default' : null },
+      modelConfigs: modelSlug ? [{ modeKey: 'default', modelSlug, displayName: 'Default', sortOrder: 0 }] : [],
+      prompts: [
+        {
+          filename: 'instructions.md',
+          kind: 'instructions',
+          content: 'You help people with their questions.\n\nAnswer in two or three sentences. When you do not know, say so.',
+          enabled: true,
+          sortOrder: 0,
+        },
+      ],
+    },
+    null,
+    2,
+  ) + '\n'
+
+/** Behavior settings: open-ended, with one customer variable the test setup can fill in. */
+const OPERATING = JSON.stringify(
+  {
+    version: 1,
+    execution: { harness: 'open-ended' },
+    variables: [
+      {
+        key: 'customer_name',
+        label: 'Customer name',
+        description: 'How to address the person writing in',
+        scope: 'end-customer',
+        type: 'text',
+        testValue: 'Sam',
+      },
+    ],
+  },
+  null,
+  2,
+) + '\n'
+
+const EVALS = `# Test cases for the assistant. Each case: a conversation, then what a good reply does.
+# \`frontera local test\` (or Evaluations in Studio) runs them against the draft.
+#
+# This one passes with the keyless local model, which repeats what it was told.
+# Once the Agent uses a real model, write expectations about the answer instead.
+cases:
+  - name: replies-to-a-greeting
+    conversation:
+      - user: Hello from a new project
+    expectedContains: [Hello from a new project]
+`
+
+const WORKFLOW = `apiVersion: workflow/v1
+name: hello
+description: Greets someone, to show a run end to end
+input:
+  name: { type: string, required: true, description: Who to greet }
+trigger:
+  - kind: manual
+nodes:
+  - id: greet
+    kind: transform
+    params:
+      value: { type: expr, expr: '"Hello, " & $input.name' }
+`
+
+const FUNCTION = `import { automation } from '@frontera-sdk/functions'
+
+export default automation(
+  {
+    name: 'word-count',
+    description: 'Counts the words in a piece of text.',
+    trigger: { manual: true, agent: true },
+    inputs: {
+      text: { type: 'string', required: true, description: 'The text to count' },
+    },
+  },
+  async (ctx) => {
+    const { text } = ctx.input as { text: string }
+    const words = text.trim().split(/\\s+/).filter(Boolean).length
+    await ctx.log('counted', { words })
+    return { words }
+  },
+)
+`
+
+const FUNCTION_TEST = `import { expect, test } from 'bun:test'
+
+import { createTestContext } from '@frontera-sdk/functions'
+
+import wordCount from './word-count'
+
+// A Function is a handler, so it is tested without a runtime: \`bun test\`.
+// The context refuses what the platform refuses (a grant the manifest does not
+// declare, a step name used twice), so a passing test means something.
+test('counts the words', async () => {
+  const { ctx, logs } = createTestContext({ input: { text: 'four words right here' } })
+  expect(await wordCount.handler(ctx)).toEqual({ words: 4 })
+  expect(logs.map((l) => l.message)).toEqual(['counted'])
+})
+`
+
+const README = (name: string) => `# ${name}
+
+A Frontera project. Every file here is applied to a local runtime by
+\`frontera local dev\` and tried in Frontera Studio.
+
+| Path | What it is |
+|---|---|
+| \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/evals/*.yaml\` | Its test cases |
+| \`workflows/<slug>.yaml\` | A workflow |
+| \`functions/<name>.ts\` | A Function |
+| \`datasets/<apiName>.json\` + \`.csv\` | Sample data the Blueprint reads |
+| \`blueprint/\` | The Blueprint: object types, links, metrics, actions |
+| \`fixtures/\` | Sample data for tests |
+
+## Develop
+
+\`\`\`bash
+frontera local start   # the runtimes, on this machine
+frontera local dev     # apply each file as you save it
+frontera local ui      # open Studio
+frontera local test    # run the Agents' test cases
+bun test               # run the Functions' unit tests, no runtime needed
+frontera local check   # start, apply and test in one command, before pushing
+\`\`\`
+
+An Agent's model is the catalog slug in \`modelSlug\` in its \`agent.json\`.
+\`frontera local providers\` lists the providers and models your runtimes
+have and the model new Agents start with. Add a provider's key with
+\`frontera local key-set <provider>\`, a provider of your own (a gateway,
+Azure, a model on this machine) with \`frontera local provider-add\`, and a
+model with \`frontera local model-add\`. An Agent needs a model with a key
+before it can be tried.
+
+## Add Blueprint objects
+
+An object type reads a dataset. Add \`datasets/<apiName>.json\` with its CSV
+beside it (see \`datasets/tickets.json\`), scaffold the object type, and point
+its \`backing\` at the dataset:
+
+\`\`\`bash
+frontera blueprint new object-type <Name>
+\`\`\`
+
+\`frontera local dev\` creates the dataset, loads a changed CSV as a new
+snapshot, and publishes the Blueprint to the local workspace.
+`
+
+const DATASET = JSON.stringify(
+  {
+    apiName: 'tickets',
+    displayName: 'Tickets',
+    kind: 'file',
+    path: './tickets.csv',
+    includedColumns: ['id', 'subject', 'status'],
+    keyColumns: ['id'],
+    deterministicKeyConfirmed: true,
+  },
+  null,
+  2,
+) + '\n'
+
+const DATASET_ROWS = `id,subject,status
+T-1,Cannot sign in,open
+T-2,Invoice total is wrong,closed
+T-3,Refund not received,open
+`
+
+const OBJECT_TYPE = `apiName: Ticket
+displayName: Ticket
+pluralDisplayName: Tickets
+primaryKey: id
+title: subject
+governance:
+  ownership:
+    kind: team
+    ownerId: blueprint-administration
+  sensitivity:
+    classification: internal
+    categories: []
+properties:
+  - apiName: id
+    displayName: ID
+    valueType: string
+    required: true
+    propertyType: attribute
+  - apiName: subject
+    displayName: Subject
+    valueType: string
+    required: false
+    propertyType: attribute
+  - apiName: status
+    displayName: Status
+    valueType: string
+    required: false
+    propertyType: attribute
+validations: []
+backing:
+  dataset: tickets
+  mapping:
+    id: id
+    subject: subject
+    status: status
+`
+
+/**
+ * The CLI's AGENTS.md, plus what a coding agent needs for this project. The
+ * \`local\` commands are internal and absent from \`frontera help\`, so an
+ * agent following the generic text alone would never find the loop.
+ */
+const SOLUTION_AGENTS_MD = `${AGENTS_MD}
+## This project
+
+The files here are the source of truth, developed against a Frontera runtime
+on this machine (\`frontera local\`). Nothing in this loop talks to a
+Frontera deployment.
+
+| Path | What it is |
+|---|---|
+| \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/evals/*.yaml\` | Its test cases: a conversation and what a good reply does |
+| \`workflows/<slug>.yaml\` | A workflow |
+| \`functions/<name>.ts\` | A Function (the SDK is vendored in \`vendor/\`) |
+| \`datasets/<apiName>.json\` + \`.csv\` | Sample data the Blueprint reads |
+| \`blueprint/\` | The Blueprint: object types, links, metrics, actions |
+
+The loop:
+
+1. \`frontera local start\` brings the runtime up (once; needs Docker).
+2. Edit files. Then run \`frontera local dev --once\`: it applies what
+   changed and prints each refused file's error and validation messages.
+   Fix those before going on. (A person may keep \`frontera local dev\`
+   running instead; it applies on save.)
+3. \`frontera local test\` runs the Agents' test cases and exits non-zero
+   when one fails. \`bun test\` runs the Functions' unit tests offline.
+4. Before handing work back, run \`frontera local check\`: it starts the
+   runtime if needed, applies everything and runs the test cases, and exits
+   non-zero at the first failure.
+5. \`frontera local status -o env\` prints the API URL and keys for scripts.
+
+\`frontera local <verb> --help\` documents each command; they are not
+listed by \`frontera help\`.
+
+## Documentation
+
+Frontera's documentation for the platform this project runs on is an MCP
+server here: \`frontera-docs\` in \`.mcp.json\` (Claude Code) and
+\`.cursor/mcp.json\` (Cursor); for Codex, add the command
+\`frontera local docs-mcp\` as an MCP server. Its tools search and read the
+same pages as the documentation in the platform, for the release the local
+runtime runs. Before writing or changing an \`agent.json\`, an
+\`operating.json\` (procedures, variables), a workflow, a Function or the
+Blueprint, search the documentation for it and follow what it says; do not
+guess a field or a step kind. It reads the documentation that
+\`frontera local start\` keeps for the runtime's release, so start the runtime
+once; after that it needs no key and works while the runtime is stopped.
+
+The guides describe the product and its concepts, mostly through its
+screens. The exact format of each file is a JSON Schema for the release the
+runtime runs: \`frontera local schema <kind>\` prints it, for \`operating\`,
+\`agent\`, \`workflow\`, \`evals\` and \`dataset\` (\`frontera local schema\`
+lists which file each one is), \`frontera local start\` keeps them in
+\`.frontera/local/schemas/\`, and the documentation server's
+\`read_file_schema\` tool returns them too. Read the schema before you write
+a file, rather than guessing a field or reading Frontera's source, and do
+not add a \`$schema\` key to a file: most files refuse a key they do not
+know. A schema checks a file's shape; what the file refers to (the action a
+step runs, the Function an action names) is checked when it is applied, and
+\`frontera local dev --once\` prints each refused file's validation messages.
+
+## Models
+
+An Agent's model is the catalog slug in \`modelSlug\` (\`agent.json\`).
+\`frontera local providers --json\` lists the models this machine's runtimes
+offer and the one new Agents start with; use those slugs. Keys, providers and the models offered are
+the person's to set (\`frontera local key-set\`, \`provider-add\`,
+\`model-add\`, or Forge's Models page): ask them rather than doing it, and
+never handle a key yourself.
+
+Change the files, not the runtime: \`local dev\` keeps the two in step, and
+a change made only on the runtime is lost on the next reset. A changed CSV
+must keep its dataset's columns.
+`
+
+/**
+ * Frontera's documentation for the coding agents working in the project:
+ * a stdio MCP server the harness launches. It reads the copy `local start`
+ * keeps, so there is no key and nothing secret in this file.
+ */
+const DOCS_MCP = `${JSON.stringify({ mcpServers: { 'frontera-docs': { command: 'frontera', args: ['local', 'docs-mcp'] } } }, null, 2)}\n`
+
+const GITIGNORE = `node_modules/
+.env
+`
+
+export function solutionScaffoldFiles(name: string, opts: { agentModel?: string } = {}): Record<string, string> {
+  const sdk = vendored.files as Record<string, string>
+  const out: Record<string, string> = {}
+  for (const rel of AUTOMATION_SDK_FILES) {
+    const content = sdk[rel]
+    if (content === undefined) throw new Error(`vendored SDK is missing ${rel} — run \`bun run sync:sdk\` in packages/frontera-cli`)
+    out[`vendor/${rel}`] = content
+  }
+
+  out['frontera.yaml'] = `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${name}\n`
+  out['README.md'] = README(name)
+  out['AGENTS.md'] = SOLUTION_AGENTS_MD
+  out['.gitignore'] = GITIGNORE
+  out['.mcp.json'] = DOCS_MCP
+  out['.cursor/mcp.json'] = DOCS_MCP
+  out['agents/assistant/agent.json'] = AGENT(name, opts.agentModel)
+  out['agents/assistant/operating.json'] = OPERATING
+  out['agents/assistant/evals/regression.yaml'] = EVALS
+  out['workflows/hello.yaml'] = WORKFLOW
+  out['functions/word-count.ts'] = FUNCTION
+  out['functions/word-count.test.ts'] = FUNCTION_TEST
+  out['datasets/tickets.json'] = DATASET
+  out['datasets/tickets.csv'] = DATASET_ROWS
+  out['blueprint/object-types/Ticket.yaml'] = OBJECT_TYPE
+  out['package.json'] =
+    JSON.stringify(
+      {
+        name,
+        private: true,
+        type: 'module',
+        scripts: { typecheck: 'tsc --noEmit', test: 'bun test' },
+        // The vendored manifest validates cron expressions with it.
+        dependencies: { 'cron-parser': '^5.0.6' },
+        devDependencies: { typescript: '^5.6.0', '@types/bun': 'latest' },
+      },
+      null,
+      2,
+    ) + '\n'
+  out['tsconfig.json'] =
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2022',
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: ['bun'],
+          baseUrl: '.',
+          paths: {
+            '@frontera-sdk/functions': ['./vendor/frontera/automation/index.ts'],
+            '@frontera-sdk/functions/*': ['./vendor/frontera/automation/*'],
+            '@frontera-sdk/blueprint/types': ['./vendor/frontera/blueprint/types.ts'],
+            '@frontera-sdk/blueprint/*': ['./vendor/frontera/blueprint/*'],
+          },
+        },
+        include: ['functions', 'vendor'],
+      },
+      null,
+      2,
+    ) + '\n'
+  return out
+}
+
+/**
+ * Write the files that are not there yet; with `force`, replace those that
+ * are. An AGENTS.md that is still the CLI's generic one is replaced anyway:
+ * nobody has changed it, and the project's version contains it.
+ */
+export function writeSolutionScaffold(target: string, name: string, force: boolean, opts: { agentModel?: string } = {}): { written: string[]; skipped: string[] } {
+  const written: string[] = []
+  const skipped: string[] = []
+  for (const [rel, content] of Object.entries(solutionScaffoldFiles(name, opts))) {
+    const full = join(target, rel)
+    const generic = rel === 'AGENTS.md' && existsSync(full) && readFileSync(full, 'utf8') === AGENTS_MD
+    if (existsSync(full) && !force && !generic) {
+      skipped.push(rel)
+      continue
+    }
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+    written.push(rel)
+  }
+  return { written, skipped }
+}