@frontera-sdk/cli 0.1.0

package/src/template.ts

@@ -0,0 +1,566 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+import vendored from './vendor/sdk-sources.json'
+
+/**
+ * Project scaffold.
+ *
+ * Everything the author should NOT have to write lives here: the Vite config,
+ * the entry point, the design tokens, and the SDK itself. What is left in
+ * `src/App.tsx` is application code, which is the whole point of the rewrite.
+ *
+ * The SDK arrives as VENDORED SOURCE under `src/frontera/`, not as a
+ * dependency — see `scripts/sync-sdk.ts` for why. The import specifiers still
+ * read `@frontera-sdk/core/…`; `tsconfig` paths and a matching Vite alias
+ * resolve them. So `package.json` needs nothing but public npm, and a project
+ * pulled onto a machine that has never seen this monorepo still builds.
+ */
+export function scaffold(target: string, name: string): void {
+  for (const [rel, content] of Object.entries(files(name))) {
+    const full = join(target, rel)
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+  }
+}
+
+/**
+ * The scaffold's file map, exported so tests can assert its contents without
+ * writing to disk — in particular that every `frontera …` command named in a
+ * shipped SKILL.md actually exists, and that every `@frontera-sdk/…` import
+ * resolves to a file the scaffold actually writes.
+ */
+export function scaffoldFiles(name: string): Record<string, string> {
+  return files(name)
+}
+
+/**
+ * The SDK packages an APP carries as vendored source — the ones `tsconfig`
+ * paths and the Vite alias below actually resolve.
+ *
+ * The CLI vendors more than an app needs: `frontera/automation` is carried for
+ * automations, and its `manifest.ts` imports `cron-parser`, which is not a
+ * dependency of a React app. Writing it here would leave every scaffolded app
+ * with an unresolvable import and a failing `bun run typecheck`, for a module
+ * nothing in the app imports. So the scaffold takes what it can resolve, and
+ * this table moves when an alias does.
+ *
+ * `heal.ts` reads the same table to repair a PULLED app, so the two paths
+ * cannot drift into vendoring different sets of files under different names.
+ */
+export const APP_SDK_PACKAGES = {
+  '@frontera-sdk/core': { prefix: 'frontera/core/', dir: 'src/frontera/core' },
+  '@frontera-sdk/blueprint': { prefix: 'frontera/blueprint/', dir: 'src/frontera/blueprint' },
+} as const
+
+export type AppSdkPackage = keyof typeof APP_SDK_PACKAGES
+
+/**
+ * The names these packages had before the `@frontera-sdk` scope, mapped to what
+ * they are now.
+ *
+ * This table is the difference between `heal` working and `heal` being
+ * decorative. Every app already in storage was packaged under the old scope —
+ * that is what "legacy tree" MEANS here — so a healer that matches only
+ * `@frontera-sdk/*` repairs nothing that actually exists. The rename moved the
+ * code and the test fixture in one commit, so the suite followed the bug
+ * instead of catching it.
+ *
+ * Deleting an entry is not a cleanup. It is dropping support for trees that are
+ * still in storage, and they do not migrate themselves.
+ */
+export const LEGACY_SDK_ALIASES: Record<string, AppSdkPackage> = {
+  '@frontera/sdk-core': '@frontera-sdk/core',
+  '@frontera/blueprint': '@frontera-sdk/blueprint',
+}
+
+/** The current name for a dependency, whichever scope it was written in. */
+export function currentSdkPackage(dep: string): AppSdkPackage | null {
+  if (dep in LEGACY_SDK_ALIASES) return LEGACY_SDK_ALIASES[dep]!
+  if (dep in APP_SDK_PACKAGES) return dep as AppSdkPackage
+  return null
+}
+
+const APP_SDK_DIRS = Object.values(APP_SDK_PACKAGES).map((p) => p.prefix)
+
+/**
+ * The vendored source of ONE SDK package, keyed by its path relative to that
+ * package's own directory (`client.ts`, not `frontera/core/client.ts`).
+ */
+export function sdkPackageFiles(pkg: AppSdkPackage): Record<string, string> {
+  const { prefix } = APP_SDK_PACKAGES[pkg]
+  const out: Record<string, string> = {}
+  for (const [path, content] of Object.entries(vendored.files)) {
+    if (path.startsWith(prefix)) out[path.slice(prefix.length)] = content
+  }
+  return out
+}
+
+/** SDK source and design tokens, written under `src/`. */
+function vendoredFiles(): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [path, content] of Object.entries(vendored.files)) {
+    const isSdk = path.startsWith('frontera/')
+    if (isSdk && !APP_SDK_DIRS.some((dir) => path.startsWith(dir))) continue
+    out[`src/${path}`] = content
+  }
+  return out
+}
+
+function files(name: string): Record<string, string> {
+  return {
+    ...vendoredFiles(),
+
+    'package.json': `${JSON.stringify(
+      {
+        name,
+        private: true,
+        version: '0.1.0',
+        type: 'module',
+        frontera: {
+          // No slug: the platform owns it and can rename it, so a committed
+          // copy would go stale. `name` above seeds it on the first deploy, and
+          // `frontera.appId` is written back once the app exists.
+          displayName: name,
+          // Origins this app may reach at runtime, enforced as a CSP by the
+          // host. `frontera app deploy` turns these into the version's
+          // manifest, so an addition takes effect on the next deploy — add one
+          // deliberately rather than discovering the block in production.
+          connectDomains: [],
+          resourceDomains: [],
+        },
+        scripts: {
+          dev: 'vite',
+          build: 'vite build',
+          typecheck: 'tsc --noEmit',
+          deploy: 'bun run build && frontera app deploy',
+        },
+        dependencies: {
+          '@tanstack/react-query': '^5.90.21',
+          react: '^19.0.0',
+          'react-dom': '^19.0.0',
+        },
+        devDependencies: {
+          '@tailwindcss/vite': '^4.1.0',
+          // For `node:url` in vite.config.ts and the `process` guard in the
+          // SDK's config resolution — both compile without it, and neither
+          // type-checks.
+          '@types/node': '^22',
+          '@types/react': '^19',
+          '@types/react-dom': '^19',
+          '@vitejs/plugin-react': '^5.0.0',
+          tailwindcss: '^4.1.0',
+          typescript: '^5.9.3',
+          vite: '^7.0.0',
+        },
+      },
+      null,
+      2,
+    )}\n`,
+
+    'vite.config.ts': `import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+const src = (path: string) => fileURLToPath(new URL(\`./src/\${path}\`, import.meta.url))
+
+// The SDK is vendored into src/frontera/ so this project installs and builds
+// with nothing but public npm. These aliases are what keep the import
+// specifiers stable — app code, copied components and the docs all say
+// \`@frontera-sdk/core/…\`, and only this file knows where that resolves.
+// Keep them in step with the \`paths\` in tsconfig.json.
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: [
+      { find: /^@frontera-sdk\\/core\\/(.*)$/, replacement: src('frontera/core/$1') },
+      { find: /^@frontera-sdk\\/blueprint\\/(.*)$/, replacement: src('frontera/blueprint/$1') },
+      { find: /^@\\/(.*)$/, replacement: src('$1') },
+    ],
+  },
+})
+`,
+
+    'tsconfig.json': `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          lib: ['ESNext', 'DOM'],
+          jsx: 'react-jsx',
+          strict: true,
+          skipLibCheck: true,
+          noEmit: true,
+          baseUrl: '.',
+          paths: {
+            '@/*': ['./src/*'],
+            // Mirrors resolve.alias in vite.config.ts — the editor and the
+            // bundler have to agree or one of them lies to you.
+            '@frontera-sdk/core/*': ['./src/frontera/core/*'],
+            '@frontera-sdk/blueprint/*': ['./src/frontera/blueprint/*'],
+          },
+        },
+        include: ['src', 'vite.config.ts'],
+      },
+      null,
+      2,
+    )}\n`,
+
+    'dev-host.html': devHostHtml(name),
+
+    'index.html': `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+
+    'src/main.tsx': `import './theme.css'
+
+import { createFronteraApp } from '@frontera-sdk/core/create-frontera-app'
+import { blueprintProvider } from '@frontera-sdk/blueprint/provider'
+
+import App from './App'
+
+// Completes the bridge handshake, adopts the host's palette, installs the
+// error boundary that reports crashes back to the platform, and only THEN
+// mounts — an app has no data scope until the host says who it is.
+createFronteraApp(<App />, { providers: [blueprintProvider] })
+`,
+
+    'src/App.tsx': `import { useObjects } from '@frontera-sdk/blueprint/hooks'
+import { useFronteraApp } from '@frontera-sdk/core/create-frontera-app'
+
+/**
+ * The object type this page reads.
+ *
+ * \`frontera blueprint list\` shows what this workspace exposes; put an API name
+ * here — \`Shipment\`, \`LoanApplication\`, whatever the deployment models — and
+ * \`frontera blueprint get <apiName>\` lists its properties.
+ *
+ * Annotated \`: string\` on purpose. Without it TypeScript infers the literal
+ * type \`''\`, and the empty-check below becomes a "no overlap" error the moment
+ * you fill this in — a type error caused by doing exactly what the comment says.
+ */
+const OBJECT_TYPE: string = ''
+
+export default function App() {
+  const { init } = useFronteraApp()
+  const { data, isLoading, error } = useObjects(OBJECT_TYPE, {
+    pageSize: 20,
+    enabled: OBJECT_TYPE.length > 0,
+  })
+
+  return (
+    <main className="mx-auto flex max-w-5xl flex-col gap-6 p-8">
+      <header>
+        <h1 className="text-xl font-semibold text-foreground">${name}</h1>
+        <p className="text-sm text-muted-foreground">version {init.version}</p>
+      </header>
+
+      {OBJECT_TYPE === '' ? (
+        <div className="rounded-lg border border-border bg-card p-6 text-sm text-muted-foreground">
+          Set <code className="font-mono text-foreground">OBJECT_TYPE</code> in{' '}
+          <code className="font-mono text-foreground">src/App.tsx</code> to read live data. Run{' '}
+          <code className="font-mono text-foreground">frontera blueprint list</code> to see what
+          this workspace exposes.
+        </div>
+      ) : (
+        <section className="flex flex-col gap-2">
+          {isLoading && <p className="text-sm text-muted-foreground">Loading…</p>}
+          {error && (
+            <p role="alert" className="text-sm text-destructive">
+              {error.message}
+            </p>
+          )}
+          {data && (
+            <p className="text-sm text-muted-foreground">
+              {data.rows.length} of {OBJECT_TYPE}
+            </p>
+          )}
+        </section>
+      )}
+    </main>
+  )
+}
+`,
+
+    '.gitignore': `node_modules/
+dist/
+.frontera/
+*.log
+`,
+
+    '.agents/skills/using-frontera-sdk/SKILL.md': `---
+name: using-frontera-sdk
+description: Use at the start of ANY task in a Frontera app project — a Vite project whose package.json carries a "frontera" key and that deploys via the frontera CLI. Establishes the project shape and routes to the right pattern.
+---
+
+# Frontera App Development
+
+An app is ordinary React that runs in a sandboxed iframe inside Frontera and
+reaches platform data through the SDK. You write application code; the scaffold
+owns the runtime.
+
+## The layout
+
+| Path | What it is |
+|---|---|
+| \`src/App.tsx\` | yours — the page |
+| \`src/components/ui/\` | yours — copied source from \`frontera app add\` |
+| \`src/frontera/\` | **the SDK, vendored.** Read it freely; do not edit it |
+| \`src/theme.css\` | design tokens + Tailwind entry, imported by \`main.tsx\` |
+| \`src/main.tsx\`, \`vite.config.ts\` | the runtime wiring |
+
+\`src/frontera/\` is a copy of \`@frontera-sdk/core\` and \`@frontera-sdk/blueprint\`,
+written here at \`frontera app init\`. That is why this project installs with
+nothing but public npm. Imports still read \`@frontera-sdk/core/…\` — the
+tsconfig \`paths\` and the Vite alias resolve them — so **never rewrite an import
+to a relative path into \`src/frontera/\`**, and never add \`@frontera-sdk/*\` to
+\`package.json\`.
+
+## Non-negotiables
+
+1. **Never edit \`vite.config.ts\`, \`src/main.tsx\`, or \`src/frontera/\`.** They
+   wire the bridge and the module resolution. If you think you need to, you are
+   solving the wrong problem.
+2. **Components are yours.** \`src/components/ui/\` is copied source, not a
+   dependency — edit it in place. \`frontera app add <name>\` fetches more.
+3. **Data arrives as props.** Components never fetch; hooks do, at the page level.
+4. **Filter on the server.** Pass \`where\` to \`useObjects\`; filtering the
+   returned array narrows one page and misreports every total.
+5. **Never commit \`.env\`.** The CLI refuses to package it, and that refusal is
+   not overridable.
+
+## Where to look
+
+| Task | Source of truth |
+|---|---|
+| What data is available | \`frontera blueprint list\`, then \`frontera blueprint get <apiName>\` |
+| What a component accepts | the file in \`src/components/ui/\` — read it, it is yours |
+| What a hook returns | \`src/frontera/blueprint/hooks.ts\` |
+| Deploy and versions | \`frontera app versions\`, \`frontera app deploy --help\` |
+
+Read the source rather than trusting a summary: this file deliberately does not
+restate prop tables or function signatures, because those change per release
+and a stale skill is worse than no skill.
+
+## Verify before claiming done
+
+\`\`\`bash
+bun run typecheck
+\`\`\`
+
+\`\`\`bash
+bun run build
+\`\`\`
+
+\`\`\`bash
+frontera app deploy --no-promote
+\`\`\`
+
+\`vite build\` does not type-check, so a build that succeeds proves nothing about
+types — run both. \`bun run build\` is the deploy gate: \`frontera app deploy\`
+refuses without \`dist/index.html\`. \`--no-promote\` publishes a version without
+moving the live pointer, so you can preview it before customers see it.
+
+## Running it locally
+
+\`bun run dev\` serves the app. Opening \`/\` directly renders "This app runs
+inside Frontera" instead of mounting — the handshake refusing to hand a
+credential to an unknown parent, not a bug.
+
+Open **\`/dev-host.html\`** to actually see it. That page frames the app and plays
+the host side of the bridge (init, theme, navigate), so it mounts and reads real
+data. Set \`VITE_FRONTERA_TOKEN\` and \`VITE_FRONTERA_API_URL\` in \`.env.local\` for
+platform reads to succeed; without a token the app mounts and its queries 401.
+
+The dev host lives at the project root, so it is served in dev and never built
+into \`dist/\`. Do not move it into \`public/\` — a page that fakes a platform
+handshake must not ship with the app.
+`,
+
+    '.agents/skills/frontera-app-data/SKILL.md': `---
+name: frontera-app-data
+description: Use when reading platform data in a Frontera app — useObjects, useAggregate, useObjectInstance, where clauses, paging, and why filtering must happen on the server.
+---
+
+# Reading Blueprint data
+
+\`\`\`tsx
+import { useObjects, useAggregate } from '@frontera-sdk/blueprint/hooks'
+import { objectsOf, type WhereNode } from '@frontera-sdk/blueprint/types'
+\`\`\`
+
+Every read is scoped by the credential the host handed over at handshake, so an
+object type the workspace was not granted is simply absent — the query fails
+with \`UNKNOWN_OBJECT_TYPE\` rather than an authorization error. Discover what
+exists with \`frontera blueprint list\`, never by guessing an api name.
+
+## Filter on the server
+
+\`where\` compiles into the object set, so the server filters and pages:
+
+\`\`\`tsx
+const where: WhereNode | undefined = status
+  ? { property: 'deliveryStatus', op: 'eq', value: status }
+  : undefined
+
+const rows = useObjects<Shipment>('Shipment', { where, page: 1, pageSize: 20 })
+\`\`\`
+
+Filtering \`rows.data.rows\` in the component instead is the classic mistake: it
+narrows only the page you happened to fetch, so a filter matching 8,961 records
+renders 5 of them and the footer claims "Page 1 of 1".
+
+For the same reason, a total is its own query — \`useAggregate\` with a count
+over the SAME object set — not \`rows.length\`.
+
+## Paging
+
+\`page\` is 1-based. Server-driven tables need \`pageCount\` and \`rowCount\` from
+the aggregate, or the table re-paginates one page of server data.
+
+## Identity
+
+\`useObjectInstance(objectType, pk)\` returns one record and is disabled while
+\`pk\` is null, so a detail panel can mount before a row is selected.
+`,
+  }
+}
+
+/**
+ * The dev host. `bun run dev` alone renders "This app runs inside Frontera"
+ * and nothing else: `connectToHost` rejects when `window.parent === window`,
+ * so an app served straight from Vite never mounts. That is correct behaviour
+ * — an app has no data scope until a host tells it who it is — but it leaves
+ * the author (and any agent verifying its work) looking at a refusal panel
+ * instead of the app.
+ *
+ * This page is the missing other half: it frames the app and plays the host
+ * side of the bridge. The SDK was built to accept exactly this —
+ * `connectToHost` takes an explicit `parentOrigin` and reads
+ * `__FRONTERA_CONFIG__` for the rest.
+ *
+ * It lives at the project ROOT, not in `public/`: Vite's build input is
+ * `index.html` alone, so a root-level HTML file is served in dev and never
+ * reaches `dist/`. That matters — a page that fakes a platform handshake must
+ * not ship inside the deployed bundle.
+ *
+ * Exported because `heal.ts` writes it into a PULLED app too. A project
+ * packaged before the dev host existed has none, and an agent that opens `/`
+ * because `/dev-host.html` 404s is looking at a refusal panel — which is how
+ * a session ends up hand-writing this file and then deleting it in cleanup.
+ */
+export function devHostHtml(name: string): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name} — dev host</title>
+    <style>
+      :root { color-scheme: dark; }
+      body { margin: 0; height: 100vh; display: flex; flex-direction: column;
+             font: 13px/1.4 system-ui, sans-serif; background: #0b0b0c; color: #e7e7ea; }
+      header { display: flex; align-items: center; gap: 12px; padding: 8px 12px;
+               background: #f5a623; color: #1a1a1a; font-weight: 600; }
+      header code { font-weight: 400; opacity: .8; }
+      iframe { flex: 1; width: 100%; border: 0; background: #fff; }
+      button { font: inherit; border: 0; border-radius: 4px; padding: 3px 8px; cursor: pointer; }
+    </style>
+  </head>
+  <body>
+    <!-- Deliberately loud. A screenshot of this page must never be mistaken
+         for the deployed app. -->
+    <header>
+      DEV HOST — simulated platform frame, not production
+      <code id="path"></code>
+      <button id="scheme" type="button">Toggle light/dark</button>
+    </header>
+    <iframe id="app" src="/" title="${name}"></iframe>
+    <script type="module">
+      const frame = document.getElementById('app')
+      const origin = window.location.origin
+
+      // Read from the environment so the dev host talks to whatever API the
+      // author is pointed at. Vite exposes VITE_* to the client; these are the
+      // same values \\\`frontera login\\\` stores.
+      const token = import.meta.env.VITE_FRONTERA_TOKEN ?? ''
+      const apiBaseUrl = import.meta.env.VITE_FRONTERA_API_URL ?? 'http://localhost:4000'
+      const orgId = import.meta.env.VITE_FRONTERA_ORG_ID ?? null
+      const workspaceId = import.meta.env.VITE_FRONTERA_WORKSPACE_ID ?? null
+
+      let colorScheme = 'dark'
+      const tokens = {
+        '--background': colorScheme === 'dark' ? '#0b0b0c' : '#ffffff',
+        '--foreground': colorScheme === 'dark' ? '#e7e7ea' : '#111111',
+      }
+
+      const send = (message) => frame.contentWindow?.postMessage(message, origin)
+
+      window.addEventListener('message', (event) => {
+        // Same origin check the real host makes. The dev host is a
+        // convenience, not an excuse to model the protocol loosely.
+        if (event.origin !== origin) return
+        const message = event.data
+        if (!message || typeof message !== 'object') return
+
+        switch (message.type) {
+          case 'frontera:ready':
+            if (!token) {
+              console.warn(
+                '[dev-host] No VITE_FRONTERA_TOKEN — the app will mount but platform reads will 401.',
+              )
+            }
+            send({
+              type: 'frontera:init',
+              token,
+              apiBaseUrl,
+              appId: '${name}',
+              version: 'dev',
+              orgId,
+              workspaceId,
+              theme: { tokens, colorScheme },
+              state: {},
+              path: window.location.hash.slice(1) || undefined,
+            })
+            break
+          case 'frontera:navigate':
+            // The platform would change its URL here; showing it is enough to
+            // verify the app asked for the right one.
+            document.getElementById('path').textContent = message.path
+            window.location.hash = message.path
+            break
+          case 'frontera:error':
+            console.error('[dev-host] app error:', message.message, message.stack ?? '')
+            break
+          default:
+            break
+        }
+      })
+
+      document.getElementById('scheme').addEventListener('click', () => {
+        colorScheme = colorScheme === 'dark' ? 'light' : 'dark'
+        tokens['--background'] = colorScheme === 'dark' ? '#0b0b0c' : '#ffffff'
+        tokens['--foreground'] = colorScheme === 'dark' ? '#e7e7ea' : '#111111'
+        document.documentElement.style.colorScheme = colorScheme
+        // Exercises the path that was received-and-dropped before the SDK
+        // grew a theme handler: an app must follow the host's palette for the
+        // whole session, not only at mount.
+        send({ type: 'frontera:theme', tokens, colorScheme })
+      })
+    </script>
+  </body>
+</html>
+`
+}