@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-agent-grants.ts

@@ -5,14 +5,20 @@ import type { LocalCredentials } from './local-state'
  * An Agent's Context and data on the local runtime: the object types it may
  * read through its Blueprint tools, from the `blueprint` list in its
  * `agents/<slug>/bindings.json` (`{ "objectType": "objectType/Incident",
- * "permissions": ["read"] }`). On the platform these are the Agent's
+ * "permissions": ["read"] }`), and the types it may submit governed Actions
+ * on (`"act"`, which implies read). On the platform these are the Agent's
  * Blueprint grants; without them it has no Blueprint tools at all.
  *
  * Granting is a Steward's call on the organization's Blueprint, so it is made
  * with the runtime's organization key, after the Blueprint is applied and
  * published (bindings apply after it). The runtime ends up with the file's
  * grants: missing ones are granted, changed permissions replaced, and grants
- * the file does not list revoked. An object type the runtime leaves off
+ * the file does not list revoked. An entry that names no `permissions` (and
+ * every grant assumed when the pull couldn't read them, `keepHeld`) is read
+ * plus what the runtime's grant already holds, so `act` or `read_sensitive`
+ * is taken away only by a file that lists the type's permissions without it
+ * (for `act`, the grant is sent with `removePermissions`: a re-grant on the
+ * runtime otherwise keeps it). An object type the runtime leaves off
  * (media files) is skipped with a warning; one it does not hold yet waits
  * for the Blueprint to build, so the Agent's tools read as blocked on it.
  */
@@ -41,6 +47,8 @@ export async function applyAgentGrants(input: {
   leftOff: LeftOff
   /** Whether the project's Blueprint has a file for this object type. */
   inProject: (apiName: string) => boolean
+  /** Every grant keeps what the runtime's grant holds beyond read (the file's permissions are assumed, not read). */
+  keepHeld?: boolean
   fetch?: typeof fetch
 }): Promise<GrantOutcome> {
   const { slug, creds } = input
@@ -71,13 +79,17 @@ export async function applyAgentGrants(input: {
 
   // Wanted: by API name, the file's permissions (read when it names none).
   const wanted = new Map<string, string[]>()
+  // The types whose permissions the file doesn't state: read, plus what the runtime's grant holds.
+  const keep = new Set<string>()
   for (const g of input.grants) {
     const ref = typeof g?.objectType === 'string' ? parseRef(g.objectType) : null
     if (!ref || ref.kind !== 'objectType') {
       failures.push(`  ${String(g?.objectType)}: not an object type reference (objectType/<apiName>)`)
       continue
     }
-    wanted.set(ref.name, [...(Array.isArray(g.permissions) && g.permissions.length ? g.permissions : ['read'])].sort())
+    // `read` is implied by the others (`read_sensitive`, `act`), as the runtime stores the grant.
+    wanted.set(ref.name, [...new Set(['read', ...(Array.isArray(g.permissions) ? g.permissions : [])])].sort())
+    if (input.keepHeld || !Array.isArray(g.permissions)) keep.add(ref.name)
   }
 
   // The workspace's own list, which holds Agents never published too; the organization's
@@ -91,10 +103,15 @@ export async function applyAgentGrants(input: {
   const onRuntime = new Set(held.ok ? list<{ apiName?: string }>(held.data).flatMap((t) => (t.apiName ? [t.apiName] : [])) : [])
   const current = await call(creds.orgKey, `/v1/blueprint/grants/agent/${encodeURIComponent(agent.id)}`)
   if (!current.ok) return { failures: [...failures, `  agent/${slug}: its Blueprint access could not be read: ${brief(current)}`], notes }
-  const has = new Map(list<{ objectTypeApiName: string; permissions?: string[] }>(current.data).map((g) => [g.objectTypeApiName, [...(g.permissions ?? ['read'])].sort()]))
+  const has = new Map(list<{ objectTypeApiName: string; permissions?: string[] }>(current.data).map((g) => [g.objectTypeApiName, [...new Set(['read', ...(g.permissions ?? [])])].sort()]))
 
   let granted = 0
-  for (const [apiName, permissions] of wanted) {
+  const acting: string[] = []
+  const kept: string[] = []
+  for (const [apiName, stated] of wanted) {
+    const held = has.get(apiName) ?? []
+    const extras = keep.has(apiName) ? held.filter((p) => !stated.includes(p)) : []
+    const permissions = extras.length ? [...stated, ...extras].sort() : stated
     const why = input.leftOff(apiName)
     if (why) {
       notes.push(`  warning: Context and data: ${apiName} is left off here (${why}), so ${slug} can’t read it locally`)
@@ -106,13 +123,17 @@ export async function applyAgentGrants(input: {
       continue
     }
     if (has.get(apiName)?.join(',') !== permissions.join(',')) {
-      const res = await call(creds.orgKey, '/v1/blueprint/grants/agent', 'POST', { agentId: agent.id, objectTypeApiName: apiName, permissions })
+      // A re-grant keeps a held `act` unless it is named as removed, and here the file's list is the whole grant.
+      const removePermissions = held.includes('act') && !permissions.includes('act') ? ['act'] : []
+      const res = await call(creds.orgKey, '/v1/blueprint/grants/agent', 'POST', { agentId: agent.id, objectTypeApiName: apiName, permissions, ...(removePermissions.length ? { removePermissions } : {}) })
       if (!res.ok) {
         failures.push(`  objectType/${apiName}: ${brief(res)}`)
         continue
       }
     }
     granted += 1
+    if (extras.length) kept.push(`${extras.join(' and ')} on ${apiName}`)
+    if (permissions.includes('act')) acting.push(apiName)
   }
   // The file is what the Agent may read: a grant it does not list is withdrawn.
   for (const apiName of has.keys()) {
@@ -120,6 +141,7 @@ export async function applyAgentGrants(input: {
     const res = await call(creds.orgKey, `/v1/blueprint/grants/agent/${encodeURIComponent(agent.id)}/${encodeURIComponent(apiName)}`, 'DELETE')
     if (!res.ok) failures.push(`  objectType/${apiName}: could not be revoked: ${brief(res)}`)
   }
-  if (granted) notes.push(`  Context and data: ${granted} object type${granted === 1 ? '' : 's'}`)
+  if (granted) notes.push(`  Context and data: ${granted} object type${granted === 1 ? '' : 's'}${acting.length ? `; ${slug} can submit Actions on ${acting.sort().join(', ')} (act)` : ''}`)
+  if (kept.length) notes.push(`  Context and data: kept what ${slug}'s grants already held where its bindings.json names no permissions: ${kept.join('; ')}`)
   return { failures, notes }
 }

package/src/local/local-agent-lean-plugins.ts

@@ -0,0 +1,68 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { unchangedSincePull } from './local-check-inherited'
+
+/**
+ * Agents whose Plugins are not offered: an Agent with behavior set up
+ * (`agents/<slug>/operating.json`) and no computer runs on the lean profile,
+ * which leaves out the platform tools and `activate_capability`, so the
+ * Plugins its agent.json lists (`config.plugins`: artifacts, image, charts…)
+ * are never offered, here and on the platform alike. By design, but nothing
+ * in the apply says so: said as a warning on the Agent, with the fix.
+ *
+ * Only when all three hold: behavior exists, the Agent has no computer
+ * (`config.features.computerAvailability` is not `on-demand` or `eager`; an
+ * Agent with behavior and no setting of its own gets none), and Plugins are
+ * listed.
+ */
+
+export interface AgentLeanPlugins {
+  agent: string
+  plugins: string[]
+  /** agent.json and operating.json are as the last pull wrote them: the workspace's Agent is the same. */
+  inherited: boolean
+}
+
+/** The Computer availability values that give an Agent a computer (the service's `AGENT_COMPUTER_AVAILABILITY`, less `none`). */
+const WITH_COMPUTER = new Set(['on-demand', 'eager'])
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    const v = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+export function agentLeanPlugins(root: string): AgentLeanPlugins[] {
+  let slugs: string[] = []
+  try {
+    slugs = readdirSync(join(root, 'agents')).filter((n) => !n.startsWith('.')).sort()
+  } catch {
+    return []
+  }
+  const out: AgentLeanPlugins[] = []
+  let unchanged: ReturnType<typeof unchangedSincePull> | null = null
+  for (const slug of slugs) {
+    const operating = join(root, 'agents', slug, 'operating.json')
+    if (!existsSync(operating) || !readJson(operating)) continue
+    const agent = readJson(join(root, 'agents', slug, 'agent.json'))
+    const config = (agent?.config ?? null) as { plugins?: unknown; features?: { computerAvailability?: unknown } } | null
+    if (!config) continue
+    const plugins = Array.isArray(config.plugins) ? config.plugins.filter((p): p is string => typeof p === 'string' && !!p) : []
+    if (!plugins.length) continue
+    if (WITH_COMPUTER.has(String(config.features?.computerAvailability ?? ''))) continue
+    unchanged ??= unchangedSincePull(root)
+    out.push({ agent: slug, plugins, inherited: [`agents/${slug}/agent.json`, `agents/${slug}/operating.json`].every((f) => unchanged!.files.has(f)) })
+  }
+  return out
+}
+
+const list = (names: string[]) => (names.length <= 2 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`)
+
+/** One Agent in a line, with its fix: what `local dev`, `local status`, the MCP status and Forge's builds say. */
+export function agentLeanPluginsLine(g: AgentLeanPlugins): string {
+  return `agent/${g.agent}: its Plugins (${list(g.plugins)}) aren’t offered once behavior is set up (operating.json) without a computer, so it runs without them, here and on the platform. Fix: give it a computer ("computerAvailability": "on-demand" under config.features in agents/${g.agent}/agent.json), or remove the Plugins from agent.json${g.inherited ? ' (inherited: these files are as the pull wrote them, so the workspace’s Agent is the same)' : ''}`
+}

package/src/local/local-agent-missing-tools.ts

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ItemBuild } from './local-applied'
+
+/**
+ * An Agent whose tools didn't build: its `bindings.json` names Functions or
+ * workflows whose apply failed (or that wait on something), so the runtime
+ * gives it the rest and it runs without those. That is not an adaptation
+ * for local, it is a gap: said as a warning on the Agent's row, naming what
+ * failed, on every surface that lists it (`local status`, Forge's home and
+ * Activity, Studio's Agents page).
+ */
+
+export interface MissingTools {
+  agent: string
+  /** `function/dispatch-request`, `workflow/intake`: what it names that isn't on the runtime. */
+  refs: string[]
+}
+
+/** The tools an Agent's bindings name and enable: Functions and workflows, by reference. */
+function boundTools(root: string, slug: string): string[] {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, 'agents', slug, 'bindings.json'), 'utf8')) as { functions?: unknown; workflows?: unknown }
+    const refs: string[] = []
+    for (const list of [doc.functions, doc.workflows]) {
+      if (!Array.isArray(list)) continue
+      for (const b of list) {
+        if (!b || typeof b !== 'object' || (b as { enabled?: unknown }).enabled === false) continue
+        const ref = (b as { function?: unknown; workflow?: unknown }).function ?? (b as { workflow?: unknown }).workflow
+        if (typeof ref === 'string' && /^(function|workflow)\/[\w.-]+$/.test(ref)) refs.push(ref)
+      }
+    }
+    return refs
+  } catch {
+    return []
+  }
+}
+
+/** Each Agent whose bound Functions or workflows failed to apply (or wait on what they need), by its slug. */
+export function agentMissingTools(root: string, agents: string[], builds: Readonly<Record<string, ItemBuild>>): MissingTools[] {
+  const out: MissingTools[] = []
+  for (const agent of agents) {
+    const refs = [...new Set(boundTools(root, agent))].filter((ref) => {
+      const state = builds[ref]?.state
+      return state === 'failed' || state === 'blocked'
+    })
+    if (refs.length) out.push({ agent, refs: refs.sort() })
+  }
+  return out
+}
+
+const list = (names: string[]) => (names.length <= 1 ? (names[0] ?? '') : `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`)
+
+/** The warning on the Agent's row: "agent/nova: missing tools: … failed to apply, … Fix: …". */
+export function missingToolsLine(m: MissingTools): string {
+  const names = m.refs.map((r) => r.slice(r.indexOf('/') + 1))
+  const one = names.length === 1
+  const kinds = new Set(m.refs.map((r) => r.slice(0, r.indexOf('/'))))
+  const noun = kinds.size === 1 ? (kinds.has('function') ? 'Function' : 'workflow') : 'tool'
+  const what = one ? noun : `${noun}s`
+  return `agent/${m.agent}: missing tools: the ${what} ${list(names)} failed to apply, so it runs without ${one ? 'it' : 'them'} here. Fix: fix ${one ? `that ${noun}` : `those ${what}`} (${one ? 'its' : 'each one’s'} row says why); the Agent gets ${one ? 'it' : 'them'} on the next apply after ${one ? 'it builds' : 'they build'}`
+}
+
+/** An adaptation the tools' apply recorded for the same gap ("nova goes without the Function x here until it builds"): said as the warning instead. */
+export function isMissingToolAdaptation(line: string): boolean {
+  return /\bgoes without the (Function|workflow) [\w.-]+ here until it builds\b/i.test(line)
+}

package/src/local/local-agent-name.ts

@@ -69,3 +69,30 @@ export async function syncAgentName(input: { slug: string; identity: AgentIdenti
     return `  warning: ${input.slug}'s name could not be set: ${(err as Error).message}`
   }
 }
+
+/**
+ * Whether the runtime holds a draft of this Agent: true or false, or null when
+ * it could not be told (no such Agent yet, the runtime did not answer). Its
+ * files may be unchanged since they were applied while the draft is gone (a
+ * publish turns the draft into the live version), and the Agent's test cases
+ * and Studio's Draft chat run the draft, so `local dev` stages it again.
+ */
+export async function hasAgentDraft(input: { slug: string; serviceUrl: string; creds: LocalCredentials; fetch?: typeof fetch }): Promise<boolean | null> {
+  const doFetch = input.fetch ?? fetch
+  const headers = { authorization: `Bearer ${input.creds.workspaceKey ?? ''}` }
+  try {
+    const found = await doFetch(new URL(`/v1/config/agents/${encodeURIComponent(input.slug)}`, input.serviceUrl), { headers })
+    if (!found.ok) return null
+    const row = (await found.json()) as { data?: { id?: string }; id?: string }
+    const id = row.data?.id ?? row.id
+    if (!id) return null
+    const res = await doFetch(new URL(`/v1/config/agents/${encodeURIComponent(id)}/draft-v2`, input.serviceUrl), { headers })
+    if (!res.ok) return null
+    // Wrapped twice: `ok({ data: … })` around the draft, which is null when nothing is staged.
+    const body = (await res.json()) as { data?: { data?: unknown } | null } | null
+    const inner = body?.data && typeof body.data === 'object' && 'data' in body.data ? body.data.data : body?.data
+    return inner !== null && inner !== undefined
+  } catch {
+    return null
+  }
+}

package/src/local/local-app-code.ts

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+import { CliError } from '../errors'
+import { healProject } from '../heal'
+import { writeState } from '../project'
+import { unpackTo } from '../untar'
+import { appPath } from './local-apps'
+import { vendoredShadows } from './local-app-sdk'
+import { appPulledAsIs, recordPulledFiles } from './local-app-pulled'
+import type { SyncClient } from './local-sync-client'
+
+/**
+ * A pulled Custom App's code, brought beside its file: the source of the
+ * version the workspace deployed, unpacked into `apps/<slug>/`, as
+ * `frontera app pull` does for a folder of its own. `local dev` then builds
+ * it like any App folder.
+ *
+ * Never over a folder that is there: an `apps/<slug>/` is the project's own
+ * code, edited or not. No `.env.local` is written: a dev host given the
+ * workspace's credential would read the workspace's records, and `app_dev`
+ * (or `frontera app dev`) points the App at the local runtime when it runs.
+ */
+/**
+ * Each `@frontera-sdk` package an App's package.json takes from the copy under
+ * src/frontera/ while its bun.lock installed a published release
+ * (`vendoredShadows`): a frozen install refuses that App until one of the two
+ * files changes.
+ */
+export type SdkShadow = { pkg: string; version: string }
+
+export type AppCodePulled =
+  | { slug: string; version: string; files: number; repairs: string[]; shadows?: SdkShadow[]; replaced?: SdkShadow[] }
+  | { slug: string; version: string; kept: true; shadows?: SdkShadow[] }
+  | { slug: string; version: string; missing: true }
+  | { slug: string; version: string; failed: string }
+
+/** The version an App's file names, else the pulled item's (`v1.4.0`). */
+export function appCodeVersion(root: string, slug: string, itemVersion?: string | null): string | null {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, appPath(slug)), 'utf8')) as { version?: unknown }
+    if (typeof doc.version === 'string' && doc.version) return doc.version
+  } catch {
+    // No file: the item's version, below.
+  }
+  return itemVersion ? itemVersion.replace(/^v/, '') : null
+}
+
+/**
+ * The SDK packages an App folder's package.json takes from the copy under
+ * src/frontera/ while its bun.lock installed a published release, when the
+ * folder is otherwise all as an earlier pull left it ([] when it isn't, or
+ * nothing disagrees). That is an older CLI's repair, not the person's work:
+ * before pull run 10 the pull vendored the CLI's SDK copy over the published
+ * range the workspace's source declared and left its bun.lock as it was, so
+ * the two disagree and a frozen install refuses the folder. A pull brings the
+ * deployed source again in its place. Read it before the pull writes its
+ * frontera.lock entry: an older pull's folder is told from that entry
+ * (`appPulledAsIs`).
+ */
+export function earlierPullShadows(root: string, slug: string): SdkShadow[] {
+  const dir = join(root, 'apps', slug)
+  if (!existsSync(dir)) return []
+  const shadows = vendoredShadows(dir)
+  return shadows.length && appPulledAsIs(root, join('apps', slug)) === true ? shadows : []
+}
+
+/** Unpack an App's source into `dir`, record its lineage, repair it, and record it as pulled. */
+function unpackPulled(dir: string, bytes: Uint8Array, app: { id: string; version: string }): { files: number; repairs: string[] } {
+  const files = unpackTo(dir, bytes)
+  // Its lineage: the workspace's App and the version this code is. Not a deployment from here
+  // (`parentVersion`), so status says it was pulled, not deployed; a deploy still names it as its parent.
+  writeState(dir, { pulledFrom: app.id, pulledVersion: app.version })
+  const { repairs } = healProject(dir)
+  // Its source as pulled (repairs included): `local check` counts a failure while it is still so as inherited.
+  recordPulledFiles(dir)
+  return { files, repairs }
+}
+
+/**
+ * `replaceEarlierPull`: the folder is there, as an earlier pull left it, with
+ * its package.json and bun.lock disagreeing (`earlierPullShadows`, read by the
+ * caller before the pull's frontera.lock entry changes). Its source is
+ * brought again and takes the folder's place, so the folder is the deployed
+ * code with the package.json and bun.lock the workspace deployed, which
+ * agree; the folder's own `.frontera/` (its state and render evidence) is
+ * kept. Without the flag a folder that is there is always kept.
+ */
+export async function pullAppCode(root: string, client: SyncClient, app: { slug: string; id: string; version: string; replaceEarlierPull?: boolean }): Promise<AppCodePulled> {
+  const dir = join(root, 'apps', app.slug)
+  const base = { slug: app.slug, version: app.version }
+  const replacing = existsSync(dir) ? (app.replaceEarlierPull ? vendoredShadows(dir) : []) : null
+  // The project's own code, kept; but a package.json and bun.lock that disagree (an earlier pull, before the
+  // pull went back to the release its bun.lock installed) are said now, with the fix, not at the first render.
+  if (replacing && !replacing.length) {
+    const shadows = vendoredShadows(dir)
+    return { ...base, kept: true, ...(shadows.length ? { shadows } : {}) }
+  }
+  let bytes: Uint8Array
+  try {
+    bytes = await client.getBytes(`/v1/platform-apps/${encodeURIComponent(app.id)}/versions/${encodeURIComponent(app.version)}/source`)
+  } catch (err) {
+    // The earlier pull's folder stays as it is, said with the fix that still applies.
+    if (replacing) return { ...base, kept: true, shadows: replacing }
+    if (err instanceof CliError && err.code === 'NOT_FOUND') return { ...base, missing: true }
+    return { ...base, failed: (err as Error).message.slice(0, 200) }
+  }
+  // Into a folder of its own first: the earlier pull's folder goes only once the source is unpacked and repaired.
+  const target = replacing ? join(root, 'apps', `.${app.slug}.pulling-${process.pid}-${Date.now()}`) : dir
+  try {
+    const { files, repairs } = unpackPulled(target, bytes, app)
+    if (replacing) {
+      // The folder's state (its local deployment, its render evidence) stays with it; the pull's lineage and record win.
+      const own = join(dir, '.frontera')
+      const pulledState = readFileSync(join(target, '.frontera', 'state.json'), 'utf8')
+      rmSync(join(target, '.frontera'), { recursive: true, force: true })
+      if (existsSync(own)) renameSync(own, join(target, '.frontera'))
+      writeState(target, JSON.parse(pulledState) as Parameters<typeof writeState>[1])
+      rmSync(dir, { recursive: true, force: true })
+      renameSync(target, dir)
+    }
+    // The repair prefers what the workspace stored: its bun.lock's published release over a copy package.json
+    // names. One it couldn't make leaves them disagreeing, said with the command that settles it.
+    const shadows = vendoredShadows(dir)
+    return { ...base, files, repairs, ...(shadows.length ? { shadows } : {}), ...(replacing ? { replaced: replacing } : {}) }
+  } catch (err) {
+    // A half-unpacked folder would read as the project's own code next time: it goes.
+    rmSync(target, { recursive: true, force: true })
+    if (replacing) return { ...base, kept: true, shadows: vendoredShadows(dir) }
+    return { ...base, failed: `its source could not be unpacked (${(err as Error).message.slice(0, 160)})` }
+  }
+}
+
+/**
+ * Why an App folder won't install as it is, and the command that settles it:
+ * its package.json names the SDK copy under src/frontera/ where its bun.lock
+ * installed a published release, the one its code was written against.
+ */
+export function sdkShadowLine(dir: string, shadows: readonly SdkShadow[], opts: { repull?: string } = {}): string {
+  const pkgs = shadows.map((s) => s.pkg).join(' and ')
+  const released = shadows.map((s) => `${s.pkg} ${s.version}`).join(' and ')
+  const why = `its package.json names the SDK copy under src/frontera/ for ${pkgs}, where its bun.lock installed the published ${released}, so an install from its lockfile refuses it`
+  // An earlier pull's folder, unchanged since: pulling it again brings the deployed source, whose two files agree.
+  if (opts.repull) return `${why}. An earlier pull left it so, and nothing in it has changed since: \`frontera local sync pull ${opts.repull}\` brings the deployed source again in its place, or \`frontera app sdk use-local --npm\` in ${dir} goes back to that release where it is, deleting the copy (review and commit either change)`
+  return `${why}: run \`frontera app sdk use-local --npm\` in ${dir} to go back to that release (review and commit the change)`
+}
+
+/**
+ * The pull that brings an App folder's deployed source back, when it is an
+ * earlier pull's folder still as that pull left it (`apps/<slug>/` of a
+ * project, `earlierPullShadows`): `app/<slug>`, else null.
+ */
+export function repullRefFor(appRoot: string): string | null {
+  const parent = dirname(appRoot)
+  if (basename(parent) !== 'apps') return null
+  const slug = basename(appRoot)
+  return earlierPullShadows(dirname(parent), slug).length ? `app/${slug}` : null
+}
+
+/**
+ * What an install from the App's own SDK copy did (`bun install --no-save`),
+ * for `app dev`, `app_render`/`app_dev` and `local check`: installed as its
+ * package.json says, the SDK from its copy under src/frontera/; bun.lock kept
+ * as pulled (it still records the published release) and package.json
+ * unchanged; and what brings the deployed source back.
+ */
+export function copyInstallLine(shadows: readonly SdkShadow[], summary: string, opts: { repull?: string | null } = {}): string {
+  const pkgs = shadows.map((s) => s.pkg).join(' and ')
+  const released = shadows.map((s) => `${s.pkg} ${s.version}`).join(' and ')
+  const back = opts.repull
+    ? `An earlier pull left package.json and bun.lock disagreeing: \`frontera local sync pull ${opts.repull}\` brings the deployed source back`
+    : '`frontera app sdk use-local --npm` in the App goes back to that release (it rewrites package.json and deletes the copy)'
+  return `installed its packages from the App’s own SDK copy under src/frontera/ for ${pkgs}, as its package.json says, with \`bun install --no-save\` (${summary}); bun.lock was kept as pulled (it records the published ${released}) and package.json is unchanged. ${back}`
+}
+
+/** One line per App, for the pull's text. */
+export function appCodeLine(p: AppCodePulled): string {
+  const shadows = 'shadows' in p ? p.shadows : undefined
+  const shadow = shadows?.length ? `; ${sdkShadowLine(`apps/${p.slug}`, shadows)}` : ''
+  if ('files' in p) {
+    // A repair back to the bun.lock's release means the workspace's source disagreed with itself: said as that.
+    const restored = p.repairs.some((r) => r.startsWith('restored '))
+    const instead = p.replaced?.length
+      ? `, in place of the folder an earlier pull left unchanged, whose package.json named the SDK copy under src/frontera/ for ${p.replaced.map((s) => s.pkg).join(' and ')} where its bun.lock installed the published ${p.replaced.map((s) => `${s.pkg} ${s.version}`).join(' and ')} (that copy is gone; its package.json and bun.lock are the workspace’s again; review the change before you commit)`
+      : ''
+    return `  ${p.slug}: version ${p.version} into apps/${p.slug}/ (${p.files} files${p.repairs.length ? `; ${restored ? 'the workspace’s source has package.json and bun.lock disagreeing, so it was repaired to what its bun.lock installed' : 'repaired legacy packaging'}: ${p.repairs.join('; ')}` : ''})${instead}${shadow}`
+  }
+  if ('kept' in p) return `  ${p.slug}: apps/${p.slug}/ is already here, so it was kept as it is${shadow}`
+  if ('missing' in p) return `  ${p.slug}: the platform holds no source for version ${p.version}; apps/${p.slug}.json is its description only`
+  return `  ${p.slug}: its code could not be brought (${p.failed}); \`frontera local sync pull app/${p.slug}\` tries again`
+}

package/src/local/local-app-dev-files.ts

@@ -0,0 +1,186 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * What an App's dev server writes into its folder, put back.
+ *
+ * `next dev` rewrites `next-env.d.ts` when it starts (Next 16 points it at
+ * `.next/dev/types/routes.d.ts` where `next build` wrote `.next/types/…`) and
+ * may reconfigure `tsconfig.json`. A pulled App tracks both, so a preview
+ * would leave them modified. `frontera app dev` (which `app_dev`,
+ * `app_render` and Forge start) puts each back once the server is ready, and
+ * again when it stops.
+ *
+ * Only files that are the project's, not the person's work in progress: a
+ * file git tracks, or one the pull recorded (`pulledFiles` in the App's
+ * `.frontera/state.json`), that the dev server changed. A change made while
+ * the server runs is put back only when it is what the dev server wrote (the
+ * content it wrote at startup, or for `next-env.d.ts` and build info, their
+ * generated form); anything else is left as it is, and named.
+ */
+
+/** A file as it was: its bytes and its times, for putting it back as if nothing had touched it. */
+export interface FileAsWas {
+  bytes: Buffer
+  atimeMs: number
+  mtimeMs: number
+}
+
+/** A file's bytes and times now; null when it can't be read. */
+export function fileAsWas(path: string): FileAsWas | null {
+  try {
+    const stat = statSync(path)
+    return { bytes: readFileSync(path), atimeMs: stat.atimeMs, mtimeMs: stat.mtimeMs }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Put a file back as it was, its modification time too. A file the tooling
+ * rewrote for a run and put back byte for byte is no change, and whether a
+ * render is fresh (`render-evidence.ts`) is read from the source's mtimes: a
+ * put-back with a new mtime made the last render stale although nothing in
+ * the App had changed. Returns whether the bytes had to be written (a file
+ * the tool rewrote with the same bytes only gets its time back).
+ */
+export function putBackAsWas(path: string, was: FileAsWas): boolean {
+  const now = existsSync(path) ? readFileSync(path) : null
+  const rewrite = !now || !now.equals(was.bytes)
+  if (rewrite) writeFileSync(path, was.bytes)
+  try {
+    if (rewrite || statSync(path).mtimeMs !== was.mtimeMs) utimesSync(path, was.atimeMs / 1000, was.mtimeMs / 1000)
+  } catch {
+    // The bytes are back; a time that can't be set only makes a render look stale.
+  }
+  return rewrite
+}
+
+/** Written by a framework's dev server or a typecheck into the App folder's top. */
+const isDevWritten = (name: string) => name === 'next-env.d.ts' || name === 'tsconfig.json' || name.endsWith('.tsbuildinfo')
+
+/** `next-env.d.ts` as Next writes it: references, an import of its route types, comments. Never a person's code. */
+export function isNextGenerated(name: string, text: string): boolean {
+  if (name.endsWith('.tsbuildinfo')) return true
+  if (name !== 'next-env.d.ts') return false
+  const lines = text.split('\n').map((l) => l.trim()).filter(Boolean)
+  return lines.length > 0 && lines.every((l) => /^\/\/\/ <reference (types|path)=".*" \/>$/.test(l) || /^import ["']\.\/\.next\/[^"']+["'];?$/.test(l) || l.startsWith('//'))
+}
+
+/** The names in `names` that git tracks in `dir`; none outside a repository. */
+function gitTracked(dir: string, names: string[]): Set<string> {
+  if (!names.length) return new Set()
+  const res = spawnSync('git', ['ls-files', '-z', '--', ...names], { cwd: dir, encoding: 'utf8' })
+  if (res.status !== 0 || res.error) return new Set()
+  return new Set(res.stdout.split('\0').filter(Boolean))
+}
+
+/** The files the pull recorded in the App folder (`pulledFiles`), by path in the folder. */
+function pulledRecorded(dir: string): Set<string> {
+  try {
+    const state = JSON.parse(readFileSync(join(dir, '.frontera', 'state.json'), 'utf8')) as { pulledFiles?: Record<string, string> }
+    return new Set(Object.keys(state.pulledFiles ?? {}))
+  } catch {
+    return new Set()
+  }
+}
+
+/** The App folder's files a dev server may write that are the project's: tracked by git, or recorded by the pull. */
+export function trackedDevWrittenFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  const present = readdirSync(dir).filter(isDevWritten).sort()
+  const tracked = gitTracked(dir, present)
+  const pulled = pulledRecorded(dir)
+  return present.filter((name) => tracked.has(name) || pulled.has(name))
+}
+
+export interface DevWrittenFiles {
+  /** The files watched, as they were before the dev server started. */
+  readonly watched: string[]
+  /** Once the server is ready: each it changed since it started, put back. The names put back. */
+  afterReady(): string[]
+  /** When it has stopped: each it changed again, put back; the names put back, and those changed otherwise (left). */
+  atStop(): { putBack: string[]; left: string[] }
+}
+
+/** Keep the App folder's tracked files a dev server writes as they were before it started (call before starting it). */
+export function keepDevWrittenFiles(dir: string): DevWrittenFiles {
+  const before = new Map<string, FileAsWas>()
+  for (const name of trackedDevWrittenFiles(dir)) {
+    const was = fileAsWas(join(dir, name))
+    // Unreadable: left as the server leaves it.
+    if (was) before.set(name, was)
+  }
+  // What the server wrote at startup: the same content again later is its doing too.
+  const wrote = new Map<string, Buffer>()
+  const read = (name: string) => {
+    try {
+      return readFileSync(join(dir, name))
+    } catch {
+      return null
+    }
+  }
+  const putBack = (name: string): boolean => {
+    try {
+      putBackAsWas(join(dir, name), before.get(name)!)
+      return true
+    } catch {
+      return false
+    }
+  }
+  // Rewritten with the same bytes: only its time goes back, and nothing is said.
+  const retime = (name: string) => {
+    try {
+      putBackAsWas(join(dir, name), before.get(name)!)
+    } catch {
+      // Only a render's freshness reads the time.
+    }
+  }
+  return {
+    watched: [...before.keys()],
+    afterReady() {
+      const back: string[] = []
+      for (const [name, was] of before) {
+        const now = read(name)
+        if (!now) continue
+        if (now.equals(was.bytes)) {
+          retime(name)
+          continue
+        }
+        wrote.set(name, now)
+        if (putBack(name)) back.push(name)
+      }
+      return back
+    },
+    atStop() {
+      const back: string[] = []
+      const left: string[] = []
+      for (const [name, was] of before) {
+        const now = read(name)
+        if (!now) continue
+        if (now.equals(was.bytes)) {
+          retime(name)
+          continue
+        }
+        const theServers = wrote.get(name)?.equals(now) || isNextGenerated(name, now.toString('utf8'))
+        if (theServers && putBack(name)) back.push(name)
+        else left.push(name)
+      }
+      return { putBack: back, left }
+    },
+  }
+}
+
+/** One line for what was put back, for the dev server's output (`[dev] …`), or null when nothing was. */
+export function putBackLine(names: string[], when: 'started' | 'stopped'): string | null {
+  if (!names.length) return null
+  const files = names.join(' and ')
+  return `put back ${files} as tracked: the dev server rewrote ${names.length === 1 ? 'it' : 'them'} ${when === 'started' ? 'when it started' : 'while it ran'}`
+}
+
+/** One line for tracked files changed while the server ran that weren't its doing, or null. */
+export function leftLine(names: string[]): string | null {
+  if (!names.length) return null
+  return `left ${names.join(' and ')} as ${names.length === 1 ? 'it is' : 'they are'}: changed while the dev server ran, not to what it writes (an edit of yours is never put back)`
+}