@frontera-sdk/cli 1.50.82 → 1.50.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.82",
+  "version": "1.50.84",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.50.82",
-    "@frontera-sdk/core": "1.50.82",
+    "@frontera-sdk/functions": "1.50.84",
+    "@frontera-sdk/core": "1.50.84",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.82",
+    "@frontera-sdk/forge-contracts": "1.50.84",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/platform-api.ts

@@ -3,6 +3,7 @@ import { FronteraClient } from '@frontera-sdk/core/client'
 import { organizationHeaders, selectedOrganization } from '../organization'
 
 import { CliError } from '../errors'
+import { BLUEPRINT_SCHEMA_CAPABILITIES } from '../blueprint-types'
 
 /**
  * The service's code for an HTTP status, for responses that carry no `code` of
@@ -108,7 +109,7 @@ export class PlatformApi {
   }
 
   blueprintSchema() {
-    return this.get<unknown>('/v1/blueprint/schema')
+    return this.get<unknown>(`/v1/blueprint/schema?capabilities=${BLUEPRINT_SCHEMA_CAPABILITIES.join(',')}`)
   }
 
   blueprintObjectType(apiName: string) {
@@ -145,6 +146,8 @@ export class PlatformApi {
     orderBy?: Array<{ property: string; dir: 'asc' | 'desc' }>
     pageSize?: number
     pageToken?: string
+    /** Distance ordering from a location; checked by the service. */
+    nearest?: unknown
   }) {
     return this.client.request<{
       rows?: Array<Record<string, unknown>>

package/src/blueprint/projection.ts

@@ -79,8 +79,11 @@ function propertyToFile(
   objectApiName: string,
   sharedApiNameById: Map<string, string>,
   semanticApiNameById: Map<string, string>,
+  siblingApiNameById: Map<string, string>,
 ): Record<string, unknown> {
   const body = rest(property, new Set(['id', 'sharedPropertyId', 'semanticTypeId']))
+  const location = locationToFile(property, objectApiName, siblingApiNameById)
+  if (location) body.calculation = location
   const semanticType = resolveName(
     property.semanticTypeId,
     semanticApiNameById,
@@ -127,6 +130,29 @@ function resolveName(
   return apiName
 }
 
+/**
+ * A location calculation (ADR 0013) names its latitude and longitude fields, as
+ * `primaryKey` and `title` do, rather than carrying their ids. Its only reader is
+ * the differ, which compares it against the live draft projected the same way, so
+ * no inverse is needed. Other calculations pass through unchanged.
+ */
+function locationToFile(
+  property: Record<string, unknown>,
+  objectApiName: string,
+  siblingApiNameById: Map<string, string>,
+): Record<string, unknown> | undefined {
+  const calculation = property.calculation as
+    | { kind?: unknown; latitudePropertyId?: unknown; longitudePropertyId?: unknown }
+    | undefined
+  if (calculation?.kind !== 'location') return undefined
+  const subject = `Location "${String(property.apiName)}" on ${objectApiName}`
+  return {
+    kind: 'location',
+    latitude: resolveName(calculation.latitudePropertyId, siblingApiNameById, 'latitude field', subject),
+    longitude: resolveName(calculation.longitudePropertyId, siblingApiNameById, 'longitude field', subject),
+  }
+}
+
 /**
  * `governance.sourceMappings[0]` → the portable `backing:` a file writes.
  *
@@ -194,7 +220,7 @@ function objectToFile(
     primaryKey: byId.get(object.primaryKeyPropertyId) ?? object.primaryKeyPropertyId,
     title: byId.get(object.titlePropertyId) ?? object.titlePropertyId,
     properties: object.properties.map((property) =>
-      propertyToFile(property, object.apiName, sharedApiNameById, semanticApiNameById)),
+      propertyToFile(property, object.apiName, sharedApiNameById, semanticApiNameById, byId)),
   }
 }
 

package/src/blueprint-types.ts

@@ -9,8 +9,19 @@ export const DEFAULT_BLUEPRINT_TYPES_OUTPUT = 'src/generated/frontera-blueprint.
 /** Mirrors the service's `DataType`. `media_reference` is first-class (spec
  *  §4/§12): it generates a named struct rather than `unknown`, and the schema
  *  publishes it as neither filterable nor sortable, so the generated
- *  `BlueprintRegistry` cannot offer a predicate the query layer refuses. */
-export type BlueprintDataType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'json' | 'media_reference'
+ *  `BlueprintRegistry` cannot offer a predicate the query layer refuses.
+ *  `geopoint` is a location (ADR 0013) and generates `BlueprintGeoPoint`. */
+export const BLUEPRINT_DATA_TYPES = [
+  'string', 'number', 'boolean', 'date', 'timestamp', 'json', 'media_reference', 'geopoint',
+] as const
+export type BlueprintDataType = (typeof BLUEPRINT_DATA_TYPES)[number]
+
+/**
+ * Value kinds this CLI declares to `GET /v1/blueprint/schema`. The service
+ * leaves out fields of any kind a client does not declare, so an older CLI
+ * keeps working when a newer kind is published.
+ */
+export const BLUEPRINT_SCHEMA_CAPABILITIES = ['geopoint'] as const
 export type BlueprintPropertyType = 'attribute' | 'measure' | 'time'
 
 export interface BlueprintSchemaProperty {
@@ -37,7 +48,18 @@ export interface BlueprintSchemaResponse {
   objectTypes: BlueprintSchemaObject[]
 }
 
-const DATA_TYPES = new Set<BlueprintDataType>(['string', 'number', 'boolean', 'date', 'timestamp', 'json', 'media_reference'])
+/** The schema as this CLI can use it: the fields it left out, as `Type.field`. */
+export interface ParsedBlueprintSchema extends BlueprintSchemaResponse {
+  skipped: string[]
+}
+
+/** The stderr warning for fields a schema had that this CLI cannot type. */
+export function skippedFieldsWarning(skipped: readonly string[]): string | null {
+  if (skipped.length === 0) return null
+  return `warning: skipped ${skipped.join(', ')}: their value type is newer than this CLI; upgrade the Frontera CLI to generate types for them`
+}
+
+const DATA_TYPES: ReadonlySet<string> = new Set(BLUEPRINT_DATA_TYPES)
 const PROPERTY_TYPES = new Set<BlueprintPropertyType>(['attribute', 'measure', 'time'])
 
 function schemaContractError(detail: string): never {
@@ -47,7 +69,16 @@ function schemaContractError(detail: string): never {
   })
 }
 
-export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
+/**
+ * Validate the schema response.
+ *
+ * A property whose `dataType` this CLI does not know is left out and named in
+ * `skipped`, rather than failing the whole schema: one field of a newer kind
+ * anywhere in the organization would otherwise stop type generation for every
+ * App. It is still validated in every other respect, and anything malformed
+ * still fails. The input is not modified.
+ */
+export function parseBlueprintSchema(input: unknown): ParsedBlueprintSchema {
   if (!input || typeof input !== 'object') return schemaContractError('expected an object')
   const schema = input as Record<string, unknown>
   if (schema.schemaVersion !== 1) {
@@ -58,7 +89,9 @@ export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
   }
   if (!Array.isArray(schema.objectTypes)) return schemaContractError('objectTypes must be an array')
 
+  const skipped: string[] = []
   const objectNames = new Set<string>()
+  const objectTypes: BlueprintSchemaObject[] = []
   for (const [objectIndex, candidate] of schema.objectTypes.entries()) {
     if (!candidate || typeof candidate !== 'object') return schemaContractError(`objectTypes[${objectIndex}] must be an object`)
     const objectType = candidate as Record<string, unknown>
@@ -75,6 +108,7 @@ export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
     if (objectNames.has(objectType.apiName)) return schemaContractError(`duplicate object apiName ${objectType.apiName}`)
     objectNames.add(objectType.apiName)
     const propertyNames = new Set<string>()
+    const properties: BlueprintSchemaProperty[] = []
     for (const [propertyIndex, propertyCandidate] of objectType.properties.entries()) {
       if (!propertyCandidate || typeof propertyCandidate !== 'object') {
         return schemaContractError(`objectTypes[${objectIndex}].properties[${propertyIndex}] must be an object`)
@@ -87,7 +121,7 @@ export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
         typeof property.displayName !== 'string'
         || !(property.description === null || typeof property.description === 'string')
         || !PROPERTY_TYPES.has(property.propertyType as BlueprintPropertyType)
-        || !DATA_TYPES.has(property.dataType as BlueprintDataType)
+        || typeof property.dataType !== 'string'
         || typeof property.nullable !== 'boolean'
         || typeof property.filterable !== 'boolean'
         || typeof property.sortable !== 'boolean'
@@ -98,9 +132,15 @@ export function parseBlueprintSchema(input: unknown): BlueprintSchemaResponse {
         return schemaContractError(`duplicate property apiName ${property.apiName} on ${objectType.apiName}`)
       }
       propertyNames.add(property.apiName)
+      if (!DATA_TYPES.has(property.dataType)) {
+        skipped.push(`${objectType.apiName}.${property.apiName}`)
+        continue
+      }
+      properties.push(property as unknown as BlueprintSchemaProperty)
     }
+    objectTypes.push({ ...(objectType as unknown as BlueprintSchemaObject), properties })
   }
-  return input as BlueprintSchemaResponse
+  return { schemaVersion: 1, digest: schema.digest as `sha256:${string}`, objectTypes, skipped }
 }
 
 /**
@@ -126,6 +166,19 @@ const MEDIA_REFERENCE_TYPE_DECLARATION = [
   '}',
 ]
 
+/** A WGS 84 location, always named — never a positional pair (ADR 0013). */
+const GEO_POINT_TYPE_NAME = 'BlueprintGeoPoint'
+
+const GEO_POINT_TYPE_DECLARATION = [
+  '/** A WGS 84 location in decimal degrees: latitude -90..90, longitude -180..180.',
+  ' *  Null when the object has no valid location. It cannot be sorted or',
+  ' *  compared — ask `!== null` to test presence. */',
+  `export interface ${GEO_POINT_TYPE_NAME} {`,
+  '  lat: number',
+  '  lon: number',
+  '}',
+]
+
 const TYPE_BY_DATA_TYPE: Readonly<Record<BlueprintDataType, string>> = {
   string: 'string',
   number: 'number',
@@ -134,6 +187,7 @@ const TYPE_BY_DATA_TYPE: Readonly<Record<BlueprintDataType, string>> = {
   timestamp: 'string',
   json: 'unknown',
   media_reference: MEDIA_REFERENCE_TYPE_NAME,
+  geopoint: GEO_POINT_TYPE_NAME,
 }
 
 function jsDoc(value: string | null): string[] {
@@ -232,7 +286,7 @@ export function writeBlueprintTypesFile(
   return { path, changed: true }
 }
 
-export function generateBlueprintTypes(schema: BlueprintSchemaResponse): string {
+export function generateBlueprintTypes(schema: BlueprintSchemaResponse & { skipped?: readonly string[] }): string {
   if (schema.schemaVersion !== 1) {
     throw new Error(`unsupported Blueprint schema version: ${String(schema.schemaVersion)}`)
   }
@@ -244,9 +298,13 @@ export function generateBlueprintTypes(schema: BlueprintSchemaResponse): string
       properties: [...objectType.properties].sort(compareApiName),
     }))
 
+  const skipped = schema.skipped ?? []
   const lines = [
     BLUEPRINT_TYPES_MARKER,
     `// Blueprint schema digest: ${schema.digest}`,
+    // The digest covers the whole schema, so a field left out is named here:
+    // the file must not claim to type what it does not.
+    ...(skipped.length > 0 ? [`// Not generated (value type newer than this CLI): ${skipped.join(', ')}`] : []),
     '',
     "import type { BlueprintObjectSchema as __FronteraBlueprintObjectSchema } from '@frontera-sdk/blueprint/types'",
     '',
@@ -260,6 +318,11 @@ export function generateBlueprintTypes(schema: BlueprintSchemaResponse): string
   ))) {
     lines.push(...MEDIA_REFERENCE_TYPE_DECLARATION, '')
   }
+  if (objects.some((objectType) => objectType.properties.some(
+    (property) => property.dataType === 'geopoint',
+  ))) {
+    lines.push(...GEO_POINT_TYPE_DECLARATION, '')
+  }
 
   for (const objectType of objects) {
     lines.push(...jsDoc(objectType.description), `export interface ${objectType.apiName} {`)

package/src/commands/blueprint/declarative.ts

@@ -600,6 +600,7 @@ export function assertApplicable(
   // omits, and refuse the run naming a field the plan never called changed.
   const unmappable = Object.keys(file.document).filter((field) =>
     !applicable.has(field) && !satisfies(file.document[field], live[field], field))
+  if (kind === 'object-type') unmappable.push(...unmappablePropertyFields(file.document, live))
   if (unmappable.length === 0) return
   throw new CliError(
     `${file.path}: ${unmappable.join(', ')} ${unmappable.length === 1 ? 'differs' : 'differ'} from the draft, `
@@ -615,6 +616,26 @@ export function assertApplicable(
   )
 }
 
+/**
+ * Property fields the field commands do not carry. A property's `calculation`
+ * (a location included) and its own `sensitivity` have no route from a file:
+ * applying one would report a classification or a formula that never changed.
+ * Named as `properties.<apiName>.<field>`.
+ */
+const UNAPPLICABLE_PROPERTY_FIELDS = ['calculation', 'sensitivity'] as const
+
+function unmappablePropertyFields(document: Record<string, unknown>, live: Record<string, unknown>): string[] {
+  const declared = Array.isArray(document.properties) ? document.properties as Array<Record<string, unknown>> : []
+  const liveProperties = Array.isArray(live.properties) ? live.properties as Array<Record<string, unknown>> : []
+  const liveByName = new Map(liveProperties.map((property) => [String(property.apiName), property]))
+  return declared.flatMap((property) => {
+    const counterpart = liveByName.get(String(property.apiName)) ?? {}
+    return UNAPPLICABLE_PROPERTY_FIELDS
+      .filter((field) => property[field] !== undefined && !satisfies(property[field], counterpart[field], field))
+      .map((field) => `properties.${String(property.apiName)}.${field}`)
+  })
+}
+
 /**
  * `primaryKey` and `title` — the two references a file states by property apiName.
  *

package/src/commands/blueprint/generate-types.ts

@@ -4,6 +4,7 @@ import { PlatformApi } from '../../api/platform-api'
 import {
   generateBlueprintTypes,
   parseBlueprintSchema,
+  skippedFieldsWarning,
   writeBlueprintTypesFile,
 } from '../../blueprint-types'
 import type { Command } from '../types'
@@ -31,6 +32,8 @@ export const blueprintGenerateTypes: Command = {
     const project = ctx.project!
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const schema = parseBlueprintSchema(await api.blueprintSchema())
+    const skippedWarning = skippedFieldsWarning(schema.skipped)
+    if (skippedWarning) ctx.output.note(skippedWarning)
     const contents = generateBlueprintTypes(schema)
     const written = writeBlueprintTypesFile(
       project.root,
@@ -50,6 +53,9 @@ export const blueprintGenerateTypes: Command = {
         propertyCount,
         changed: written.changed,
         checked,
+        // Fields left out because their value type is newer than this CLI,
+        // also named in the generated file's header.
+        skipped: schema.skipped,
       },
       text: checked
         ? `Blueprint types are current at ${path} (${schema.objectTypes.length} objects, ${propertyCount} properties).`

package/src/commands/blueprint/get.ts

@@ -1,5 +1,5 @@
 import { PlatformApi } from '../../api/platform-api'
-import { parseBlueprintSchema, type BlueprintSchemaObject } from '../../blueprint-types'
+import { parseBlueprintSchema, skippedFieldsWarning, type BlueprintSchemaObject } from '../../blueprint-types'
 import { CliError, UsageError } from '../../errors'
 import type { Command } from '../types'
 
@@ -139,6 +139,8 @@ export const blueprintGet: Command = {
 
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const schema = parseBlueprintSchema(await api.blueprintSchema())
+    const skippedWarning = skippedFieldsWarning(schema.skipped)
+    if (skippedWarning) ctx.output.note(skippedWarning)
     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))
@@ -261,6 +263,8 @@ export const blueprintGet: Command = {
         ...(relations.ok ? {} : { relationsUnavailable: relations.unavailable }),
         metrics: own.ok ? own.rows : null,
         ...(own.ok ? {} : { metricsUnavailable: own.unavailable }),
+        // Fields of this type the CLI left out (a newer value type), as `Type.field`.
+        skipped: schema.skipped.filter((name) => name.startsWith(`${apiName}.`)),
       },
       text: lines.join('\n'),
     }

package/src/commands/blueprint/list.ts

@@ -1,5 +1,5 @@
 import { PlatformApi } from '../../api/platform-api'
-import { parseBlueprintSchema } from '../../blueprint-types'
+import { parseBlueprintSchema, skippedFieldsWarning } from '../../blueprint-types'
 import { table } from '../../table'
 import type { Command } from '../types'
 
@@ -32,7 +32,12 @@ export const blueprintList: Command = {
 
   async run(ctx) {
     const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const types = parseBlueprintSchema(await api.blueprintSchema()).objectTypes
+    const schema = parseBlueprintSchema(await api.blueprintSchema())
+    // `data` stays the type list its JSON consumers read; a field left out
+    // is only a warning here, since a type list shows no fields.
+    const skippedWarning = skippedFieldsWarning(schema.skipped)
+    if (skippedWarning) ctx.output.note(skippedWarning)
+    const types = schema.objectTypes
 
     return {
       data: types,

package/src/templates/next-skills.ts

@@ -323,6 +323,10 @@ const session: Skill = {
     '  for presentation (chrome density, external links), never for data access.',
     '- Treat `init.token` as opaque and short-lived. Do not cache it, put it in state, log it, send it',
     '  anywhere, or retry an authorization failure with a different credential.',
+    '- Who opened the App is `useViewer()` — `{ userId, name, email }` or `null`. Use it for "you",',
+    '  "assigned to me" and owner defaults; never ask a person to type who they are. It is for',
+    '  display only: never use it to decide what the person may do. It is `null` under a workspace',
+    '  key, for an App hosted outside Frontera, and on an older host — only then ask.',
     '- Local development is `frontera app dev`. It mints a short-lived App token, keeps the stored CLI',
     '  key in the broker, and owns `NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT` — never hand-write that',
     '  variable. `bun run dev` alone starts Next with no session: fine for layout, useless for data.',
@@ -330,13 +334,14 @@ const session: Skill = {
     '```tsx',
     "'use client'",
     '',
-    "import { useFronteraApp } from '@frontera-sdk/core/react'",
+    "import { useFronteraApp, useViewer } from '@frontera-sdk/core/react'",
     '',
     'export function AppShell({ children }: { children: React.ReactNode }) {',
     '  const { mode, init } = useFronteraApp()',
+    '  const viewer = useViewer() // { userId, name, email } | null',
     '  // mode: "embedded" | "standalone" | "local"',
-    '  // init: { appId, version, orgId, workspaceId, theme, state, path? }',
-    '  return <section data-mode={mode}>{children}</section>',
+    '  // init: { appId, version, orgId, workspaceId, theme, state, path?, viewer? }',
+    '  return <section data-mode={mode} aria-label={viewer?.name ?? undefined}>{children}</section>',
     '}',
     '```',
     '',
@@ -353,6 +358,7 @@ const session: Skill = {
     '- Writing `NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT` by hand into `.env`.',
     '- Branching data access on `mode`.',
     '- Rendering the app before the session resolves, or adding a "not ready" guard inside a feature.',
+    '- An "enter your email" field when `useViewer()` already says who the person is.',
     '',
     '## Verification',
     '',