@frontera-sdk/cli 1.43.9 → 1.44.0

package/README.md

@@ -9,13 +9,15 @@ bunx @frontera-sdk/cli --help
 ```bash
 frontera login
 frontera app init shipments-console
-cd shipments-console && bun install && bun run dev
+cd shipments-console && bun install
+frontera app dev
 ```
 
-Then open **`/dev-host.html`**, not `/`. An app served straight from Vite never
-mounts: the handshake refuses a parent that is not the platform, and renders a
-panel saying so. The dev host frames the app and plays the host side of the
-bridge, so it mounts and reads real data.
+New Apps are Next.js static exports by default. `frontera app dev` starts Next
+on loopback and a separate authenticated session broker. The stored workspace
+key never enters browser JavaScript or `.env.local`; the browser receives only
+a short-lived, App-scoped token. Existing Vite Apps remain supported with
+`--framework react` and their legacy `dev-host.html` flow.
 
 ## The commands
 
@@ -24,12 +26,15 @@ project) and `frontera app init` (scaffold a new app) are different commands.
 
 | | |
 |---|---|
-| `frontera app init <name>` | scaffold a new app |
+| `frontera app init <name>` | scaffold a Next.js static App |
+| `frontera app init <name> --framework react` | scaffold a legacy Vite App |
+| `frontera app dev` | run locally with authenticated Blueprint access |
 | `frontera app pull <slug>` | fetch an existing app's source |
 | `frontera app save` | package the working tree to storage |
 | `frontera app deploy` | build output → an immutable version |
 | `frontera app list` / `versions` | what exists, what is live |
 | `frontera blueprint list` / `get` | what data an app can read |
+| `frontera blueprint generate-types` | generate committed App-local types from that data contract |
 
 `frontera help --json` returns the whole table as data.
 
@@ -38,13 +43,136 @@ project) and `frontera app init` (scaffold a new app) are different commands.
 `0` success · `1` transient · `2` usage · `3` conflict · `4` auth. Branch on
 them rather than on message text.
 
-## Scaffolded apps carry the SDK
+## Project configuration
 
-`frontera app init` writes `@frontera-sdk/core` and `@frontera-sdk/blueprint` into
-`src/frontera/` and resolves the `@frontera-sdk/…` specifiers with tsconfig paths
-and a matching Vite alias, so a new app installs with nothing but public npm.
-`frontera app pull` repairs a tree that predates that — including one whose
-dependencies point at paths on the machine that published it.
+`package.json` remains standard package metadata: package identity, scripts,
+dependencies, development dependencies, and package-manager metadata.
+Frontera's artifact contract lives in `frontera.config.json`:
+
+```json
+{
+  "displayName": "shipments-console",
+  "outputDirectory": "out",
+  "routing": "filesystem",
+  "connectDomains": [],
+  "resourceDomains": []
+}
+```
+
+`runtime` is always static; `routing` describes the artifact rather than the
+framework that produced it. The environment-specific App binding is written to
+gitignored `.frontera/state.json`. Existing projects that already use
+`package.json#frontera` remain readable, but new scaffolds do not add it.
+
+Next Apps consume the published `@frontera-sdk/core` and
+`@frontera-sdk/blueprint` packages. Existing Vite Apps retain vendored SDK
+source; `frontera app sdk sync` refreshes only that generated tree.
+
+## What `app init` does
+
+It refuses before it writes, then finishes the job:
+
+1. Rejects a name `package.json` would reject — with the name that would have
+   worked — and refuses to scaffold over a directory that already holds work.
+2. Writes the project, its `AGENTS.md`, and its pattern skills.
+3. Runs `bun install`. A machine with no network gets a reported skip and a
+   `bun install` line in the next steps, never a failed command.
+4. Adds the baseline shadcn components — `button`, `input`, `table`,
+   `skeleton`, `card`, `alert` — which the reference feature imports.
+5. Creates a repository and an initial commit, unless it is already inside one.
+   A repository that cannot be committed to is removed rather than left half
+   made.
+
+`--no-install`, `--no-components` and `--no-git` opt out of the last three.
+Progress goes to stderr, so `--json` still returns nothing but the result
+document.
+
+## Components come from shadcn
+
+Apps do not carry a component library this repository maintains. `components.json`
+is configured for the project as scaffolded — Tailwind v4, `src/app/globals.css`,
+the `@/` aliases, `cn` from `@/lib/utils` — so anything upstream publishes drops
+in unmodified:
+
+```bash
+bunx --bun shadcn@latest add dialog dropdown-menu tabs
+```
+
+Two details make that work and are asserted by the scaffold tests. Every item in
+the shadcn registry declares **no npm dependencies**, so the scaffold declares
+what they import — `class-variance-authority`, `radix-ui`, `lucide-react`,
+`tw-animate-css`. And the platform stylesheet already defines every token
+upstream references, so `add` leaves it untouched; `shadcn init` would replace
+it with the vanilla palette, which is why nothing runs it.
+
+`frontera app add` remains for Frontera-specific compositions — `app-page`,
+`page-header`, `stat-tile`, `filter-bar`, `data-table` — that upstream has no
+equivalent for.
+
+## What a new App contains
+
+`frontera app init` writes a project that already demonstrates the patterns its
+skills describe, because an agent copies the nearest file rather than the
+nearest paragraph:
+
+```text
+src/app/                    route adapters: layout, providers, one thin page
+src/ui/app-shell/           the frame, aware of embedded vs standalone
+src/ui/object-explorer/     reference feature — entry, components/, hooks/, utils, types
+src/lib/blueprint/          the data layer, with tests over its pure helpers
+src/lib/copy.ts             user-visible strings
+src/components/ui/          shadcn primitives, fetched at init
+components.json             shadcn CLI configuration for this project
+AGENTS.md / CLAUDE.md       the entry point that routes an agent to the skills
+.agents/skills/             thirteen pattern skills, dispatcher first
+```
+
+The reference feature reads any object type by name, so it works before a data
+model is known: search debounced into a server-side filter, paged reads, a total
+from a separate aggregate over the same object set, a content-shaped skeleton,
+dimmed background refetches, and distinct empty and error states.
+
+`bun run check` — typecheck, then `bun test`, then `next build` — is the gate a
+scaffolded project ships with, and the one its skills tell an agent to run
+before claiming a change works.
+
+## Blueprint types
+
+From an authenticated App project, generate the active workspace-granted
+Blueprint contract:
+
+```bash
+bun run blueprint:types
+git add src/generated/frontera-blueprint.ts
+```
+
+The generated file is deterministic and contains API names and TypeScript
+types, never server IDs, credentials, origins, or timestamps. Commit it so
+ordinary installs and builds remain offline and reproducible. An authenticated
+CI job may check freshness without writing:
+
+```bash
+bun run blueprint:types:check
+```
+
+Generation is intentionally not part of install, build, local development, or
+deployment. Use `--output <relative.ts>` for a different committed location.
+
+## Build and release
+
+Build on the FDE laptop or in customer CI, then upload the immutable result:
+
+```bash
+bun run typecheck
+bun run build
+frontera app deploy --no-promote
+frontera app versions
+frontera app promote 0.1.0
+```
+
+The CLI packages the configured output directory and records packaging
+provenance. The service independently computes the authoritative artifact
+digest, file count, byte count, and uploader.
 
 ## It runs on Bun, not Node
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.43.9",
+  "version": "1.44.0",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -37,8 +37,8 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.43.6",
-    "@frontera-sdk/core": "1.43.6",
+    "@frontera-sdk/automation": "1.43.10",
+    "@frontera-sdk/core": "1.43.10",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },

package/src/adopt.ts

@@ -0,0 +1,436 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { UsageError } from './errors'
+import { nextSkillFiles } from './templates/next-skills'
+
+/**
+ * Turn an existing Next.js project into a Frontera App.
+ *
+ * `frontera app init <name>` creates a project. This is the other half, and it
+ * is the half an FDE actually meets: the customer already has an app, or the
+ * work starts from `create-next-app`, and "scaffold a new one and copy your
+ * code across" is not an answer.
+ *
+ * The shape is borrowed from `shadcn init`, whose whole decision is one check —
+ * a `package.json` at the target means initialise in place, its absence means
+ * create — and whose preflight REFUSES rather than guesses: an undetected
+ * framework, a missing Tailwind entry or an existing `components.json` each
+ * stop the command with a specific message. A half-configured project is worse
+ * than an unconfigured one, because the author cannot tell which half is theirs.
+ *
+ * What follows from that here: this module writes files that did not exist and
+ * adds keys that were missing, and everything it cannot do SAFELY it reports as
+ * a manual step with the exact edit. It never rewrites a config file, a layout
+ * or a stylesheet someone else wrote — those are the three files where a clever
+ * codemod is indistinguishable from vandalism when it guesses wrong.
+ */
+
+export interface AdoptionTarget {
+  root: string
+  /** Where the App Router lives, relative to the root: `src/app` or `app`. */
+  appDir: string
+  /** True when the project keeps sources under `src/`. */
+  srcDir: boolean
+  /** The Tailwind entry stylesheet, relative to the root. */
+  css: string
+  /** The `@/…` style import alias, read from tsconfig rather than assumed. */
+  alias: string
+  /** Path of the Next config file, relative to the root. */
+  nextConfig: string | null
+  packageName: string
+  /** Already a Frontera App — adoption is a no-op unless forced. */
+  alreadyAdopted: boolean
+}
+
+interface PackageJson {
+  name?: string
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  scripts?: Record<string, string>
+}
+
+function readJson<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Establish that this directory can become an App, or say precisely why not.
+ *
+ * Every refusal names the thing that is missing. "We could not detect a
+ * supported framework" is worth more than a stack trace three files later, and
+ * it is the reason shadcn's preflight is a list of specific checks rather than
+ * one try/catch.
+ */
+export function detectAdoption(root: string): AdoptionTarget {
+  const pkg = readJson<PackageJson>(join(root, 'package.json'))
+  if (!pkg) {
+    throw new UsageError(
+      `no package.json in ${root}`,
+      'run `frontera app init <name>` to create a project, or cd into an existing one',
+    )
+  }
+
+  const dependencies = { ...pkg.devDependencies, ...pkg.dependencies }
+  if (!dependencies.next) {
+    throw new UsageError(
+      'this project does not depend on Next.js',
+      'Frontera Apps are Next.js projects — `frontera app init <name>` scaffolds one',
+    )
+  }
+
+  // A monorepo root is a real place to run this by accident, and adopting it
+  // would write an App manifest next to a workspace list.
+  const workspaces = (readJson<{ workspaces?: unknown }>(join(root, 'package.json')) ?? {}).workspaces
+  if (workspaces && !existsSync(join(root, 'app')) && !existsSync(join(root, 'src/app'))) {
+    throw new UsageError(
+      `${root} looks like a workspace root, not an App`,
+      'cd into the package that holds the Next.js app and run this there',
+    )
+  }
+
+  const srcDir = existsSync(join(root, 'src/app'))
+  const appDir = srcDir ? 'src/app' : 'app'
+  if (!existsSync(join(root, appDir, 'layout.tsx')) && !existsSync(join(root, appDir, 'layout.jsx'))) {
+    throw new UsageError(
+      'could not find an App Router layout',
+      'Frontera Apps use the Next App Router — expected app/layout.tsx or src/app/layout.tsx',
+    )
+  }
+
+  const css = [`${appDir}/globals.css`, `${appDir}/global.css`, 'styles/globals.css']
+    .find((candidate) => existsSync(join(root, candidate)))
+  if (!css) {
+    throw new UsageError(
+      'could not find a Tailwind entry stylesheet',
+      `expected ${appDir}/globals.css — Frontera Apps style with Tailwind v4`,
+    )
+  }
+
+  const tsconfig = readJson<{ compilerOptions?: { paths?: Record<string, string[]> } }>(
+    join(root, 'tsconfig.json'),
+  )
+  const paths = tsconfig?.compilerOptions?.paths ?? {}
+  // Read the alias rather than assuming `@/*`: a project with no `src/` maps it
+  // to `./*`, and writing imports against the wrong one produces a scaffold
+  // that resolves nothing.
+  const aliasEntry = Object.entries(paths).find(([, targets]) =>
+    targets.some((target) => target === (srcDir ? './src/*' : './*')),
+  )
+  if (!aliasEntry) {
+    throw new UsageError(
+      'could not find an import alias in tsconfig.json',
+      `add "paths": { "@/*": ["./${srcDir ? 'src/' : ''}*"] } to compilerOptions, then run this again`,
+    )
+  }
+
+  const nextConfig = ['next.config.ts', 'next.config.mjs', 'next.config.js']
+    .find((candidate) => existsSync(join(root, candidate))) ?? null
+
+  return {
+    root,
+    appDir,
+    srcDir,
+    css,
+    alias: aliasEntry[0].replace(/\/\*$/, ''),
+    nextConfig,
+    packageName: pkg.name ?? 'app',
+    alreadyAdopted: existsSync(join(root, 'frontera.config.json')),
+  }
+}
+
+export interface AdoptionPlan {
+  /** New files, keyed by path relative to the root. Never overwrites. */
+  files: Record<string, string>
+  /** Dependencies to add, with the ranges the scaffold pins. */
+  dependencies: Record<string, string>
+  /** Development dependencies to add. */
+  devDependencies: Record<string, string>
+  /** Scripts to add. Existing scripts are never replaced. */
+  scripts: Record<string, string>
+  /** Edits this command will not make for you, with the exact change. */
+  manual: string[]
+}
+
+/**
+ * What a Frontera App needs that a plain Next.js project does not have.
+ *
+ * The shadcn packages are here for the same reason the scaffold declares them:
+ * this command writes `lib/utils.ts` and `components.json`, and every item in
+ * that registry declares NO dependencies of its own. Adopting a project and
+ * leaving it unable to resolve `clsx` is precisely the half-configured state
+ * the preflight exists to prevent — and it was caught by building an adopted
+ * project rather than by reading this list.
+ */
+const REQUIRED_DEPENDENCIES: Record<string, string> = {
+  '@frontera-sdk/blueprint': '^1.43.10',
+  '@frontera-sdk/core': '^1.43.10',
+  '@tanstack/react-query': '^5.90.21',
+  'class-variance-authority': '^0.7.1',
+  clsx: '^2.1.1',
+  'lucide-react': '^1.31.0',
+  'radix-ui': '^1.6.7',
+  'tailwind-merge': '^3.3.1',
+}
+
+/** The Tailwind v4 animation utilities shadcn overlays style themselves with. */
+const REQUIRED_DEV_DEPENDENCIES: Record<string, string> = {
+  'tw-animate-css': '^1.4.0',
+}
+
+const REQUIRED_SCRIPTS: Record<string, string> = {
+  'blueprint:types': 'frontera blueprint generate-types',
+  'blueprint:types:check': 'frontera blueprint generate-types --check',
+  deploy: 'bun run build && frontera app deploy',
+}
+
+const NEXT_CONFIG_KEYS = [
+  ['output', "'export'"],
+  ['trailingSlash', 'true'],
+  ['images', '{ unoptimized: true }'],
+  ['transpilePackages', "['@frontera-sdk/core', '@frontera-sdk/blueprint']"],
+] as const
+
+export function planAdoption(target: AdoptionTarget): AdoptionPlan {
+  const pkg = readJson<PackageJson>(join(target.root, 'package.json')) ?? {}
+  const declared = { ...pkg.devDependencies, ...pkg.dependencies }
+  const files: Record<string, string> = {}
+  const manual: string[] = []
+
+  const put = (path: string, content: string) => {
+    if (!existsSync(join(target.root, path))) files[path] = content
+  }
+
+  put(
+    'frontera.config.json',
+    `${JSON.stringify(
+      {
+        displayName: target.packageName,
+        outputDirectory: 'out',
+        routing: 'filesystem',
+        connectDomains: [],
+        resourceDomains: [],
+      },
+      null,
+      2,
+    )}\n`,
+  )
+
+  // The provider tree is a NEW file, so writing it is safe; mounting it is an
+  // edit to their layout, which is not.
+  put(
+    `${target.appDir}/providers.tsx`,
+    `'use client'
+
+import type { ReactNode } from 'react'
+import { blueprintProvider } from '@frontera-sdk/blueprint/provider'
+import { FronteraAppProvider } from '@frontera-sdk/core/react'
+
+const devSessionEndpoint = process.env.NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT
+if (devSessionEndpoint) {
+  const runtime = globalThis as typeof globalThis & {
+    __FRONTERA_CONFIG__?: Record<string, unknown>
+  }
+  runtime.__FRONTERA_CONFIG__ = { ...runtime.__FRONTERA_CONFIG__, devSessionEndpoint }
+}
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <FronteraAppProvider providers={[blueprintProvider]}>{children}</FronteraAppProvider>
+}
+`,
+  )
+
+  // The patterns, unchanged from a scaffolded App — an adopted project gets the
+  // same skills, or the guidance is only true for projects that started here.
+  for (const [path, content] of Object.entries(nextSkillFiles())) put(path, content)
+
+  /**
+   * The entry point that makes those skills findable.
+   *
+   * An adopted project usually HAS an AGENTS.md already — `create-next-app`
+   * writes one — and overwriting it would delete instructions someone wrote
+   * about their own codebase. So: write it when it is absent, and when it is
+   * not, say the one line that needs adding rather than claiming the skills are
+   * wired up when nothing points at them.
+   */
+  const agentsPath = join(target.root, 'AGENTS.md')
+  if (!existsSync(agentsPath)) {
+    files['AGENTS.md'] = adoptedAgentsMd(target)
+  } else if (!readFileSync(agentsPath, 'utf8').includes('using-frontera-app-patterns')) {
+    manual.push(
+      'AGENTS.md: point agents at `.agents/skills/using-frontera-app-patterns/SKILL.md` before anything else',
+    )
+  }
+
+  put(
+    'components.json',
+    `${JSON.stringify(
+      {
+        $schema: 'https://ui.shadcn.com/schema.json',
+        style: 'new-york',
+        rsc: false,
+        tsx: true,
+        tailwind: { config: '', css: target.css, baseColor: 'neutral', cssVariables: true, prefix: '' },
+        aliases: {
+          components: `${target.alias}/components`,
+          ui: `${target.alias}/components/ui`,
+          utils: `${target.alias}/lib/utils`,
+          lib: `${target.alias}/lib`,
+          hooks: `${target.alias}/hooks`,
+        },
+        iconLibrary: 'lucide',
+      },
+      null,
+      2,
+    )}\n`,
+  )
+
+  put(
+    `${target.srcDir ? 'src/lib' : 'lib'}/utils.ts`,
+    `import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+`,
+  )
+
+  // Never rewritten, only extended — and only when the entry is missing.
+  const gitignore = existsSync(join(target.root, '.gitignore'))
+    ? readFileSync(join(target.root, '.gitignore'), 'utf8')
+    : ''
+  const missingIgnores = ['.frontera/', 'out/'].filter(
+    (entry) => !gitignore.split('\n').some((line) => line.trim() === entry.replace(/\/$/, '') || line.trim() === entry),
+  )
+  if (missingIgnores.length > 0) {
+    manual.push(`add to .gitignore: ${missingIgnores.join(', ')}`)
+  }
+
+  const nextConfigSource = target.nextConfig
+    ? readFileSync(join(target.root, target.nextConfig), 'utf8')
+    : null
+  if (!nextConfigSource) {
+    files['next.config.ts'] = `import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  output: 'export',
+  trailingSlash: true,
+  images: { unoptimized: true },
+  transpilePackages: ['@frontera-sdk/core', '@frontera-sdk/blueprint'],
+}
+
+export default nextConfig
+`
+  } else {
+    const missingKeys = NEXT_CONFIG_KEYS.filter(([key]) => !new RegExp(`\\b${key}\\s*:`).test(nextConfigSource))
+    if (missingKeys.length > 0) {
+      manual.push(
+        `${target.nextConfig}: add ${missingKeys.map(([key, value]) => `${key}: ${value}`).join(', ')}`,
+      )
+    }
+  }
+
+  const stylesheet = readFileSync(join(target.root, target.css), 'utf8')
+  if (!stylesheet.includes('tw-animate-css')) {
+    manual.push(`${target.css}: add \`@import "tw-animate-css";\` after the Tailwind import`)
+  }
+
+  const layoutPath = existsSync(join(target.root, target.appDir, 'layout.tsx'))
+    ? `${target.appDir}/layout.tsx`
+    : `${target.appDir}/layout.jsx`
+  const layout = readFileSync(join(target.root, layoutPath), 'utf8')
+  if (!layout.includes('Providers')) {
+    manual.push(
+      `${layoutPath}: import { Providers } from './providers' and wrap {children} in <Providers>`,
+    )
+  }
+
+  return {
+    files,
+    dependencies: Object.fromEntries(
+      Object.entries(REQUIRED_DEPENDENCIES).filter(([name]) => !declared[name]),
+    ),
+    devDependencies: Object.fromEntries(
+      Object.entries(REQUIRED_DEV_DEPENDENCIES).filter(([name]) => !declared[name]),
+    ),
+    scripts: Object.fromEntries(
+      Object.entries(REQUIRED_SCRIPTS).filter(([name]) => !pkg.scripts?.[name]),
+    ),
+    manual,
+  }
+}
+
+/**
+ * Merge the plan's dependencies and scripts into an existing manifest.
+ *
+ * Returns the new text rather than writing, so the caller decides — and so the
+ * merge itself is testable without a directory. Existing entries always win:
+ * a project that pins its own React Query version has a reason.
+ */
+export function mergeManifest(source: string, plan: AdoptionPlan): string {
+  const pkg = JSON.parse(source) as PackageJson & Record<string, unknown>
+  const indent = /\n(\s+)"/.exec(source)?.[1]?.length ?? 2
+
+  if (Object.keys(plan.dependencies).length > 0) {
+    pkg.dependencies = sortKeys({ ...pkg.dependencies, ...plan.dependencies })
+  }
+  if (Object.keys(plan.devDependencies).length > 0) {
+    pkg.devDependencies = sortKeys({ ...pkg.devDependencies, ...plan.devDependencies })
+  }
+  if (Object.keys(plan.scripts).length > 0) {
+    pkg.scripts = { ...pkg.scripts, ...plan.scripts }
+  }
+  return `${JSON.stringify(pkg, null, indent)}\n`
+}
+
+function sortKeys(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)))
+}
+
+/** The agent entry point for a project that already had a life before Frontera. */
+function adoptedAgentsMd(target: AdoptionTarget): string {
+  return `# ${target.packageName}
+
+This project is a Frontera App: a Next.js App Router project whose deployable
+result is static files, reading platform data through Blueprint.
+
+## Read this first
+
+Load \`.agents/skills/using-frontera-app-patterns/SKILL.md\`. It is the
+dispatcher — it routes you to the one skill that governs the files you are
+about to change.
+
+## Where things go
+
+| Path | What it is |
+|---|---|
+| \`${target.appDir}/\` | route adapters only — layout, providers, thin pages |
+| \`${target.srcDir ? 'src/ui' : 'ui'}/<feature>/\` | feature folders; one component per file |
+| \`${target.srcDir ? 'src/components' : 'components'}/ui/\` | shadcn primitives — \`bunx --bun shadcn@latest add <name>\` |
+| \`${target.srcDir ? 'src/lib' : 'lib'}/blueprint/<domain>/\` | the data layer: Blueprint reads live here |
+
+This project was adopted rather than scaffolded, so those directories may not
+exist yet. Create them as you go; the skills describe what belongs in each.
+
+## Non-negotiables
+
+1. Bun runs everything: \`bun install\`, \`bun run <script>\`, \`bun test\`.
+2. Components never fetch. Hooks fetch; components take props.
+3. Filter, sort, page and aggregate on the server.
+4. No secrets in browser code — not in source, not in \`NEXT_PUBLIC_*\`, not in \`.env\`.
+5. Every route must exist as a static file after \`bun run build\`.
+
+## Verify before claiming done
+
+\`\`\`bash
+bun run build
+\`\`\`
+
+For anything touching data, run it against real data with \`frontera app dev\`.
+`
+}

package/src/api/apps-api.ts

@@ -10,6 +10,24 @@ export interface AppVersionSummary {
   uploadedBy: string
   createdAt: string
   deployed: boolean
+  runtime: 'static'
+  routing: 'spa' | 'filesystem'
+  provenance: {
+    schemaVersion?: number
+    cliVersion?: string
+    framework?: string
+    frameworkVersion?: string
+    sourceCommit?: string
+    sourceDirty?: boolean
+    lockfilePath?: string
+    lockfileDigest?: string
+    packagedAt?: string
+  } | null
+}
+
+export interface AppTokenResponse {
+  token: string
+  expiresAt: number
 }
 
 /**
@@ -98,6 +116,10 @@ export class AppsApi {
     return this.client.request<AppVersionSummary[]>(`/v1/platform-apps/${appId}/versions`)
   }
 
+  appToken(appId: string): Promise<AppTokenResponse> {
+    return this.client.request<AppTokenResponse>(`/v1/platform-apps/${appId}/token`)
+  }
+
   publish(appId: string, args: {
     version: string
     parentVersion?: string | null
@@ -107,6 +129,10 @@ export class AppsApi {
     promote: boolean
     /** §4.4 — whether this tree had been rendered since its last source change. */
     renderEvidence?: unknown
+    /** Recorded build/package metadata; never trusted for authorization. */
+    provenance?: unknown
+    /** PNG from that render; the platform keeps it as the app's thumbnail. */
+    thumbnail?: Uint8Array | null
   }) {
     const form = new FormData()
     form.set('version', args.version)
@@ -116,6 +142,10 @@ export class AppsApi {
     if (args.manifest) form.set('manifest', JSON.stringify(args.manifest))
     form.set('promote', args.promote ? 'true' : 'false')
     if (args.renderEvidence) form.set('renderEvidence', JSON.stringify(args.renderEvidence))
+    if (args.provenance) form.set('provenance', JSON.stringify(args.provenance))
+    if (args.thumbnail && args.thumbnail.byteLength > 0) {
+      form.set('thumbnail', new Blob([args.thumbnail], { type: 'image/png' }), 'thumbnail.png')
+    }
     return this.multipart<{
       version: string
       promoted: boolean