@frontera-sdk/cli 1.53.10 → 1.53.12

package/src/local/local-sync-link.ts

@@ -9,9 +9,11 @@ import { credentialStore } from '../credential-store'
 import { forgetDeviceSession, readDeviceSession, type DeviceSession } from '../device-login'
 import { writeFileAtomic } from '../fs-atomic'
 import { configDir } from '../paths'
+import { CliError } from '../errors'
 import { deleteProfile, fingerprint, getProfile, putProfile } from '../profiles'
 import { syncClient, type SyncClient } from './local-sync-client'
 import { PROJECT_FILES, type LocalProject } from './local-project'
+import { normalizeOrigin } from './local-sync-client'
 
 /**
  * A project's link to one platform workspace, and the keys that read it.
@@ -40,15 +42,30 @@ export interface SyncLink {
   models?: Record<string, string>
 }
 
+/**
+ * A workspace the project delivers to by name besides its link
+ * (`sync.targets.<name>` in frontera.yaml), on its own platform: staging and
+ * production, say. It has its own keys, target profile and change requests.
+ */
+export interface NamedTarget extends SyncLink {
+  /** Reached only by its name (`--target`); the project's link is never pointed at its workspace. */
+  production?: boolean
+}
+
+export const TARGET_NAME = /^[a-z][a-z0-9-]{0,31}$/
+
 export function projectFile(root: string): string {
   return join(root, PROJECT_FILES.find((f) => existsSync(join(root, f))) ?? PROJECT_FILES[0])
 }
 
-export function readLink(root: string): SyncLink | null {
+function readSync(root: string): Record<string, unknown> | null {
   const file = projectFile(root)
   if (!existsSync(file)) return null
-  const doc = parseDocument(readFileSync(file, 'utf8')).toJS() as { sync?: Partial<SyncLink> } | null
-  const s = doc?.sync
+  const doc = parseDocument(readFileSync(file, 'utf8')).toJS() as { sync?: unknown } | null
+  return doc?.sync && typeof doc.sync === 'object' && !Array.isArray(doc.sync) ? (doc.sync as Record<string, unknown>) : null
+}
+
+function linkOf(s: Partial<Record<keyof SyncLink, unknown>> | null | undefined): SyncLink | null {
   if (!s || typeof s.platform !== 'string' || typeof s.workspace !== 'string') return null
   const models = s.models && typeof s.models === 'object' && !Array.isArray(s.models)
     ? Object.fromEntries(Object.entries(s.models as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === 'string' && !!e[0] && !!e[1]))
@@ -64,6 +81,58 @@ export function readLink(root: string): SyncLink | null {
   }
 }
 
+export function readLink(root: string): SyncLink | null {
+  return linkOf(readSync(root))
+}
+
+/**
+ * The project's named targets (`sync.targets`), and each entry left out with
+ * why: a name the CLI refuses, no platform or workspace, or a platform a key
+ * is not sent to. A target's platform is read as `connect` writes it (an
+ * https origin), so every call and every step reads one address for it.
+ */
+function targetEntries(root: string): { targets: Record<string, NamedTarget>; leftOut: Array<{ name: string; problem: string }> } {
+  // No prototype: `constructor` is a target only when the file has one.
+  const targets: Record<string, NamedTarget> = Object.create(null)
+  const leftOut: Array<{ name: string; problem: string }> = []
+  for (const [name, value] of Object.entries(rawTargets(root)).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+    const entry = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null
+    const link = linkOf(entry)
+    if (!TARGET_NAME.test(name)) leftOut.push({ name, problem: 'a target’s name is lowercase letters, digits and dashes, starting with a letter: rename it in frontera.yaml' })
+    else if (!link) leftOut.push({ name, problem: `it needs a platform and a workspace: \`frontera local sync connect --target ${name} --platform <url>\` writes both` })
+    else {
+      try {
+        targets[name] = { ...link, platform: normalizeOrigin(link.platform), ...(entry?.production === true ? { production: true } : {}) }
+      } catch (err) {
+        const why = err as CliError
+        leftOut.push({ name, problem: `\`${link.platform}\` is not a platform a key is sent to: ${why.message}${why.hint ? ` (${why.hint})` : ''}` })
+      }
+    }
+  }
+  return { targets, leftOut }
+}
+
+/** The project's named targets (`sync.targets`), by name; an entry the CLI can't use is left out (`leftOutTargets`). */
+export function readTargets(root: string): Record<string, NamedTarget> {
+  return targetEntries(root).targets
+}
+
+/** The `sync.targets` entries left out, each with what to fix. */
+export function leftOutTargets(root: string): Array<{ name: string; problem: string }> {
+  return targetEntries(root).leftOut
+}
+
+/** The link's fields as frontera.yaml writes them, in order. */
+function linkFields(link: SyncLink): Record<string, unknown> {
+  const value: Record<string, unknown> = { platform: link.platform, workspace: link.workspace }
+  if (link.workspaceName) value.workspaceName = link.workspaceName
+  if (link.organization) value.organization = link.organization
+  if (link.organizationName) value.organizationName = link.organizationName
+  value.blueprint = link.blueprint
+  if (link.models && Object.keys(link.models).length) value.models = link.models
+  return value
+}
+
 const mapped = new Map<string, { mtimeMs: number; models: Record<string, string> }>()
 
 /** The project's model mapping (`sync.models`), empty when it has none or no link; read once per change of the file. */
@@ -95,20 +164,21 @@ export function setModelMapping(root: string, local: string, workspace: string |
   return next
 }
 
-/** Write the link into `frontera.yaml`, keeping the rest of the file and its comments. */
-export function writeLink(root: string, link: SyncLink | null): void {
+/**
+ * Write the `sync` block into `frontera.yaml`, keeping the rest of the file and
+ * its comments. `targets` is written as given: an entry this CLI can't read
+ * (a name it refuses, a missing workspace) is kept as it was written.
+ */
+function writeSync(root: string, link: SyncLink | null, targets: Record<string, unknown>): void {
   const file = projectFile(root)
   const doc = parseDocument(existsSync(file) ? readFileSync(file, 'utf8') : '')
   if (!doc.contents) doc.contents = doc.createNode({}) as never
-  if (!link) {
+  const named = Object.keys(targets).sort()
+  if (!link && !named.length) {
     doc.delete('sync')
   } else {
-    const value: Record<string, unknown> = { platform: link.platform, workspace: link.workspace }
-    if (link.workspaceName) value.workspaceName = link.workspaceName
-    if (link.organization) value.organization = link.organization
-    if (link.organizationName) value.organizationName = link.organizationName
-    value.blueprint = link.blueprint
-    if (link.models && Object.keys(link.models).length) value.models = link.models
+    const value: Record<string, unknown> = link ? linkFields(link) : {}
+    if (named.length) value.targets = Object.fromEntries(named.map((name) => [name, targets[name]]))
     const existing = doc.get('sync', true) as { commentBefore?: string } | undefined
     const node = doc.createNode(value) as unknown as { commentBefore?: string }
     node.commentBefore = existing?.commentBefore ?? ' The platform workspace this project pulls from (`frontera local sync`). Keys are in your keychain, not here.'
@@ -117,10 +187,35 @@ export function writeLink(root: string, link: SyncLink | null): void {
   writeFileSync(file, doc.toString())
 }
 
+/** The `sync.targets` block as written. */
+function rawTargets(root: string): Record<string, unknown> {
+  const raw = readSync(root)?.targets
+  return raw && typeof raw === 'object' && !Array.isArray(raw) ? { ...(raw as Record<string, unknown>) } : {}
+}
+
+/** Write the link into `frontera.yaml`, keeping the named targets, the rest of the file and its comments. */
+export function writeLink(root: string, link: SyncLink | null): void {
+  writeSync(root, link, rawTargets(root))
+}
+
+const TARGET_FIELDS = new Set(['platform', 'workspace', 'workspaceName', 'organization', 'organizationName', 'blueprint', 'models', 'production'])
+
+/** Write one named target into `frontera.yaml` (`sync.targets.<name>`), keeping the keys it doesn't know, or remove it. */
+export function writeTarget(root: string, name: string, target: NamedTarget | null): void {
+  const targets = rawTargets(root)
+  const was = targets[name]
+  const kept = was && typeof was === 'object' && !Array.isArray(was) ? Object.entries(was).filter(([key]) => !TARGET_FIELDS.has(key)) : []
+  if (target) targets[name] = { ...linkFields(target), ...(target.production ? { production: true } : {}), ...Object.fromEntries(kept) }
+  else delete targets[name]
+  writeSync(root, readLink(root), targets)
+}
+
 // ── Keys ─────────────────────────────────────────────────────────────────────
 
 const SERVICE = 'frontera-sync-key'
 export type KeyRole = 'workspace' | 'organization'
+/** Whose keys and target profile: a project's (its link), or one of its named targets (`<project id>@<name>`). */
+export type KeyOwner = Pick<LocalProject, 'id'>
 
 function useKeychain(): boolean {
   return process.platform === 'darwin' && !process.env.FRONTERA_SYNC_KEYS_FILE
@@ -138,35 +233,84 @@ function readKeysFile(): Record<string, string> {
   }
 }
 
-const account = (project: LocalProject, role: KeyRole) => `${project.id}:${role}`
+/** `checked-at`: where a named target's keys were checked, kept beside them. */
+const account = (owner: KeyOwner, role: KeyRole | 'checked-at') => `${owner.id}:${role}`
 
-export function setSyncKey(project: LocalProject, role: KeyRole, key: string): void {
+function storeSet(name: string, value: string): void {
   if (useKeychain()) {
-    const res = spawnSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account(project, role), '-w', key], { stdio: 'ignore' })
+    const res = spawnSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', name, '-w', value], { stdio: 'ignore' })
     if (res.status !== 0) throw new Error('the macOS keychain refused the key')
     return
   }
-  writeFileAtomic(keysFile(), `${JSON.stringify({ ...readKeysFile(), [account(project, role)]: key }, null, 2)}\n`, 0o600)
+  writeFileAtomic(keysFile(), `${JSON.stringify({ ...readKeysFile(), [name]: value }, null, 2)}\n`, 0o600)
 }
 
-export function getSyncKey(project: LocalProject, role: KeyRole): string | null {
+function storeGet(name: string): string | null {
   if (useKeychain()) {
-    const res = spawnSync('security', ['find-generic-password', '-s', SERVICE, '-a', account(project, role), '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    const res = spawnSync('security', ['find-generic-password', '-s', SERVICE, '-a', name, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
     return res.status === 0 ? res.stdout.trim() || null : null
   }
-  return readKeysFile()[account(project, role)] ?? null
+  return readKeysFile()[name] ?? null
 }
 
-export function removeSyncKey(project: LocalProject, role: KeyRole): void {
+function storeRemove(name: string): void {
   if (useKeychain()) {
-    spawnSync('security', ['delete-generic-password', '-s', SERVICE, '-a', account(project, role)], { stdio: 'ignore' })
+    spawnSync('security', ['delete-generic-password', '-s', SERVICE, '-a', name], { stdio: 'ignore' })
     return
   }
   const keys = readKeysFile()
-  delete keys[account(project, role)]
+  delete keys[name]
   writeFileAtomic(keysFile(), `${JSON.stringify(keys, null, 2)}\n`, 0o600)
 }
 
+export function setSyncKey(owner: KeyOwner, role: KeyRole, key: string): void {
+  storeSet(account(owner, role), key)
+}
+
+export function getSyncKey(owner: KeyOwner, role: KeyRole): string | null {
+  return storeGet(account(owner, role))
+}
+
+export function removeSyncKey(owner: KeyOwner, role: KeyRole): void {
+  storeRemove(account(owner, role))
+}
+
+/** A platform and a workspace: what a checked-at record holds, and what a target profile's name is made of. */
+type CheckedAt = Pick<SyncLink, 'platform' | 'workspace'>
+
+/** Record where a named target's keys were checked (`connect --target`), or (null) forget it. */
+export function setKeysCheckedAt(owner: KeyOwner, at: CheckedAt | null): void {
+  if (at) storeSet(account(owner, 'checked-at'), JSON.stringify({ platform: normalizeOrigin(at.platform), workspace: at.workspace }))
+  else storeRemove(account(owner, 'checked-at'))
+}
+
+export function keysCheckedAt(owner: KeyOwner): CheckedAt | null {
+  try {
+    const at = JSON.parse(storeGet(account(owner, 'checked-at')) ?? 'null') as Partial<CheckedAt> | null
+    return typeof at?.platform === 'string' && typeof at.workspace === 'string' ? { platform: at.platform, workspace: at.workspace } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A named target's keys go only to the platform and workspace `connect`
+ * checked them on. `frontera.yaml` is a file in the repository, so a commit
+ * that points the target elsewhere (a teammate's, a merge, a copied entry)
+ * is refused before any call, not followed with the stored keys.
+ */
+export function refuseMovedTarget(target: Pick<SyncTarget, 'name' | 'owner' | 'link'>): void {
+  if (!target.name || !getSyncKey(target.owner, 'workspace')) return
+  const at = keysCheckedAt(target.owner)
+  const { platform, workspace } = target.link
+  if (at && at.platform === platform && at.workspace === workspace) return
+  const where = (a: CheckedAt) => `${a.workspace} on ${new URL(a.platform).host}`
+  throw new CliError(`target ${target.name}’s keys were ${at ? `checked for ${where(at)}` : 'stored without the address they were checked for'}, and frontera.yaml now points it at ${where(target.link)}`, {
+    code: 'SYNC_TARGET_MOVED',
+    hint: `its keys are not sent there. If ${target.name} moved, connect it again: \`frontera local sync connect --target ${target.name} --platform ${platform}\`; otherwise put its entry back`,
+  })
+}
+
 // ── The link's target as a CLI profile ──────────────────────────────────────
 
 /**
@@ -179,8 +323,8 @@ export function removeSyncKey(project: LocalProject, role: KeyRole): void {
  * read that checks them) names this profile with `--profile`; the remote guard
  * lets a command that names its target through.
  */
-export function targetProfileName(project: LocalProject, link: SyncLink): string {
-  const target = [project.id, link.platform, link.workspace].join('\n')
+export function targetProfileName(owner: KeyOwner, link: CheckedAt): string {
+  const target = [owner.id, link.platform, link.workspace].join('\n')
   return `sync-${createHash('sha256').update(target).digest('hex').slice(0, 16)}`
 }
 
@@ -188,27 +332,28 @@ export function targetProfileName(project: LocalProject, link: SyncLink): string
 export const targetOf = (link: SyncLink) => `${new URL(link.platform).host}/${link.workspace}`
 
 /**
- * The person signed in for the project's target (`frontera auth login
- * --browser --profile <target>`), when the sign-in is for the linked
- * platform and still lasts; null otherwise. Only the target profile's own
- * sign-in counts: one kept for another profile is never borrowed.
+ * The person signed in for the target profile of the project's link, or of
+ * one of its named targets (`owner`), with `frontera auth login --browser
+ * --profile <target>`, when the sign-in is for that platform and still lasts;
+ * null otherwise. Only that profile's own sign-in counts: one kept for another
+ * profile, the link's or another target's, is never borrowed.
  */
-export function targetSession(project: LocalProject, link: SyncLink): Promise<DeviceSession | null> {
-  return readDeviceSession(credentialStore(), targetProfileName(project, link), link.platform)
+export function targetSession(owner: KeyOwner, link: SyncLink): Promise<DeviceSession | null> {
+  return readDeviceSession(credentialStore(), targetProfileName(owner, link), link.platform)
 }
 
 /**
- * The project's reader at organization grain (`client`): the person signed
- * in for the target, in the linked workspace's organization, when they may
- * read there (a Blueprint Steward, or an owner or admin); else the
- * organization key stored; null with neither. `notSteward` names the person
- * signed in when they may not and no key reads in their place.
+ * The reader at organization grain (`client`) for the link or a named target
+ * (`owner`): the person signed in for it, in its workspace's organization,
+ * when they may read there (a Blueprint Steward, or an owner or admin); else
+ * the organization key stored for it; null with neither. `notSteward` names
+ * the person signed in when they may not and no key reads in their place.
  */
-export async function organizationReader(project: LocalProject, link: SyncLink): Promise<{ client: SyncClient | null; notSteward: string | null }> {
-  const key = getSyncKey(project, 'organization')
+export async function organizationReader(owner: KeyOwner, link: SyncLink): Promise<{ client: SyncClient | null; notSteward: string | null }> {
+  const key = getSyncKey(owner, 'organization')
   const byKey = key ? syncClient(link.platform, key) : null
-  const person = await targetSession(project, link)
-  const orgId = person ? await targetOrganization(project, link) : null
+  const person = await targetSession(owner, link)
+  const orgId = person ? await targetOrganization(owner, link) : null
   if (!person || !orgId) return { client: byKey, notSteward: null }
   const client = syncClient(link.platform, person.token, { 'x-org-id': orgId })
   if (await readsOrganization(client, person.token, orgId)) return { client, notSteward: null }
@@ -227,23 +372,23 @@ function readsOrganization(client: SyncClient, token: string, orgId: string): Pr
 }
 
 /** The linked workspace's organization, as the target profile records it: a profile recorded before it knew one is recorded again. */
-async function targetOrganization(project: LocalProject, link: SyncLink): Promise<string | null> {
-  const name = targetProfileName(project, link)
-  if (!getProfile(name)?.orgId) await registerTargetProfile(project, link).catch(() => null)
+async function targetOrganization(owner: KeyOwner, link: SyncLink): Promise<string | null> {
+  const name = targetProfileName(owner, link)
+  if (!getProfile(name)?.orgId) await registerTargetProfile(owner, link).catch(() => null)
   return getProfile(name)?.orgId ?? null
 }
 
 /** The linked workspace's organization as the platform answers the workspace key; null when it does not. */
-async function workspaceOrganization(project: LocalProject, link: SyncLink): Promise<string | null> {
-  const key = getSyncKey(project, 'workspace')
+async function workspaceOrganization(owner: KeyOwner, link: SyncLink): Promise<string | null> {
+  const key = getSyncKey(owner, 'workspace')
   const me = key ? await syncClient(link.platform, key).get<{ orgId?: string | null }>('/v1/whoami').catch(() => null) : null
   return me?.orgId ?? null
 }
 
 /** The fingerprints of the keys stored for the project now. */
-export function projectKeyFingerprints(project: LocalProject): string[] {
+export function projectKeyFingerprints(owner: KeyOwner): string[] {
   return (['organization', 'workspace'] as const).flatMap((role) => {
-    const key = getSyncKey(project, role)
+    const key = getSyncKey(owner, role)
     return key ? [fingerprint(key)] : []
   })
 }
@@ -260,13 +405,13 @@ export function projectKeyFingerprints(project: LocalProject): string[] {
  * which `connect` knows even with no organization key; without it, the one
  * recorded, else the platform's answer to the workspace key.
  */
-export async function registerTargetProfile(project: LocalProject, link: SyncLink, previous: readonly string[] = [], orgId: string | null = null): Promise<string | null> {
-  const organizationKey = getSyncKey(project, 'organization')
-  const key = organizationKey ?? getSyncKey(project, 'workspace')
+export async function registerTargetProfile(owner: KeyOwner, link: SyncLink, previous: readonly string[] = [], orgId: string | null = null): Promise<string | null> {
+  const organizationKey = getSyncKey(owner, 'organization')
+  const key = organizationKey ?? getSyncKey(owner, 'workspace')
   if (!key) return null
-  const name = targetProfileName(project, link)
+  const name = targetProfileName(owner, link)
   const existing = getProfile(name)
-  if (existing && ![...previous, ...projectKeyFingerprints(project)].includes(existing.fingerprint)) {
+  if (existing && ![...previous, ...projectKeyFingerprints(owner)].includes(existing.fingerprint)) {
     throw new Error(`the profile ${name} holds a key that isn't this project's, so it is left as it is; \`frontera auth remove ${name}\` frees the name`)
   }
   await credentialStore().set(name, key)
@@ -277,7 +422,7 @@ export async function registerTargetProfile(project: LocalProject, link: SyncLin
     workspaceId: organizationKey ? null : link.workspace,
     // The workspace's organization as the platform reports it, so the person signed in on the profile addresses it
     // when they belong to several. Never frontera.yaml's: a file in the repository does not choose it.
-    orgId: orgId ?? existing?.orgId ?? (await workspaceOrganization(project, link)),
+    orgId: orgId ?? existing?.orgId ?? (await workspaceOrganization(owner, link)),
     fingerprint: fingerprint(key),
     createdAt: existing?.createdAt ?? now,
     lastVerifiedAt: now,
@@ -286,12 +431,67 @@ export async function registerTargetProfile(project: LocalProject, link: SyncLin
 }
 
 /** Remove this folder's target profile with its key and its browser sign-in, unless the profile holds a key that isn't the project's. */
-export async function removeTargetProfile(project: LocalProject, link: SyncLink): Promise<void> {
-  const name = targetProfileName(project, link)
+export async function removeTargetProfile(owner: KeyOwner, link: CheckedAt): Promise<void> {
+  const name = targetProfileName(owner, link)
   const existing = getProfile(name)
-  if (existing && !projectKeyFingerprints(project).includes(existing.fingerprint)) return
+  if (existing && !projectKeyFingerprints(owner).includes(existing.fingerprint)) return
   if (existing) deleteProfile(name)
   const store = credentialStore()
   await store.delete(name)
   await forgetDeviceSession(store, name, (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(5_000) }))
 }
+
+// ── Where a command delivers ────────────────────────────────────────────────
+
+/**
+ * Where a `local sync` command acts: the project's link (`name` null, what
+ * every command acts on unless it names a target), or a named target.
+ */
+export interface SyncTarget {
+  name: string | null
+  link: SyncLink
+  production: boolean
+  /** Whose keys and target profile it uses: never another target's. */
+  owner: KeyOwner
+  /**
+   * The root its change requests and fetched snapshot are kept under, laid
+   * out as the project's own, so the same readers serve it: the project
+   * folder for the link, `.frontera/sync/targets/<name>/` for a named target.
+   */
+  state: string
+}
+
+export function linkTarget(project: LocalProject, link: SyncLink): SyncTarget {
+  return { name: null, link, production: false, owner: project, state: project.root }
+}
+
+/** Whose keys and target profile a target uses: the project's for its link, `<project id>@<name>` for a named target. */
+export function targetOwner(project: LocalProject, name: string | null): KeyOwner {
+  return name ? { id: `${project.id}@${name}` } : project
+}
+
+/** Where a named target's change requests, snapshot and base live. */
+export function targetState(project: Pick<LocalProject, 'root'>, name: string): string {
+  return join(project.root, '.frontera', 'sync', 'targets', name)
+}
+
+export function namedTarget(project: LocalProject, name: string, target: NamedTarget): SyncTarget {
+  return { name, link: target, production: target.production === true, owner: targetOwner(project, name), state: targetState(project, name) }
+}
+
+/** The project's link, when it has one, then its named targets. */
+export function projectTargets(project: LocalProject): SyncTarget[] {
+  const link = readLink(project.root)
+  return [...(link ? [linkTarget(project, link)] : []), ...Object.entries(readTargets(project.root)).map(([name, t]) => namedTarget(project, name, t))]
+}
+
+/** A command's words for this target: `--target <name>` follows them for a named target. */
+export function targetWords(target: Pick<SyncTarget, 'name'>, words: string): string {
+  return target.name ? `${words} --target ${target.name}` : words
+}
+
+/** How the output names the target: its workspace, and the target's name when it has one. */
+export function targetLabel(target: Pick<SyncTarget, 'name' | 'link'>): string {
+  const workspace = target.link.workspaceName ?? target.link.workspace
+  return target.name ? `${workspace} (target ${target.name})` : workspace
+}

package/src/local/local-sync-plan.ts

@@ -523,7 +523,7 @@ export interface ApplyResult {
 }
 
 /** The lock entry for an item as the workspace has it: the base after a pull or a resolve. */
-function entryFor(item: RemoteItem, now: string): LockEntry {
+export function entryFor(item: RemoteItem, now: string): LockEntry {
   return {
     ...(item.id ? { id: item.id } : {}),
     ...(item.revision ? { revision: item.revision } : {}),

package/src/local/local-sync-precheck.ts

@@ -1,3 +1,4 @@
+import { targetLabel, targetWords, type SyncTarget } from './local-sync-link'
 import { modelsNamed } from './local-sync-portable'
 import type { Check, PushItem } from './local-sync-push'
 
@@ -109,15 +110,28 @@ export function splitCheckMessage(message: string): { why: string; file: string
   return { why: m[2]!.charAt(0).toUpperCase() + m[2]!.slice(1), file: m[1]! }
 }
 
+const MOVED_THERE: Record<string, string> = { stale_base: 'Changed in', gone: 'Deleted in', exists: 'Made in' }
+
+/**
+ * A refusal because the item moved on a named target since this push read
+ * it, in the target's words: a target is never pulled from, so its fix is a
+ * look that reads it again. Null for the link, and for any other refusal.
+ */
+export function movedOnTarget(check: Check, target: Pick<SyncTarget, 'name' | 'link'>): { reason: string; fix: string } | null {
+  const moved = target.name ? MOVED_THERE[check.code] : undefined
+  return moved ? { reason: `${moved} ${targetLabel(target)} since this push read it`, fix: `look again with \`${targetWords(target, 'frontera local sync push --preview')}\`, which reads what it holds now` } : null
+}
+
 /** Block each item the workspace's checks would refuse, with the reason first and its fix. Returns the refs refused. */
-export function markRefused(items: PushItem[], checks: Check[]): string[] {
+export function markRefused(items: PushItem[], checks: Check[], target?: Pick<SyncTarget, 'name' | 'link'>): string[] {
   const byRef = new Map(items.map((i) => [i.ref, i]))
   const refused: string[] = []
   for (const check of checks) {
     const item = byRef.get(check.ref)
     if (!item || !item.proposable) continue
     const { why, file } = splitCheckMessage(check.message)
-    Object.assign(item, { proposable: false, blocked: 'refused', reason: file ? `${why} (${file})` : why, fix: fixFor(check) })
+    const there = target ? movedOnTarget(check, target) : null
+    Object.assign(item, { proposable: false, blocked: 'refused', reason: there?.reason ?? (file ? `${why} (${file})` : why), fix: there?.fix ?? fixFor(check) })
     refused.push(item.ref)
   }
   return refused

package/src/local/local-synthetic-data.ts

@@ -62,8 +62,13 @@ interface Property {
   enum?: unknown[]
   /** A calculated field (a location from latitude and longitude): computed by the Blueprint, never a column. */
   calculation?: unknown
+  /** An edit-only field: only Actions write it, so sample data gives it no column and no value. */
+  editOnly?: boolean
 }
 
+/** Whether a property reads a column of its type's dataset: neither calculated nor edit-only. */
+const readsColumn = (p: Property) => !p.calculation && p.editOnly !== true
+
 /**
  * Whether a record may leave a property empty: unless it says `required:
  * true`, as the Blueprint reads it (a property without `required` is
@@ -327,7 +332,7 @@ export function inferReferences(types: ObjectType[], refs: Map<string, Map<strin
   for (const type of types) {
     const own = refs.get(type.apiName)
     for (const p of type.properties ?? []) {
-      if (p.calculation || p.apiName === primaryKeys.get(type.apiName) || own?.has(p.apiName) || !['string', 'number'].includes(p.valueType ?? 'string') || hasValues(type, p)) continue
+      if (!readsColumn(p) || p.apiName === primaryKeys.get(type.apiName) || own?.has(p.apiName) || !['string', 'number'].includes(p.valueType ?? 'string') || hasValues(type, p)) continue
       const others = types.filter((t) => t.apiName !== type.apiName && sameKind(p, t))
       const name = squash(p.apiName)
       // Another type's key by name: `staffId`, `decisionId`.
@@ -1528,11 +1533,11 @@ function timeBound(c: Constraint, rule: SemanticType['rule'] | undefined): Const
   return { ...c, ...(Number.isFinite(min) ? { min } : {}), ...(Number.isFinite(max) ? { max } : {}) }
 }
 
-/** The properties a type's dataset holds a column for: not a calculated field, and in its mapping when it has one. */
+/** The properties a type's dataset holds a column for: not a calculated or edit-only field, and in its mapping when it has one. */
 export function storedProperties(type: ObjectType): Property[] {
   const mapping = type.backing?.mapping
   const mapped = mapping && Object.keys(mapping).length ? new Set(Object.keys(mapping)) : null
-  return (type.properties ?? []).filter((p) => !p.calculation && (!mapped || mapped.has(p.apiName)))
+  return (type.properties ?? []).filter((p) => readsColumn(p) && (!mapped || mapped.has(p.apiName)))
 }
 
 type Row = Record<string, unknown>
@@ -1824,8 +1829,8 @@ export function generateSyntheticData(root: string, opts: SyntheticOptions = {})
     // Types others point at are the fewer ones (customers, products); the rest scale with them.
     const referenced = [...refs.values()].some((m) => [...m.values()].some((r) => r.objectType === type.apiName))
     const wanted = custom?.rows ?? (referenced ? Math.max(5, Math.round(baseRows / 2)) : baseRows)
-    // A calculated field is the Blueprint's to compute: no value, no column.
-    const properties = (type.properties ?? []).filter((p) => !p.calculation)
+    // A calculated field is the Blueprint's to compute, and an edit-only one the Actions' to write: no value, no column.
+    const properties = (type.properties ?? []).filter(readsColumn)
     const pk = primaryKeys.get(type.apiName)!
     const prefix = keyPrefix(type.apiName)
     const ownRefs = refs.get(type.apiName) ?? new Map<string, Reference>()
@@ -2303,8 +2308,8 @@ export function addMissingBackings(root: string): string[] {
   for (const { file, doc } of readTree<ObjectType>(dir)) {
     if (!doc?.apiName || doc.backing?.dataset) continue
     const { dataset, column } = backingOf(doc)
-    // A calculated field reads no column.
-    const next = { ...doc, backing: { dataset, mapping: Object.fromEntries((doc.properties ?? []).filter((p) => !p.calculation).map((p) => [p.apiName, column(p.apiName)])) } }
+    // A calculated or edit-only field reads no column.
+    const next = { ...doc, backing: { dataset, mapping: Object.fromEntries((doc.properties ?? []).filter(readsColumn).map((p) => [p.apiName, column(p.apiName)])) } }
     const path = join(dir, file)
     writeFileSync(path, file.endsWith('.json') ? `${JSON.stringify(next, null, 2)}\n` : stringifyYaml(next, { lineWidth: 0 }))
     changed.push(join('blueprint', 'object-types', file))

package/src/mcp/tools/project-tools.ts

@@ -18,7 +18,7 @@ import { readBaseline } from '../../local/local-db-snapshot'
 import { stuckKnowledge } from '../../local/local-knowledge-ingestion'
 import { projectOrphans } from '../../local/local-orphans'
 import type { LocalProject } from '../../local/local-project'
-import { readLink } from '../../local/local-sync-link'
+import { leftOutTargets, readLink, readTargets } from '../../local/local-sync-link'
 import { logPath, readState, type ComponentName } from '../../local/local-state'
 import { runSelf } from '../mcp-cli'
 import { errorResult, intArg, jsonResult, stringArg, type McpTool } from '../mcp-protocol'
@@ -71,7 +71,7 @@ export function projectTools(project: LocalProject): McpTool[] {
     {
       name: 'status',
       description:
-        "Where the project stands on the local runtime: who last changed it or its files (`writers`, one per session, `self` for yours; `runtimeLock` while another run holds the runtime), what each Agent, workflow, Function and Blueprint object type came to (built, adapted, stubbed, needs setup, blocked, failed, not applied) with the reason chain to the item actually at fault, files saved but not applied, the workspace link, the runtime's health and its documentation's version, the saved object sets with their ids (blueprint_query reads one), any knowledge document left pending or processing with no ingestion behind it (`knowledgeStuck`, each with the command that re-queues it), and each Agent, workflow, Function or knowledge base on the runtime with no file in the project (`notInProject`, each with its fix: apply archives an Agent or workflow whose file was deleted, and switches off such a Function). `build` counts exactly the rows `items` lists with all: true. Read it first after a change.",
+        "Where the project stands on the local runtime: who last changed it or its files (`writers`, one per session, `self` for yours; `runtimeLock` while another run holds the runtime), what each Agent, workflow, Function and Blueprint object type came to (built, adapted, stubbed, needs setup, blocked, failed, not applied) with the reason chain to the item actually at fault, files saved but not applied, the workspace link and the named targets the project delivers to (`targets`: `local sync push --target <name>`) and any entry in frontera.yaml it leaves out (`targetsLeftOut`, each with what to fix), the runtime's health and its documentation's version, the saved object sets with their ids (blueprint_query reads one), any knowledge document left pending or processing with no ingestion behind it (`knowledgeStuck`, each with the command that re-queues it), and each Agent, workflow, Function or knowledge base on the runtime with no file in the project (`notInProject`, each with its fix: apply archives an Agent or workflow whose file was deleted, and switches off such a Function). `build` counts exactly the rows `items` lists with all: true. Read it first after a change.",
       inputSchema: { type: 'object', properties: { all: { type: 'boolean', description: 'List built items too, not only the ones with something to say (default false).' } }, additionalProperties: false },
       annotations: { title: 'Project status', readOnlyHint: true, openWorldHint: false },
       async run(input) {
@@ -140,6 +140,13 @@ export function projectTools(project: LocalProject): McpTool[] {
             return orphans?.length ? { notInProject: orphans.map((o) => ({ ref: o.ref, problem: o.problem, fix: o.fix, fileDeleted: o.deleted })) } : {}
           })()),
           workspace: sync ? { linked: true, workspace: sync.workspaceName ?? sync.workspace, platform: sync.platform } : { linked: false },
+          // The named targets it delivers to by name (`local sync push --target <name>`); a production one is reached only so.
+          // An entry in frontera.yaml the CLI can't use is listed apart, with what to fix.
+          ...(() => {
+            const named = Object.entries(readTargets(project.root))
+            const leftOut = leftOutTargets(project.root)
+            return { ...(named.length ? { targets: named.map(([name, t]) => ({ name, workspace: t.workspaceName ?? t.workspace, platform: t.platform, production: t.production === true })) } : {}), ...(leftOut.length ? { targetsLeftOut: leftOut } : {}) }
+          })(),
           // The steps prepared for the person and not yet run (person_step): the delivery card Forge shows.
           ...(() => {
             const pending = readPersonSteps(project.root).filter((p) => p.status === 'pending')