@frontera-sdk/cli 1.53.10 → 1.53.12

package/src/commands/local/sync.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
 
 import { CliError, UsageError } from '../../errors'
@@ -11,7 +11,38 @@ import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/l
 import { analyticsNeeded, connectionsNeeded, documentationNeeded, standInPath, writePlatformOnly, writeStandIns } from '../../local/local-stand-ins'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { normalizeOrigin, syncClient, type SyncClient } from '../../local/local-sync-client'
-import { getSyncKey, organizationReader, projectFile, projectKeyFingerprints, readLink, registerTargetProfile, removeSyncKey, removeTargetProfile, setSyncKey, targetProfileName, targetSession, writeLink, type SyncLink } from '../../local/local-sync-link'
+import {
+  getSyncKey,
+  keysCheckedAt,
+  leftOutTargets,
+  linkTarget,
+  namedTarget,
+  organizationReader,
+  projectFile,
+  projectKeyFingerprints,
+  projectTargets,
+  readLink,
+  readTargets,
+  refuseMovedTarget,
+  registerTargetProfile,
+  removeSyncKey,
+  removeTargetProfile,
+  setKeysCheckedAt,
+  setSyncKey,
+  TARGET_NAME,
+  targetLabel,
+  targetOwner,
+  targetProfileName,
+  targetSession,
+  targetState,
+  targetWords,
+  writeLink,
+  writeTarget,
+  type KeyOwner,
+  type NamedTarget,
+  type SyncLink,
+  type SyncTarget,
+} from '../../local/local-sync-link'
 import { signInStep } from '../../device-login'
 import { describeRepair, repairBases, type BaseRepair } from '../../local/local-sync-base'
 import { conflictsId, mergeItemFiles, type Choice, type Conflict, type Side } from '../../local/local-sync-merge'
@@ -19,6 +50,7 @@ import {
   applyItems,
   baseFiles,
   computePlan,
+  entryFor,
   forgetItems,
   itemHash,
   KIND_LABEL,
@@ -29,11 +61,14 @@ import {
   summarize,
   SYNC_KINDS,
   WORKSPACE_SUFFIX,
+  writeLock,
   type ItemStatus,
+  type LockEntry,
   type PlanItem,
   type RemoteItem,
   type Resolution,
   type SyncKind,
+  type SyncLock,
 } from '../../local/local-sync-plan'
 import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
 import { rememberLocalCatalog } from '../../local/local-sync-models'
@@ -62,7 +97,7 @@ import {
   type RemoteSnapshot,
 } from '../../local/local-sync-snapshot'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
-import { currentRequest, readRequests } from '../../local/local-sync-push'
+import { currentRequest, projectRefs, readRequests } from '../../local/local-sync-push'
 import { syncMapModel, syncPush, syncRequest } from './sync-request'
 
 /**
@@ -83,6 +118,12 @@ import { syncMapModel, syncPush, syncRequest } from './sync-request'
  * and `request apply` write to the workspace, through a change request.
  * Keys arrive on stdin or at a hidden prompt and go to the keychain; the
  * link is in `frontera.yaml`.
+ *
+ * Named targets (`sync.targets`: staging, production) are workspaces the
+ * project delivers to besides its link, each with its own keys, profile and
+ * change requests and base. `connect`, `push`, `request`, `diff`, `resolve`
+ * and `disconnect` act on one when they name it with `--target`; nothing else
+ * reaches it, and nothing is pulled from it.
  */
 
 /** A snapshot this recent is used as it is by pull; an older one is fetched again first. */
@@ -107,11 +148,43 @@ function needLink(project: LocalProject): SyncLink {
   return link
 }
 
-/** The project's readers: the workspace's with its key, and the organization's (`organizationReader`) when there is one. */
-export async function sourceFor(project: LocalProject, link: SyncLink): Promise<SyncSource> {
-  const key = getSyncKey(project, 'workspace')
-  if (!key) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (the link is in frontera.yaml; keys are per machine)' })
-  const { client, notSteward } = await organizationReader(project, link)
+/**
+ * The target a command names with `--target`, else the project's link. The
+ * name is matched exactly, so a production target is reached only when the
+ * command names it; one the CLI leaves out is refused with why, and one the
+ * project doesn't have with the ones it has.
+ */
+function findTarget(project: LocalProject, ctx: CommandContext): SyncTarget {
+  const name = flagString(ctx, 'target')
+  if (name === undefined) return linkTarget(project, needLink(project))
+  const targets = readTargets(project.root)
+  const target = targets[name]
+  const leftOut = leftOutTargets(project.root).find((t) => t.name === name)
+  if (leftOut) throw new UsageError(`target ${name} in frontera.yaml can’t be used: ${leftOut.problem}`, `fix its entry in frontera.yaml, or connect it again: \`frontera local sync connect --target ${TARGET_NAME.test(name) ? name : '<name>'} --platform <url>\``)
+  if (!target) {
+    const names = Object.keys(targets)
+    throw new UsageError(`this project has no target \`${name}\``, names.length ? `its targets are ${names.join(', ')}, named exactly` : `add one with \`frontera local sync connect --target ${TARGET_NAME.test(name) ? name : '<name>'} --platform <url> --workspace-key -\``)
+  }
+  return namedTarget(project, name, target)
+}
+
+/** Where a command that calls the platform acts: a named target only while it points where its keys were checked. */
+export function chooseTarget(project: LocalProject, ctx: CommandContext): SyncTarget {
+  const target = findTarget(project, ctx)
+  refuseMovedTarget(target)
+  return target
+}
+
+/**
+ * The readers for a project's link, or for one of its named targets (`name`),
+ * with that one's own keys and sign-in, never another target's: the
+ * workspace's with its key, and the organization's (`organizationReader`)
+ * when there is one.
+ */
+export async function sourceFor(owner: KeyOwner, link: SyncLink, name: string | null = null): Promise<SyncSource> {
+  const key = getSyncKey(owner, 'workspace')
+  if (!key) throw new CliError(`no workspace key for ${name ? `target ${name}` : 'this project'} on this machine`, { code: 'SYNC_NO_KEY', hint: `run \`${targetWords({ name }, 'frontera local sync connect')}\` to store one (the link is in frontera.yaml; keys are per machine)` })
+  const { client, notSteward } = await organizationReader(owner, link)
   return {
     workspace: syncClient(link.platform, key),
     ...(client ? { organization: client } : {}),
@@ -195,12 +268,68 @@ export async function fetchFor(project: LocalProject, link: SyncLink, opts: { fu
   return { ...result, conflicts: await settleConflicts(project, link, result.snapshot, source) }
 }
 
+/**
+ * Fetch where a command delivers: the link as `fetchFor` does, or a named
+ * target into its own snapshot (`target.state`) with its own keys. A named
+ * target is never pulled from, so it has no conflicts to settle.
+ */
+export async function fetchTarget(project: LocalProject, target: SyncTarget, opts: { full?: boolean } = {}): Promise<FetchResult> {
+  if (!target.name) return fetchFor(project, target.link, opts)
+  const source = await sourceFor(target.owner, target.link, target.name)
+  const result = await fetchWorkspace(target.state, source, { blueprint: target.link.blueprint, full: opts.full })
+  await nameLink(project, target.link, source, (named) => writeTarget(project.root, target.name!, { ...named, ...(target.production ? { production: true } : {}) }))
+  return result
+}
+
+/**
+ * The plan against a named target. The project's own base was pulled from
+ * its link, whose ids and revisions are another platform's, so a target keeps
+ * a base of its own: what an Apply to it left (`frontera.lock` under
+ * `target.state`). A change made on the target since then reads as changed
+ * there, and is not put back unasked; one made on both sides is a conflict.
+ * An item the project knows (pulled, or made here) that it never delivered to
+ * the target, but the target holds, has the target's version as its base, so
+ * whatever differs here is proposed over it with the target's own id and
+ * revision. An item the target doesn't hold is new there, unless this project
+ * delivered it: then the target deleted it since. An item pulled with
+ * conflicts stays unresolved. The target's index is read whole, since one
+ * read from a cursor lists no deletion.
+ */
+export async function targetPlan(project: LocalProject, target: SyncTarget) {
+  const { snapshot } = await fetchTarget(project, target, { full: true })
+  const items = snapshotItems(target.state, snapshot)
+  const theirs = new Map(items.map((i) => [i.ref, i]))
+  const gone = knownGone(snapshot)
+  const delivered = readLock(target.state)
+  const known = delivered?.workspace === target.link.workspace ? delivered.items : {}
+  const pulled = readLock(project.root)?.items ?? {}
+  const now = new Date().toISOString()
+  // The base text of an item never delivered from here: what the target holds.
+  const holds = new Map<string, string>()
+  const refs = new Set([...Object.keys(known), ...Object.keys(pulled), ...projectRefs(project.root).keys()])
+  const lock: SyncLock = {
+    version: 2,
+    workspace: target.link.workspace,
+    items: Object.fromEntries([...refs].flatMap((ref): Array<[string, LockEntry]> => {
+      const item = theirs.get(ref)
+      if (!item) return known[ref] && gone(ref) ? [[ref, known[ref]!]] : []
+      if (!known[ref]) for (const [path, text] of Object.entries(item.files)) holds.set(path, text)
+      const conflict = pulled[ref]?.conflict
+      return [[ref, { ...(known[ref] ?? entryFor(item, now)), ...(conflict ? { conflict } : {}) }]]
+    })),
+  }
+  const base = (path: string) => holds.get(path) ?? readBase(target.state, path)
+  await refreshLocalCatalog(project)
+  const plan = computePlan(project.root, items, lock, localItems(project), { remoteKnownGone: gone, base, directory: directoryOf(snapshot) })
+  return { remote: { items, warnings: snapshot.warnings, notes: snapshot.notes }, plan, lock, snapshot, base, delivered: new Set(Object.keys(known)) }
+}
+
 /**
  * A link made while the platform could not say the workspace's name (or
  * before it could) learns it on the next fetch, so the project shows the
  * workspace by its name rather than its id. The link passed in is named too.
  */
-async function nameLink(project: LocalProject, link: SyncLink, source: SyncSource): Promise<void> {
+async function nameLink(project: LocalProject, link: SyncLink, source: SyncSource, write = (named: SyncLink) => writeLink(project.root, named)): Promise<void> {
   if (link.workspaceName && link.organizationName) return
   const identity = await source.workspace.find<{ workspace?: { name?: unknown }; organization?: { name?: unknown } }>('/v1/sync/identity').catch(() => null)
   const name = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
@@ -208,7 +337,7 @@ async function nameLink(project: LocalProject, link: SyncLink, source: SyncSourc
   const organizationName = link.organizationName ?? name(identity?.organization?.name)
   if (workspaceName === link.workspaceName && organizationName === link.organizationName) return
   Object.assign(link, { workspaceName, organizationName })
-  writeLink(project.root, link)
+  write(link)
 }
 
 /** The snapshot for this link, when one was fetched for it. */
@@ -420,26 +549,50 @@ async function checkKeys(platform: string, keys: { workspace: string; organizati
 
 const connect = async (ctx: CommandContext) => {
   const project = localProject(ctx.cwd)
-  const previous = readLink(project.root)
+  // `--target <name>`: a named target (`sync.targets.<name>`) with its own keys; without it, the project's link.
+  const name = flagString(ctx, 'target') ?? null
+  if (name !== null && !TARGET_NAME.test(name)) throw new UsageError(`\`${name}\` can’t name a target`, 'a target’s name is lowercase letters, digits and dashes, starting with a letter: staging, production')
+  if (name === null && flagBool(ctx, 'production')) throw new UsageError('--production marks a named target', 'the project’s link is never a production target: `frontera local sync connect --target production --production --platform <url> --workspace-key -`')
+  const link = readLink(project.root)
+  const targets = readTargets(project.root)
+  const previous = name ? targets[name] ?? null : link
+  const owner = targetOwner(project, name)
   const platformRaw = flagString(ctx, 'platform') ?? previous?.platform
-  if (!platformRaw) throw new UsageError('give the platform address', 'frontera local sync connect --platform https://api.acme.frontera.example')
+  if (!platformRaw) throw new UsageError('give the platform address', `${targetWords({ name }, 'frontera local sync connect')} --platform https://api.acme.frontera.example`)
   const platform = normalizeOrigin(platformRaw)
   const wantOrg = flagString(ctx, 'org-key') !== undefined
   const keys = await readKeys(ctx, wantOrg)
   if (!keys.workspace) throw new UsageError('no workspace key given', 'pass `--workspace-key -` with the key on stdin, or run in a terminal to be prompted')
   const { me, identity } = await checkKeys(platform, keys)
   if (previous && previous.workspace !== me.workspaceId && !flagBool(ctx, 'relink')) {
-    throw new CliError(`this project is linked to another workspace (${previous.workspaceName ?? previous.workspace})`, { code: 'CONFLICT', hint: 'a project links to one workspace; pass --relink to point it at this one' })
+    throw new CliError(`${name ? `target ${name}` : 'this project'} is linked to another workspace (${previous.workspaceName ?? previous.workspace})`, { code: 'CONFLICT', hint: `${name ? 'a target' : 'a project'} links to one workspace; pass --relink to point it at this one` })
   }
+  // Each workspace is reached one way: by the link, or by one named target. The link is never pointed at a production target.
+  const others: Array<[string | null, NamedTarget]> = [...(name && link ? [[null, link] as [null, SyncLink]] : []), ...Object.entries(targets).filter(([n]) => n !== name)]
+  const taken = others.find(([, t]) => normalizeOrigin(t.platform) === platform && t.workspace === me.workspaceId)
+  if (taken) {
+    const [other, t] = taken
+    const where = t.workspaceName ?? t.workspace
+    if (other === null) throw new CliError(`${where} is this project’s link already`, { code: 'CONFLICT', hint: 'a named target is another workspace; push and apply to the link without --target' })
+    throw new CliError(`target ${other} reaches ${where} already`, {
+      code: 'CONFLICT',
+      hint: t.production
+        ? `${other} is a production target, reached only by its name: deliver to it with \`--target ${other}\``
+        : `deliver to it with \`--target ${other}\`, or remove that target first (\`frontera local sync disconnect --target ${other} --forget-link\`)`,
+    })
+  }
+  const production = name !== null && (flagBool(ctx, 'production') || targets[name]?.production === true)
   const blueprintFlag = flagString(ctx, 'blueprint')
   if (blueprintFlag && blueprintFlag !== 'workspace' && blueprintFlag !== 'organization') throw new UsageError('--blueprint is workspace or organization', '`--blueprint organization` reads the whole model and needs an organization key')
-  // The stored organization key belongs to the previous link's platform and organization: kept only while both stay.
-  const keepsOrganizationKey = !keys.organization && previous?.platform === platform && previous.organization === me.orgId
-  const link: SyncLink = {
+  // The stored organization key belongs to the platform and organization it was checked with: kept only while both stay.
+  // A named target's entry is a committed file that a commit can move, so its keys stay only where `connect` checked them.
+  const checked = name ? keysCheckedAt(owner) : previous
+  const keepsOrganizationKey = !keys.organization && checked?.platform === platform && (name ? checked.workspace === me.workspaceId : previous?.organization === me.orgId)
+  const next: SyncLink = {
     platform,
     workspace: me.workspaceId!,
     workspaceName: identity?.workspace.name ?? previous?.workspaceName,
-    organization: keys.organization ? me.orgId! : keepsOrganizationKey ? previous!.organization : undefined,
+    organization: keys.organization || keepsOrganizationKey ? me.orgId! : undefined,
     organizationName: identity?.organization.name ?? previous?.organizationName,
     blueprint: (blueprintFlag as SyncLink['blueprint'] | undefined) ?? (previous?.blueprint === 'organization' && keys.organization ? 'organization' : 'workspace'),
     // The models mapped for this workspace stay; another workspace has its own catalog.
@@ -448,29 +601,33 @@ const connect = async (ctx: CommandContext) => {
   // A folder that is not a project yet gets the project file the link lives in.
   if (!existsSync(projectFile(project.root))) writeFileSync(projectFile(project.root), `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${basename(project.root)}\n`)
   // The previous target's profile goes with the keys it was made from.
-  if (previous && targetProfileName(project, previous) !== targetProfileName(project, link)) await removeTargetProfile(project, previous)
+  if (checked && targetProfileName(owner, checked) !== targetProfileName(owner, next)) await removeTargetProfile(owner, checked)
   // Read before the keys are replaced, so a profile holding the key a rotation replaces is still the project's.
-  const previousKeys = projectKeyFingerprints(project)
-  setSyncKey(project, 'workspace', keys.workspace)
-  if (keys.organization) setSyncKey(project, 'organization', keys.organization)
-  else if (!keepsOrganizationKey) removeSyncKey(project, 'organization')
-  writeLink(project.root, link)
+  const previousKeys = projectKeyFingerprints(owner)
+  setSyncKey(owner, 'workspace', keys.workspace)
+  if (keys.organization) setSyncKey(owner, 'organization', keys.organization)
+  else if (!keepsOrganizationKey) removeSyncKey(owner, 'organization')
+  if (name) {
+    setKeysCheckedAt(owner, next)
+    writeTarget(project.root, name, { ...next, ...(production ? { production: true } : {}) })
+  } else writeLink(project.root, next)
   // The workspace as a CLI profile: a change request's steps for a person name it (`--profile`).
-  const { profile, profileError } = await registerTargetProfile(project, link, previousKeys, me.orgId).then(
-    (name) => ({ profile: name, profileError: null }),
+  const { profile, profileError } = await registerTargetProfile(owner, next, previousKeys, me.orgId).then(
+    (profileName) => ({ profile: profileName, profileError: null }),
     (err: Error) => ({ profile: null, profileError: err.message }),
   )
   // A change request is applied as the person signed in for this profile; no organization key needs to be here.
-  const signIn = profile ? await signInStep({ profile, apiUrl: link.platform, named: true }) : null
+  const signIn = profile ? await signInStep({ profile, apiUrl: next.platform, named: true }) : null
+  const where = `${next.workspaceName ?? next.workspace}${next.organizationName ? ` (${next.organizationName})` : ''} on ${new URL(platform).host}`
   return {
-    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) }, profile, signIn },
+    data: { link: next, ...(name ? { target: name, production } : {}), keys: { workspace: true, organization: !!(keys.organization || getSyncKey(owner, 'organization')) }, profile, signIn },
     text: [
-      `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(platform).host}.`,
-      'Keys are in your keychain; the link is in frontera.yaml.',
+      name ? `Target ${name}${production ? ' (production: reached only by its name)' : ''} is ${where}.` : `Linked to ${where}.`,
+      name ? 'Keys are in your keychain; the target is in frontera.yaml (sync.targets).' : 'Keys are in your keychain; the link is in frontera.yaml.',
       ...(profile ? [`A change request's steps for a person reach this platform with \`--profile ${profile}\`, not the local runtime.`] : []),
       ...(signIn ? [`Change requests you apply, and the steps they leave, act as you: sign in first with \`${signIn}\`.`] : []),
       ...(profileError ? [`No CLI profile was recorded for this platform (${profileError}); a change request's steps for a person name none until one is.`] : []),
-      'See what you can pull: `frontera local sync pull --preview`.',
+      name ? `See what would be proposed to it: \`frontera local sync push --preview --target ${name}\`.` : 'See what you can pull: `frontera local sync pull --preview`.',
     ].join('\n'),
   }
 }
@@ -505,7 +662,37 @@ const status = async (ctx: CommandContext) => {
   const lock = readLock(project.root)
   const lastPull = lock && link && lock.workspace === link.workspace ? lock.pulledAt ?? null : null
   const none = { fetchedAt: null, platform: null, incoming: 0, nowNamed: 0, newInWorkspace: 0, changedHere: 0, bothChanged: 0, mergeable: 0, conflicts: 0, unresolved: 0, clearedByWorkspace: 0, deletedInWorkspace: 0, deletedHere: 0, onlyHere: 0 }
-  if (!link) return { data: { link: null, keys, lastPull: null, counts: null, error: null, ...none }, text: 'Not linked to a workspace. Connect one with `frontera local sync connect --platform <url>`.' }
+  const requestLine = (r: ReturnType<typeof currentRequest>) => (r ? `${r.state === 'merged' ? 'Applied' : r.applied && !r.applied.ok && r.state !== 'closed' ? 'Apply failed' : r.state === 'closed' ? 'Closed' : 'Proposed'} · ${plural(r.refs.length, 'item')} · ${r.title}` : null)
+  // The named targets: where each is, whether this machine has its keys and who is signed in for it, and its own change request.
+  const targets = await Promise.all(projectTargets(project).filter((t) => t.name).map(async (t) => {
+    const keys = { workspace: !!getSyncKey(t.owner, 'workspace'), organization: !!getSyncKey(t.owner, 'organization') }
+    const person = await targetSession(t.owner, t.link)
+    // A sign-in goes on the profile `connect` made where the keys were checked: none for an entry moved since.
+    const checked = keysCheckedAt(t.owner)
+    const here = keys.workspace && checked?.platform === t.link.platform && checked.workspace === t.link.workspace
+    return {
+      name: t.name!,
+      workspace: t.link.workspaceName ?? t.link.workspace,
+      platform: t.link.platform,
+      production: t.production,
+      keys,
+      signedIn: person ? { email: person.email ?? null, until: person.expiresAt } : null,
+      signIn: person || !here ? null : await signInStep({ profile: targetProfileName(t.owner, t.link), apiUrl: t.link.platform, named: true }),
+      request: requestLine(currentRequest(readRequests(t.state, t.link.workspace))),
+    }
+  }))
+  const targetsLeftOut = leftOutTargets(project.root)
+  const signedInWords = (t: (typeof targets)[number]) => (t.signedIn ? `, signed in as ${t.signedIn.email ?? 'you'}` : t.signIn ? `, not signed in (\`${t.signIn}\`)` : '')
+  const targetLines = [
+    ...targets.map((t) => `  Target      ${t.name}${t.production ? ' (production)' : ''}: ${t.workspace} on ${new URL(t.platform).host}, ${t.keys.workspace ? 'keys stored' : 'no keys here'}${signedInWords(t)}${t.request ? ` · ${t.request}` : ''}`),
+    ...targetsLeftOut.map((t) => `  Target      ${t.name}: left out, ${t.problem}`),
+  ]
+  if (!link) {
+    return {
+      data: { link: null, keys, lastPull: null, counts: null, error: null, ...none, targets, targetsLeftOut },
+      text: targetLines.length ? ['Not linked to a workspace: nothing is pulled. Connect one with `frontera local sync connect --platform <url>`.', ...targetLines].join('\n') : 'Not linked to a workspace. Connect one with `frontera local sync connect --platform <url>`.',
+    }
+  }
   let error: string | null = null
   let snapshot = snapshotFor(project, link)
   // `--fetch` asks the platform first; `--offline` is the default now and kept for older callers.
@@ -549,9 +736,9 @@ const status = async (ctx: CommandContext) => {
   // How the last `local dev` left the project, counted as Forge's home counts it.
   const build = projectBuildSummary(project.root, project.id)
   const mcp = mcpServersNotCarried(project.root)
-  const request = kept ? `${kept.state === 'merged' ? 'Applied' : kept.applied && !kept.applied.ok && kept.state !== 'closed' ? 'Apply failed' : kept.state === 'closed' ? 'Closed' : 'Proposed'} · ${plural(kept.refs.length, 'item')} · ${kept.title}` : null
+  const request = requestLine(kept)
   return {
-    data: { link, keys, signedIn: person ? { email: person.email ?? null, until: person.expiresAt } : null, signIn, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build, notCarried: mcp ? { mcpServers: mcp.files, save: mcp.command } : null },
+    data: { link, keys, signedIn: person ? { email: person.email ?? null, until: person.expiresAt } : null, signIn, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build, notCarried: mcp ? { mcpServers: mcp.files, save: mcp.command } : null, targets, targetsLeftOut },
     text: [
       `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(link.platform).host}`,
       `  Last pull   ${lastPull ? when(lastPull) : 'never'}`,
@@ -565,6 +752,7 @@ const status = async (ctx: CommandContext) => {
       ...(build ? [`  Build       ${buildStatusText(build)}`] : []),
       ...(organizationKeyFor ? [`  Actions     this workspace’s workflows use governed Actions: ${signIn ? `sign in with \`${signIn}\`` : 'connect this computer, then sign in,'} to bring them`] : []),
       ...(mcp ? [`  MCP servers ${mcp.files.join(', ')}: not in a change request; save with \`${mcp.command}\``] : []),
+      ...targetLines,
     ].join('\n'),
   }
 }
@@ -840,16 +1028,20 @@ export function wontRunLocally(root: string, items: ReadonlyArray<Pick<RemoteIte
 }
 
 /** Everything about one item for `diff` and `resolve`: the plan row, the workspace's version, and the three-way merge. */
-async function itemState(project: LocalProject, link: SyncLink, ref: string) {
-  // Offline, as diff and resolve are: a lost base comes back only from an unchanged copy here (pull reads the platform).
-  const { remote, plan, lock, snapshot } = await planFor(project, link, { fetch: 'never', repair: 'offline' })
+async function itemState(project: LocalProject, target: SyncTarget, ref: string) {
+  const { link } = target
+  // Offline for the link, as diff and resolve are: a lost base comes back only from an unchanged copy here (pull
+  // reads the platform). A named target is read as a push to it reads it, against what this project delivered.
+  const { remote, plan, lock, snapshot, base: readBaseOf } = target.name
+    ? await targetPlan(project, target)
+    : { ...(await planFor(project, link, { fetch: 'never', repair: 'offline' })), base: (p: string) => readBase(project.root, p) }
   if (!plan || !snapshot) throw new CliError('nothing fetched from the workspace yet', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch`' })
   const row = plan.find((p) => p.ref === ref)
   const item = remote.items.find((i) => i.ref === ref) ?? null
   const entry = lock?.workspace === link.workspace ? lock.items[ref] : undefined
-  if (!row && !item && !entry) throw new UsageError(`not in the workspace or the project: ${ref}`, 'list items with `frontera local sync pull --preview`')
+  if (!row && !item && !entry) throw new UsageError(`not in the workspace or the project: ${ref}`, target.name ? `list what would go to it with \`${targetWords(target, 'frontera local sync push --preview')}\`` : 'list items with `frontera local sync pull --preview`')
   const paths = [...new Set([...Object.keys(item?.files ?? {}), ...Object.keys(entry?.files ?? {}), ...(entry?.conflict?.files ?? [])])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
-  const base = baseFiles(entry, (p) => readBase(project.root, p))
+  const base = baseFiles(entry, readBaseOf)
   const local = localFiles(project.root, paths)
   const theirs = item?.files ?? {}
   return { row, item, lock, snapshot, paths, base, local, theirs, entry }
@@ -886,10 +1078,10 @@ function conflictText(c: Conflict): string[] {
 
 const diff = async (ctx: CommandContext) => {
   const project = localProject(ctx.cwd)
-  const link = needLink(project)
+  const target = chooseTarget(project, ctx)
   const ref = ctx.positional[1]
   if (!ref) throw new UsageError('name the item', 'frontera local sync diff agent/support-concierge')
-  const s = await itemState(project, link, ref)
+  const s = await itemState(project, target, ref)
   const result = mergeItemFiles(s.base, s.local, s.theirs)
   const files = result.files.map((f) => {
     const base = s.base[f.path] ?? null
@@ -908,7 +1100,9 @@ const diff = async (ctx: CommandContext) => {
         `  ${f.path}: ${f.conflicts.length ? plural(f.conflicts.length, 'conflict') : WORD[f.state]}`,
         ...f.conflicts.flatMap(conflictText),
       ]),
-      ...(result.conflicts
+      ...(result.conflicts && target.name
+        ? ['', `Keep the project’s version with \`${targetWords(target, `frontera local sync resolve ${ref} --keep mine`)}\`; to keep ${target.link.workspaceName ?? target.name}’s change too, carry it into the files here, then \`${targetWords(target, `frontera local sync resolve ${ref} --edited`)}\`.`]
+        : result.conflicts
         ? [
             '',
             `Settle with \`frontera local sync resolve ${ref} --keep workspace|mine\` (or \`--picks 1=workspace,2=mine\`), or edit and \`--edited\`.`,
@@ -921,10 +1115,12 @@ const diff = async (ctx: CommandContext) => {
 
 const resolve = async (ctx: CommandContext) => {
   const project = localProject(ctx.cwd)
-  const link = needLink(project)
+  const target = chooseTarget(project, ctx)
+  const { link } = target
   const ref = ctx.positional[1]
   if (!ref) throw new UsageError('name the item', 'frontera local sync resolve agent/support-concierge --keep workspace')
-  const s = await itemState(project, link, ref)
+  if (target.name) return resolveForTarget(project, target, ref, ctx)
+  const s = await itemState(project, target, ref)
   // Picks are by number: they apply only to the conflicts they were chosen for (`conflictsId` from
   // `diff`). Checked first, so a conflict a workspace change cleared reads as stale, not as an error.
   const chosenFor = flagString(ctx, 'conflicts')
@@ -963,8 +1159,58 @@ const resolve = async (ctx: CommandContext) => {
   }
 }
 
+/**
+ * A named target is never pulled from, so an item it changed since this
+ * project delivered it is settled one way: the project's files are kept, and
+ * the next push proposes them over what the target holds now. Its base for
+ * the item is forgotten, so the push compares with the target's version.
+ */
+async function resolveForTarget(project: LocalProject, target: SyncTarget, ref: string, ctx: CommandContext) {
+  const keep = flagString(ctx, 'keep')
+  const edited = flagBool(ctx, 'edited')
+  const label = targetLabel(target)
+  if ((keep !== undefined && keep !== 'mine') || flagString(ctx, 'picks') !== undefined) {
+    throw new UsageError('a target is never pulled from: resolve keeps the project’s files', `\`${targetWords(target, `frontera local sync resolve ${ref} --keep mine`)}\` proposes them over what it holds; to keep its change too, carry it into the files here, then \`--edited\``)
+  }
+  if (!keep && !edited) throw new UsageError('say how to resolve it', `\`--keep mine\`, or \`--edited\` once the files here carry what to keep of ${label}’s change`)
+  const s = await itemState(project, target, ref)
+  if (!s.row || (s.row.status !== 'conflict' && s.row.status !== 'changed' && s.row.status !== 'deleted-remote')) {
+    throw new UsageError(`nothing to resolve in ${ref} for ${label}: ${s.row ? statusWord(s.row) : 'it holds no such item'}`, 'resolve with --target settles an item the target changed since this project last delivered it')
+  }
+  const delivered = readLock(target.state)
+  if (delivered?.items[ref]) {
+    const { [ref]: _forgotten, ...items } = delivered.items
+    writeLock(target.state, { ...delivered, items })
+  }
+  return {
+    data: { ref, target: target.name, resolved: true, written: [], removed: [] },
+    text: `Resolved ${ref} for ${label}: the project’s files are kept, and the next push to it ${s.row.status === 'deleted-remote' ? 'proposes it again, as new' : 'proposes them over what it holds now'}.`,
+  }
+}
+
 const disconnect = async (ctx: CommandContext) => {
   const project = localProject(ctx.cwd)
+  const name = flagString(ctx, 'target')
+  if (name !== undefined) {
+    // Not `chooseTarget`: a target whose entry now points elsewhere, or that the CLI leaves out, still has its keys removed here.
+    if (!TARGET_NAME.test(name) || !leftOutTargets(project.root).some((t) => t.name === name)) findTarget(project, ctx)
+    const owner = targetOwner(project, name)
+    // The profile made where its keys were checked: first, while those keys still show it is the project's.
+    const checked = keysCheckedAt(owner)
+    if (checked) await removeTargetProfile(owner, checked)
+    removeSyncKey(owner, 'workspace')
+    removeSyncKey(owner, 'organization')
+    setKeysCheckedAt(owner, null)
+    const forget = flagBool(ctx, 'forget-link')
+    if (forget) {
+      writeTarget(project.root, name, null)
+      rmSync(targetState(project, name), { recursive: true, force: true })
+    }
+    return {
+      data: { target: name, keysRemoved: true, linkRemoved: forget },
+      text: forget ? `Removed target ${name}: its keys, and its entry in frontera.yaml.` : `Removed target ${name}’s keys from this machine. It stays in frontera.yaml for your teammates; \`--forget-link\` removes it too.`,
+    }
+  }
   const link = readLink(project.root)
   // First, while the keys that show the profile is the project's are still stored.
   if (link) await removeTargetProfile(project, link)
@@ -992,6 +1238,14 @@ const SUBCOMMANDS: Record<string, (ctx: CommandContext) => Promise<{ data: unkno
   'map-model': (ctx) => syncMapModel(ctx),
 }
 
+/** Subcommands that take no `--target`, and why: a target is only delivered to. */
+const NO_TARGET: Record<string, (name: string) => [string, string]> = {
+  fetch: (name) => ['`fetch` reads the project’s link: a target is never pulled from', `see what would go to it with \`frontera local sync push --preview --target ${name}\``],
+  pull: (name) => ['`pull` reads the project’s link: a target is never pulled from', `see what would go to it with \`frontera local sync push --preview --target ${name}\``],
+  status: () => ['`status` lists every target already', '`frontera local sync status`'],
+  'map-model': () => ['a model mapping is the project’s, for its link and every target', '`frontera local sync map-model <local model> <workspace model>`'],
+}
+
 export const localSync: Command = {
   meta: {
     noun: 'local',
@@ -1002,6 +1256,8 @@ export const localSync: Command = {
     ],
     flags: {
       platform: 'string',
+      target: 'string',
+      production: 'boolean',
       'workspace-key': 'string',
       'org-key': 'string',
       blueprint: 'string',
@@ -1041,9 +1297,10 @@ export const localSync: Command = {
       remove: 'boolean',
     },
     aliases: { t: 'title', d: 'description' },
-    summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back',
+    summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back, to the link or to a named target',
     examples: [
       'frontera local sync connect --platform $URL --workspace-key -',
+      'frontera local sync connect --target prod --production --platform $URL',
       'frontera local sync fetch',
       'frontera local sync status',
       'frontera local sync status --fetch',
@@ -1068,10 +1325,14 @@ export const localSync: Command = {
       'frontera local sync request evidence --evals --renders',
       'frontera local sync request apply',
       'frontera local sync request apply --force --reason "hotfix, checked by hand"',
+      'frontera local sync push --preview --target prod',
+      'frontera local sync push -t "Customer segments" --target prod',
+      'frontera local sync request apply --target prod',
       'frontera local sync request close',
       'frontera local sync map-model llama-4-70b claude-haiku-5-5',
       'frontera local sync map-model llama-4-70b --remove',
       'frontera local sync disconnect --forget-link',
+      'frontera local sync disconnect --target prod --forget-link',
     ],
     offline: true,
   },
@@ -1080,6 +1341,9 @@ export const localSync: Command = {
     const run = action ? SUBCOMMANDS[action] : undefined
     const named = action ? `\`${action}\`` : '(none given)'
     if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request, map-model or disconnect')
+    const target = flagString(ctx, 'target')
+    const refused = target !== undefined ? NO_TARGET[action!]?.(TARGET_NAME.test(target) ? target : '<name>') : undefined
+    if (refused) throw new UsageError(refused[0], refused[1])
     return run(ctx)
   },
 }

package/src/commands/registry.ts

@@ -40,6 +40,7 @@ import { knowledgeCommands } from './knowledge/index-commands'
 import { mediaCommands } from './media/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
+import { voiceCommands } from './voice/index-commands'
 import { chatAppCommands } from './chat-app/index-commands'
 import { mcpServerCommands } from './mcp-server/index-commands'
 import { markingCommands } from './marking/index-commands'
@@ -133,6 +134,7 @@ export const COMMANDS: readonly Command[] = [
   ...mediaCommands,
   ...packCommands,
   ...secretCommands,
+  ...voiceCommands,
   ...chatAppCommands,
   ...mcpServerCommands,
   ...automationCommands,
@@ -211,6 +213,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   knowledge: 'Knowledge bases and the sources inside them',
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
+  voice: 'Voice — Agent phone numbers and outbound calls',
   'chat-app': 'Chat Apps — stage, publish and open an Agent roster',
   'mcp-server': 'Workspace MCP servers — save, list, inspect and archive',
   function: 'Functions — TypeScript deployed here, run on a schedule',
@@ -258,8 +261,8 @@ const KEYS_ARE_SETTINGS_ONLY =
  */
 export const UNSUPPORTED: Readonly<Record<string, string>> = {
   channel:
-    'channels have no CLI surface — create one and bind it to an agent in the Console, '
-    + 'under the agent’s Channels tab',
+    'channels have no CLI surface — create one and bind it to an agent in Studio on the platform, '
+    + 'on the agent’s Channels page',
   key: KEYS_ARE_SETTINGS_ONLY,
   // The names a caller reaches for when the goal is provisioning or rotating an
   // organization key. The service routes are session-only by construction, so