@frontera-sdk/cli 1.43.10 → 1.44.1

package/src/commands/blueprint/get.ts

@@ -1,4 +1,5 @@
 import { PlatformApi } from '../../api/platform-api'
+import { parseBlueprintSchema, type BlueprintSchemaObject } from '../../blueprint-types'
 import { CliError, UsageError } from '../../errors'
 import type { Command } from '../types'
 
@@ -36,14 +37,15 @@ interface ObjectTypeRow {
  * error that names a different concept than the argument does, and does not
  * say the one thing that would fix it.
  *
- * The exact name is tried first, so the common path stays one request. Only a
- * miss pays for the list, and then it either resolves the case or names the
- * closest thing it found.
+ * Resolution happens only inside the granted schema. That both corrects case
+ * and prevents a detail lookup from becoming an existence oracle for an
+ * ungranted organization object type.
  */
-async function resolveApiName(api: PlatformApi, typed: string): Promise<string> {
-  const types = (await api.blueprintObjectTypes()) as ObjectTypeRow[]
+function resolveApiName(types: ObjectTypeRow[], typed: string): string {
   const names = types.map((t) => t.apiName).filter((n): n is string => Boolean(n))
 
+  const exact = names.find((n) => n === typed)
+  if (exact) return exact
   const insensitive = names.find((n) => n.toLowerCase() === typed.toLowerCase())
   if (insensitive) return insensitive
 
@@ -82,21 +84,10 @@ export const blueprintGet: Command = {
     }
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token)
-
-    // The response is `{ objectType, properties }`, NOT a flat object type.
-    // Reading apiName off the top level silently yielded undefined and fell
-    // back to whatever the caller typed — so the header echoed the input and
-    // looked correct only when the case already matched.
-    let payload: { objectType?: ObjectTypeRow & { description?: string | null }; properties?: Property[] }
-    try {
-      payload = (await api.blueprintObjectType(typed)) as typeof payload
-    } catch {
-      // Miss: resolve the case, or fail with the names that do exist.
-      payload = (await api.blueprintObjectType(await resolveApiName(api, typed))) as typeof payload
-    }
-
-    const type = payload.objectType ?? {}
-    const apiName = type.apiName ?? typed
+    const schema = parseBlueprintSchema(await api.blueprintSchema())
+    const apiName = resolveApiName(schema.objectTypes, typed)
+    const type = schema.objectTypes.find((objectType) => objectType.apiName === apiName) as BlueprintSchemaObject
+    const grantedNames = new Set(schema.objectTypes.map((objectType) => objectType.apiName))
 
     // Relations and metrics, not just columns. A property list alone says what
     // a table holds and nothing about how it joins or what is measured on it —
@@ -115,14 +106,21 @@ export const blueprintGet: Command = {
     for (const t of types as Array<{ id?: string; apiName?: string }>) {
       if (t.id && t.apiName) nameById.set(t.id, t.apiName)
     }
-    const selfId = (type as { id?: string }).id ?? ''
-
-    const related = (links as Link[]).filter(
-      (l) => l.fromObjectTypeId === selfId || l.toObjectTypeId === selfId,
-    )
-    const own = (metrics as Metric[]).filter((m) => m.objectTypeId === selfId)
-
-    const props = payload.properties ?? []
+    const selfId = (types as Array<{ id?: string; apiName?: string }>)
+      .find((candidate) => candidate.apiName === apiName)?.id ?? ''
+
+    const related = (links as Link[]).flatMap((link) => {
+      if (link.fromObjectTypeId !== selfId && link.toObjectTypeId !== selfId) return []
+      const outbound = link.fromObjectTypeId === selfId
+      const other = nameById.get((outbound ? link.toObjectTypeId : link.fromObjectTypeId) ?? '')
+      if (!other || !grantedNames.has(other)) return []
+      return [{ apiName: link.apiName, direction: outbound ? 'outbound' as const : 'inbound' as const, otherObjectType: other, cardinality: link.cardinality }]
+    })
+    const own = (metrics as Metric[])
+      .filter((metric) => metric.objectTypeId === selfId)
+      .map((metric) => ({ apiName: metric.apiName, displayName: metric.displayName }))
+
+    const props = type.properties as Property[]
     const heading = [apiName, type.displayName].filter(Boolean)
     const lines = [
       heading[1] && heading[1] !== heading[0] ? `${heading[0]} — ${heading[1]}` : String(heading[0]),
@@ -139,11 +137,8 @@ export const blueprintGet: Command = {
       `Relations (${related.length})`,
       ...(related.length === 0
         ? ['  (none)']
-        : related.map((l) => {
-            const outbound = l.fromObjectTypeId === selfId
-            const otherId = outbound ? l.toObjectTypeId : l.fromObjectTypeId
-            const other = nameById.get(otherId ?? '') ?? otherId ?? ''
-            return `  ${(l.apiName ?? '?').padEnd(26)}${outbound ? '→' : '←'} ${other.padEnd(18)}${l.cardinality ?? ''}`
+        : related.map((relation) => {
+            return `  ${(relation.apiName ?? '?').padEnd(26)}${relation.direction === 'outbound' ? '→' : '←'} ${relation.otherObjectType.padEnd(18)}${relation.cardinality ?? ''}`
           })),
       '',
       `Metrics (${own.length})`,
@@ -153,7 +148,7 @@ export const blueprintGet: Command = {
     ]
 
     return {
-      data: { ...payload, relations: related, metrics: own },
+      data: { objectType: type, properties: props, relations: related, metrics: own },
       text: lines.join('\n'),
     }
   },

package/src/commands/blueprint/list.ts

@@ -1,4 +1,5 @@
 import { PlatformApi } from '../../api/platform-api'
+import { parseBlueprintSchema } from '../../blueprint-types'
 import { table } from '../../table'
 import type { Command } from '../types'
 
@@ -28,7 +29,7 @@ export const blueprintList: Command = {
 
   async run(ctx) {
     const api = new PlatformApi(ctx.apiUrl, ctx.token)
-    const types = (await api.blueprintObjectTypes()) as ObjectTypeRow[]
+    const types = parseBlueprintSchema(await api.blueprintSchema()).objectTypes
 
     return {
       data: types,

package/src/commands/registry.ts

@@ -12,12 +12,17 @@ import { appSave } from './app/save'
 import { appDeploy } from './app/deploy'
 import { appPromote } from './app/promote'
 import { appVersions } from './app/versions'
+import { appSdk } from './app/sdk'
+import { appDev } from './app/dev'
 import { blueprintList } from './blueprint/list'
 import { blueprintGet } from './blueprint/get'
+import { blueprintGenerateTypes } from './blueprint/generate-types'
 import { blueprintAuthoringCommands } from './blueprint/authoring'
 import { blueprintDeclarativeCommands } from './blueprint/declarative'
 import { blueprintBind } from './blueprint/bind'
+import { blueprintEditable } from './blueprint/editable'
 import { blueprintGrant } from './blueprint/grants'
+import { actionCommands } from './action/index-commands'
 import { agentCommands } from './agent/index-commands'
 import { skillCommands } from './skill/index-commands'
 import { pluginCommands } from './plugin/index-commands'
@@ -58,6 +63,8 @@ export const COMMANDS: readonly Command[] = [
   appDeploy,
   appPromote,
   appVersions,
+  appSdk,
+  appDev,
 
   ...agentCommands,
   ...skillCommands,
@@ -70,12 +77,16 @@ export const COMMANDS: readonly Command[] = [
 
   blueprintList,
   blueprintGet,
+  blueprintGenerateTypes,
   // Authoring is no longer reserved: the organization API key (`sk-org-`) reaches the
   // organization-level shared draft, which is what these verbs were waiting on.
   ...blueprintAuthoringCommands,
   ...blueprintDeclarativeCommands,
   blueprintBind,
+  blueprintEditable,
   blueprintGrant,
+
+  ...actionCommands,
 ]
 
 export function findCommand(noun: string, verb: string | undefined): Command | null {
@@ -106,6 +117,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   secret: 'Workspace secrets — named here, never printed back',
   automation: 'Automations — TypeScript deployed here, run on a schedule',
   blueprint: 'The shared model of the organization — what an app can read',
+  action: 'Governed Actions — arm the write path a published Action runs',
 }
 
 export function nounSummary(noun: string): string {

package/src/context.ts

@@ -20,14 +20,14 @@ export interface Context {
 /**
  * Is this directory the root of a Frontera app project?
  *
- * The marker is `package.json` carrying a `frontera` field, which the scaffold
- * writes at init (`frontera: { displayName }`) and `writeAppId` fills in after
- * the first deploy. A bare `package.json` deliberately does NOT match: without
- * the field, every JavaScript repository on the machine would look like an app.
+ * New projects are marked by `frontera.config.json`. Legacy projects remain
+ * marked by `package.json#frontera`. A bare package.json does not match, so an
+ * unrelated JavaScript repository never becomes an App accidentally.
  */
 function isProjectRoot(dir: string): boolean {
   const pkgPath = join(dir, 'package.json')
   if (!existsSync(pkgPath)) return false
+  if (existsSync(join(dir, 'frontera.config.json'))) return true
   try {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { frontera?: unknown }
     return typeof pkg.frontera === 'object' && pkg.frontera !== null

package/src/dev-broker.ts

@@ -0,0 +1,71 @@
+import { randomBytes } from 'node:crypto'
+
+import type { BridgeInit } from '@frontera-sdk/core/bridge-protocol'
+
+export interface DevSessionPayload {
+  init: BridgeInit
+  expiresAt: number
+}
+
+export interface DevSessionBroker {
+  endpoint: string
+  server: ReturnType<typeof Bun.serve>
+}
+
+/**
+ * Keep the durable CLI credential on the developer's machine while giving the
+ * browser only a short-lived App token. The random path is defence in depth;
+ * loopback binding and an exact Origin check are the actual trust boundary.
+ */
+export function createDevSessionBroker(options: {
+  appOrigin: string
+  loadSession(): Promise<DevSessionPayload>
+}): DevSessionBroker {
+  const allowedOrigin = new URL(options.appOrigin).origin
+  const path = `/.frontera/dev-session/${randomBytes(32).toString('base64url')}`
+
+  const fetch = async (request: Request): Promise<Response> => {
+      const url = new URL(request.url)
+      if (url.pathname !== path) return new Response('Not found', { status: 404 })
+
+      const origin = request.headers.get('origin')
+      if (origin !== allowedOrigin) return new Response('Forbidden', { status: 403 })
+
+      const corsHeaders = {
+        'access-control-allow-origin': allowedOrigin,
+        'access-control-allow-credentials': 'true',
+        'access-control-allow-methods': 'GET, OPTIONS',
+        'access-control-allow-headers': 'Accept',
+        'cache-control': 'no-store',
+        vary: 'Origin',
+      }
+      if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: corsHeaders })
+      if (request.method !== 'GET') return new Response('Method not allowed', { status: 405, headers: corsHeaders })
+
+      try {
+        return Response.json({ data: await options.loadSession() }, { headers: corsHeaders })
+      } catch (error) {
+        return Response.json(
+          { error: error instanceof Error ? error.message : 'Could not create a local App session' },
+          { status: 502, headers: corsHeaders },
+        )
+      }
+  }
+
+  // Bun 1.3 rejects port 0 instead of asking the kernel for an ephemeral
+  // port. Retry within the IANA dynamic range; binding itself is atomic, so a
+  // race can only make one attempt fail and move to the next candidate.
+  let server: ReturnType<typeof Bun.serve> | undefined
+  let lastError: unknown
+  for (let attempt = 0; attempt < 32 && !server; attempt += 1) {
+    try {
+      const port = 49_152 + Math.floor(Math.random() * (65_535 - 49_152 + 1))
+      server = Bun.serve({ hostname: '127.0.0.1', port, fetch })
+    } catch (error) {
+      lastError = error
+    }
+  }
+  if (!server) throw lastError instanceof Error ? lastError : new Error('Could not bind the local session broker')
+
+  return { endpoint: `http://127.0.0.1:${server.port}${path}`, server }
+}

package/src/flag-help.ts

@@ -19,10 +19,22 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   plan: 'write a mapping skeleton to this path instead of binding',
   'accept-contract-change': 'confirm a rebind whose column contract differs from the pinned one',
   revoke: 'remove the grant instead of adding it',
+  // Editable properties. Comma-separated API names; `--set ''` clears the set,
+  // which is why an empty value is a valid one rather than a missing argument.
+  set: 'comma-separated property API names, replacing the whole set',
+  // Action deployment.
+  'dry-run': 'derive and print the write path without building anything',
+  'plan-id': 'reuse this mutation plan id instead of minting one, so a retry names the same artifact',
+  'binding-id': 'reuse this Binding id instead of minting one, so a retry names the same artifact',
+  reason: 'reason recorded on the deployment transition',
+  'no-activate': 'review the write path but leave it switched off',
+  role: 'organization role the capability is held by',
+  add: 'comma-separated property API names to add to the current set',
+  remove: 'comma-separated property API names to drop from the current set',
   // Blueprint authoring (organization API key). `notes` is described further down
   // — this map is keyed by flag name across every command, so one entry serves both.
   label: 'release label recorded on the published or rolled-back release',
-  report: 'validation report id to publish against; defaults to a fresh validation',
+  report: 'validation report id to act on — the release publishes against it, the review is pinned to it',
   instruction: 'migration instruction applied to every change a rollback discards',
   // Global
   json: 'machine-readable output on stdout; stderr still carries commentary',
@@ -30,6 +42,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   yes: 'assume yes for confirmations',
   help: 'show this help',
   'api-url': 'API origin to use, overriding FRONTERA_API_URL and the stored default',
+  output: 'project-relative .ts path for generated output',
+  check: 'verify generated output is current without writing it',
 
   // Project resolution
   dir: 'project directory to act on (default: walk up from the working directory)',
@@ -42,6 +56,12 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   notes: 'note recorded against the published version',
 
   // Apps
+  framework: 'App scaffold to create: next (default) or react (legacy Vite)',
+  port: 'loopback port for the local App development server',
+  'no-open': 'start local development without opening a browser window',
+  'no-install': 'scaffold without running `bun install` — for an offline machine or a sandbox',
+  'no-git': 'scaffold without creating a repository and an initial commit',
+  'no-components': 'scaffold without fetching the baseline shadcn components',
   version: 'version to publish, overriding the one in package.json',
   'no-promote': 'publish the version without moving the live pointer',
   'no-wait': 'return as soon as the run is queued instead of waiting for it to finish',
@@ -83,11 +103,14 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
  */
 const PLACEHOLDER: Readonly<Record<string, string>> = {
   'api-url': 'origin',
+  output: 'path',
   dataset: 'name',
   plan: 'path',
   dir: 'path',
   file: 'path',
   version: 'semver',
+  framework: 'next|react',
+  port: 'number',
   'expect-revision': 'hash',
   notes: 'text',
   description: 'text',

package/src/heal.ts

@@ -135,7 +135,7 @@ export function healProject(dir: string): HealResult {
         // Already pointing at the copy in this tree — that is the shape this
         // function produces, so re-pulling must not rewrite it back over
         // itself and report a repair that did nothing.
-        if (spec === `file:./${APP_SDK_PACKAGES[pkg].dir}` && vendorPresent(dir, pkg)) continue
+        if (spec === `file:./${APP_SDK_PACKAGES[pkg].dir}` && vendorCurrent(dir, pkg)) continue
         vendorSdkPackage(dir, pkg)
         deps[dep] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
         const under = dep === pkg ? '' : ` (legacy name, now ${pkg})`
@@ -184,7 +184,10 @@ export function healProject(dir: string): HealResult {
   // Reacts.
   const imported = importedSdkPackages(join(dir, 'src'))
   for (const { specifier, pkg } of imported) {
-    if (declares(manifest, specifier) || (specifier === pkg && vendorPresent(dir, pkg))) continue
+    // `declares` alone is not enough: a tree can declare the dependency and
+    // still carry a stale copy, which is the ordinary state of every app
+    // scaffolded before the SDK grew a module.
+    if (vendorCurrent(dir, pkg) && (declares(manifest, specifier) || specifier === pkg)) continue
     vendorSdkPackage(dir, pkg)
     manifest.dependencies ??= {}
     manifest.dependencies[specifier] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
@@ -252,6 +255,38 @@ function vendorPresent(dir: string, pkg: AppSdkPackage): boolean {
   return existsSync(join(dir, APP_SDK_PACKAGES[pkg].dir))
 }
 
+/**
+ * Does it carry the CURRENT one — every file this CLI would write, as written?
+ *
+ * "The directory exists" was the wrong question. An app vendored before a
+ * module was added has the directory and not the module, so a heal that
+ * skipped on presence left it frozen at whatever the CLI shipped the day it
+ * was scaffolded — and `app pull`, which exists to hydrate a tree, silently
+ * refused to hydrate the one part it owns.
+ *
+ * CONTENT, not presence, for the same reason one step on: a file that exists
+ * but predates a fix is the ordinary state of every app already deployed, and
+ * a fix nothing can deliver is not shipped. The vendored tree is a copy of
+ * upstream rather than app code — `heal` owns it and rewrites it — so
+ * overwriting a divergent copy is the repair, not a loss.
+ *
+ * Re-vendoring is safe and idempotent: `vendorSdkPackage` writes into the SAME
+ * directory, so this refreshes a copy rather than creating a second one.
+ */
+function vendorCurrent(dir: string, pkg: AppSdkPackage): boolean {
+  if (!vendorPresent(dir, pkg)) return false
+  const target = join(dir, APP_SDK_PACKAGES[pkg].dir)
+  return Object.entries(sdkPackageFiles(pkg)).every(([rel, content]) => {
+    const path = join(target, rel)
+    if (!existsSync(path)) return false
+    try {
+      return readFileSync(path, 'utf8') === content
+    } catch {
+      return false
+    }
+  })
+}
+
 /** Does it carry any of them? */
 function vendored(dir: string): boolean {
   return SDK_PACKAGE_NAMES.some((pkg) => vendorPresent(dir, pkg))

package/src/manifest.ts

@@ -15,11 +15,14 @@ import type { ProjectConfig } from './project'
  * `connectDomains` reaches the CSP for every app rather than only scaffolded
  * ones — which is the gap this closes.
  *
- * A build that DOES emit `dist/frontera.manifest.json` still wins, so a future
+ * A build that DOES emit `<outputDirectory>/frontera.manifest.json` still wins, so a future
  * plugin can add pages and an app-state schema without changing this.
  */
 export interface AppManifest {
-  schemaVersion: 1
+  schemaVersion: 2
+  runtime: 'static'
+  routing: 'spa' | 'filesystem'
+  entrypoint: 'index.html'
   displayName: string
   connectDomains: string[]
   resourceDomains: string[]
@@ -50,7 +53,10 @@ function assertDomains(field: string, values: string[]): string[] {
 
 export function buildManifest(project: ProjectConfig): AppManifest {
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
+    runtime: 'static',
+    routing: project.routing ?? 'spa',
+    entrypoint: 'index.html',
     displayName: project.displayName,
     connectDomains: assertDomains('connectDomains', project.connectDomains),
     resourceDomains: assertDomains('resourceDomains', project.resourceDomains),
@@ -60,8 +66,9 @@ export function buildManifest(project: ProjectConfig): AppManifest {
 /**
  * The manifest to publish with this build.
  *
- * Read from `dist/` when the build produced one; otherwise synthesised from
- * `package.json`. A malformed `dist/frontera.manifest.json` is an error rather
+ * Read from the configured output directory when the build produced one;
+ * otherwise synthesised from `frontera.config.json` (or the legacy
+ * package.json field). A malformed emitted manifest is an error rather
  * than a silent fallback: the build meant to say something, and quietly
  * publishing different rules than the author declared is worse than refusing.
  */
@@ -69,12 +76,86 @@ export function resolveManifest(distDir: string, project: ProjectConfig): AppMan
   const emitted = join(distDir, 'frontera.manifest.json')
   if (!existsSync(emitted)) return buildManifest(project)
 
+  let parsed: unknown
   try {
-    return JSON.parse(readFileSync(emitted, 'utf8')) as AppManifest
+    parsed = JSON.parse(readFileSync(emitted, 'utf8'))
   } catch (err) {
-    throw new CliError(`dist/frontera.manifest.json is not valid JSON: ${(err as Error).message}`, {
+    throw new CliError(`${emitted} is not valid JSON: ${(err as Error).message}`, {
       code: 'VALIDATION_ERROR',
-      hint: 'delete it to fall back to the `frontera` key in package.json',
+      hint: 'fix the emitted JSON, or delete it to use frontera.config.json',
     })
   }
+  return normalizeManifest(parsed)
+}
+
+const MANIFEST_HINT = 'fix frontera.manifest.json, then run `frontera app deploy` again'
+
+function stringArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new CliError(`${field} must be an array of strings`, {
+      code: 'VALIDATION_ERROR',
+      hint: MANIFEST_HINT,
+    })
+  }
+  return assertDomains(field, value as string[])
+}
+
+/** Validate emitted manifests before they cross the wire. */
+export function normalizeManifest(value: unknown): AppManifest {
+  if (!value || typeof value !== 'object') {
+    throw new CliError('frontera manifest must be an object', {
+      code: 'VALIDATION_ERROR', hint: MANIFEST_HINT,
+    })
+  }
+  const raw = value as Record<string, unknown>
+  if (raw.schemaVersion !== 1 && raw.schemaVersion !== 2) {
+    throw new CliError('unsupported frontera manifest schemaVersion', {
+      code: 'VALIDATION_ERROR', hint: 'emit schemaVersion 2, then run `frontera app deploy` again',
+    })
+  }
+  if (typeof raw.displayName !== 'string' || raw.displayName.length === 0) {
+    throw new CliError('manifest displayName must be a non-empty string', {
+      code: 'VALIDATION_ERROR', hint: MANIFEST_HINT,
+    })
+  }
+  const connectDomains = stringArray(raw.connectDomains, 'connectDomains')
+  const resourceDomains = stringArray(raw.resourceDomains, 'resourceDomains')
+
+  if (raw.schemaVersion === 1) {
+    return {
+      schemaVersion: 2,
+      runtime: 'static',
+      routing: 'spa',
+      entrypoint: 'index.html',
+      displayName: raw.displayName,
+      connectDomains,
+      resourceDomains,
+    }
+  }
+  if (raw.runtime !== 'static') {
+    throw new CliError('manifest runtime must be "static"', {
+      code: 'VALIDATION_ERROR', hint: 'build a static artifact; server runtimes are not supported',
+    })
+  }
+  if (raw.routing !== 'spa' && raw.routing !== 'filesystem') {
+    throw new CliError('manifest routing must be "spa" or "filesystem"', {
+      code: 'VALIDATION_ERROR',
+      hint: MANIFEST_HINT,
+    })
+  }
+  if (raw.entrypoint !== 'index.html') {
+    throw new CliError('manifest entrypoint must be "index.html"', {
+      code: 'VALIDATION_ERROR',
+      hint: MANIFEST_HINT,
+    })
+  }
+  return {
+    schemaVersion: 2,
+    runtime: 'static',
+    routing: raw.routing,
+    entrypoint: 'index.html',
+    displayName: raw.displayName,
+    connectDomains,
+    resourceDomains,
+  }
 }

package/src/packaging.ts

@@ -17,6 +17,7 @@ import { join, relative, sep } from 'node:path'
 export const HARD_EXCLUDED = Object.freeze([
   'node_modules',
   'dist',
+  'out',
   'build',
   '.next',
   '.git',
@@ -39,6 +40,11 @@ export function isExcluded(rel: string): boolean {
     if (seg === '.DS_Store') return true
     if (seg.endsWith('.log')) return true
   }
+  // The render screenshot. It is written INSIDE the project so a deploy from a
+  // bare directory can find it, but it is a build-time by-product of this
+  // machine, not source: packaging it would push a few hundred KB of PNG into
+  // every `app pull` for a picture the platform already stores per version.
+  if (rel === '.frontera/last-render.png') return true
   return false
 }