@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/commands/app/dev.ts

@@ -1,20 +1,29 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
 import { AppsApi } from '../../api/apps-api'
 import { PlatformApi } from '../../api/platform-api'
-import { createDevSessionBroker } from '../../dev-broker'
+import { createDevSessionBroker, freeLoopbackPort, isLoopbackPortFree } from '../../dev-broker'
 import { CliError, UsageError } from '../../errors'
+import { DEV_OWNER_ENV, enclosingSolution, forgetDevServer, registerDevServer, watchOwner } from '../../mcp/mcp-apps'
+import { ensureAppPackages } from '../../project-bootstrap'
 import { detectAppFramework } from '../../provenance'
 import { writeAppId } from '../../project'
+import { mintDevSession, writeDevSessionState } from '../../local/local-app-dev-session'
+import { keepDevWrittenFiles, leftLine, putBackLine } from '../../local/local-app-dev-files'
+import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
 import { requireProjectFrom } from './shared'
 import { flagBool, flagString, type Command } from '../types'
 
 const DEFAULT_PORT = 3000
 const READY_TIMEOUT_MS = 30_000
 
-function appPort(raw: string | undefined): number {
+/** The port `--port` asks for; 0 is any free one, picked when the server starts. */
+export function appPort(raw: string | undefined): number {
   if (raw === undefined) return DEFAULT_PORT
   const port = Number(raw)
-  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-    throw new UsageError('--port must be an integer from 1 to 65535', 'for example: frontera app dev --port 3210')
+  if (raw.trim() === '' || !Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new UsageError('--port must be an integer from 0 to 65535 (0: any free port)', 'for example: frontera app dev --port 3210, or --port 0')
   }
   return port
 }
@@ -55,6 +64,16 @@ function openBrowser(url: string): void {
   }
 }
 
+/** How often a dev server an MCP session or Forge started checks that its starter is still there. */
+const OWNER_POLL_MS = 5_000
+/** How long a stopping dev server is given to exit before what it wrote is put back anyway. */
+const STOP_WAIT_MS = 10_000
+
+function withoutOwner(env: NodeJS.ProcessEnv): Record<string, string> {
+  const { [DEV_OWNER_ENV]: _owner, ...rest } = env
+  return rest as Record<string, string>
+}
+
 export const appDev: Command = {
   meta: {
     noun: 'app',
@@ -62,18 +81,40 @@ export const appDev: Command = {
     args: [],
     flags: { port: 'string', 'no-open': 'boolean' },
     summary: 'Run an App locally with short-lived authenticated Blueprint access',
-    examples: ['frontera app dev', 'frontera app dev --port 3210 --no-open'],
+    examples: ['frontera app dev', 'frontera app dev --port 3210 --no-open', 'frontera app dev --port 0'],
     needsProject: true,
   },
 
   async run(ctx) {
     const project = requireProjectFrom(ctx)
-    const port = appPort(flagString(ctx, 'port'))
+    const asked = appPort(flagString(ctx, 'port'))
+    // `--port 0`: one free on every loopback, said with the URL below.
+    const port = asked === 0 ? await freeLoopbackPort() : asked
+    // The App binds 127.0.0.1; a process holding the port on ::1 or a wildcard would answer `localhost` instead.
+    if (asked !== 0 && !(await isLoopbackPortFree(port))) {
+      throw new CliError(`port ${port} is already in use`, {
+        code: 'VALIDATION_ERROR',
+        hint: `something listens on ${port} (on 127.0.0.1, ::1 or every address); stop it, or choose another: frontera app dev --port ${port + 1}`,
+      })
+    }
     const appOrigin = `http://127.0.0.1:${port}`
     const framework = detectAppFramework(project.root)
+    // A pulled App comes without its packages: installed first, and said, or its dev command isn't there (`next: command not found`).
+    if (!existsSync(join(project.root, 'node_modules'))) ctx.output.note('[dev] no node_modules here: installing the App\'s packages first (bun install)')
+    const installed = await ensureAppPackages(project.root)
+    if (installed?.lockMismatch) throw new CliError(`the App's packages weren't installed: ${installed.summary}`, { code: 'FAILURE', hint: 'bun.lock was left as it is; the message above says which file to change' })
+    if (installed && !installed.installed) {
+      // From its own SDK copy, the install that keeps package.json and bun.lock as pulled is the one to retry.
+      throw new CliError(`the App's packages could not be installed: ${installed.summary}`, { code: 'FAILURE', hint: installed.fromCopy ? 'run `bun install --no-save` in the App folder (it writes neither package.json nor bun.lock) and read its error' : 'run `bun install` in the App folder and read its error' })
+    }
+    if (installed) ctx.output.note(`[dev] ${installed.summary}`)
     const apps = new AppsApi(ctx.apiUrl, ctx.token)
     const app = await apps.ensureApp(project.slug, project.displayName, project.appId)
     writeAppId(project.root, app.id)
+    // The solution this App is in, if any: where status reads how this server's sessions fare.
+    const solution = enclosingSolution(project.root)
+    // The id sessions are minted for: a restore to a baseline from before the App existed takes it away.
+    let appId = app.id
 
     let broker: ReturnType<typeof createDevSessionBroker> | null = null
     if (framework === 'next') {
@@ -87,13 +128,26 @@ export const appDev: Command = {
       broker = createDevSessionBroker({
         appOrigin,
         loadSession: async () => {
-          const session = await apps.appToken(app.id)
+          const minted = await mintDevSession({
+            appId,
+            mint: (id) => apps.appToken(id),
+            // Gone from the runtime (`local snapshot restore`): registered again by its slug, as `app dev` started.
+            reRegister: async () => (await apps.ensureApp(project.slug, project.displayName, null)).id,
+            onReRegistered: (id) => {
+              if (id === appId) return
+              ctx.output.note(`[dev] the runtime no longer had ${app.slug} (a restore of its database?): registered it again as ${id}; \`frontera app deploy\` puts its code back`)
+              appId = id
+              writeAppId(project.root, id)
+            },
+            record: solution ? (state) => writeDevSessionState(solution.stateDir, project.slug, state) : undefined,
+          })
+          const session = minted.session
           return {
             init: {
               type: 'frontera:init',
               token: session.token,
               apiBaseUrl: ctx.apiUrl.replace(/\/+$/, ''),
-              appId: app.id,
+              appId: minted.appId,
               version: 'dev',
               orgId: identity.orgId,
               workspaceId: identity.workspaceId,
@@ -116,6 +170,13 @@ export const appDev: Command = {
 
     const targetUrl = framework === 'vite' ? `${appOrigin}/dev-host.html` : appOrigin
     ctx.output.note(`[dev] ${app.slug} at ${targetUrl}`)
+    // Installed as its bun.lock records while tsconfig.json still sends the SDK to the older copy under src/frontera/:
+    // the server runs with those paths set aside, so it serves the code against the release it was written for.
+    const aside = setAsideCopyPaths(project.root)
+    if (aside) ctx.output.note(`[dev] ${aside.line}`)
+    // The tracked files the dev server writes (`next dev` rewrites next-env.d.ts when it starts) go back as they
+    // were once it is ready, and again when it stops: a preview is not a change. Never a change of the person's.
+    const kept = keepDevWrittenFiles(project.root)
 
     let child: Bun.Subprocess
     try {
@@ -125,9 +186,10 @@ export const appDev: Command = {
           : ['bun', 'run', 'dev', '--', '--hostname', '127.0.0.1', '--port', String(port)],
         {
           cwd: project.root,
+          // The owner is this command's to watch, not the framework's: nothing under it inherits the lifetime.
           env: broker
-            ? { ...process.env, NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT: broker.endpoint }
-            : process.env,
+            ? { ...withoutOwner(process.env), NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT: broker.endpoint }
+            : withoutOwner(process.env),
           stdin: 'inherit',
           stdout: 'inherit',
           stderr: 'inherit',
@@ -135,6 +197,7 @@ export const appDev: Command = {
       )
     } catch (error) {
       broker?.server.stop(true)
+      aside?.restore()
       throw error
     }
 
@@ -148,10 +211,32 @@ export const appDev: Command = {
     const onSignal = () => stop()
     process.on('SIGINT', onSignal)
     process.on('SIGTERM', onSignal)
+    // Started by an MCP session (`app_dev`, `app_render`) or Forge (its Start): it stops when that process ends,
+    // however it ends, so a server an agent or Forge started never outlives it. The starter recorded the server itself.
+    const owner = Number(process.env[DEV_OWNER_ENV]) || null
+    const unwatch = owner
+      ? watchOwner(
+          owner,
+          () => {
+            ctx.output.note(`[dev] the process that started this server (pid ${owner}) ended, so the server stops`)
+            // The whole group this server leads (it was started detached): the framework's server under `bun run dev` too.
+            try {
+              process.kill(-process.pid, 'SIGTERM')
+            } catch {
+              stop()
+            }
+          },
+          OWNER_POLL_MS,
+        )
+      : null
 
     try {
       await waitForApp(targetUrl, child)
+      const back = putBackLine(kept.afterReady(), 'started')
+      if (back) ctx.output.note(`[dev] ${back}`)
       ctx.output.note(`[dev] ready: ${targetUrl}`)
+      // In a solution, say so where its agents look, so they render this server instead of starting another.
+      if (solution && !owner) registerDevServer(solution, { slug: project.slug, pid: process.pid, port, url: targetUrl, startedAt: new Date().toISOString(), log: 'the terminal running frontera app dev' })
       if (!flagBool(ctx, 'no-open')) openBrowser(targetUrl)
       const exitCode = await child.exited
       if (!stopped && exitCode !== 0) {
@@ -161,13 +246,20 @@ export const appDev: Command = {
         })
       }
       return {
-        data: { appId: app.id, origin: targetUrl, exitCode },
+        data: { appId, origin: targetUrl, exitCode },
         text: `Stopped ${app.slug} local development server.`,
       }
     } finally {
+      unwatch?.()
       process.off('SIGINT', onSignal)
       process.off('SIGTERM', onSignal)
+      if (solution) forgetDevServer(solution, project.slug, process.pid)
       stop()
+      // Once the framework's server has exited (or after a while, whatever it does), what it wrote goes back.
+      await Promise.race([child.exited, Bun.sleep(STOP_WAIT_MS)])
+      const { putBack, left } = kept.atStop()
+      for (const line of [putBackLine(putBack, 'stopped'), leftLine(left)]) if (line) ctx.output.note(`[dev] ${line}`)
+      if (aside) ctx.output.note(`[dev] ${aside.restore()}`)
     }
   },
 }

package/src/commands/app/init.ts

@@ -13,6 +13,8 @@ import { BASELINE_COMPONENTS, addShadcnComponents, shadcnAddCommand } from '../.
 import { scaffold, scaffoldFiles, type AppFramework } from '../../template'
 import { writeHarnessFiles } from '../../harness'
 import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
+import { checkoutSdkFor, LOCAL_SDK_DIR, useCheckoutSdk } from '../../local/local-app-sdk'
+import { findSolutionRoot, PROJECT_FILES } from '../../local/local-project'
 import { flagBool, flagString, type Command, type CommandContext, type CommandResult } from '../types'
 
 /**
@@ -122,6 +124,21 @@ async function adoptExistingProject(ctx: CommandContext, root: string): Promise<
   }
 }
 
+/**
+ * Where `frontera app init <name>` puts a new App: inside a Frontera
+ * solution (a folder with `frontera.yaml` at or above it), its `apps/`
+ * folder, where `local dev`, `local check` and the MCP tools find Apps; any
+ * other folder, beside where it runs. `--dir` always wins, and an existing
+ * project named here is adopted where it is.
+ */
+export function appParentDir(cwd: string, name: string, dir: string | undefined): { base: string; inSolution: string | null } {
+  if (dir) return { base: dir, inSolution: null }
+  if (existsSync(join(cwd, name, 'package.json'))) return { base: cwd, inSolution: null }
+  const root = findSolutionRoot(cwd)
+  if (!PROJECT_FILES.some((f) => existsSync(join(root, f)))) return { base: cwd, inSolution: null }
+  return { base: join(root, 'apps'), inSolution: root }
+}
+
 export const appInit: Command = {
   meta: {
     noun: 'app',
@@ -154,7 +171,8 @@ export const appInit: Command = {
 
   async run(ctx) {
     const name = ctx.positional[0]
-    const base = flagString(ctx, 'dir') ?? ctx.cwd
+    const placed = name ? appParentDir(ctx.cwd, name, flagString(ctx, 'dir')) : { base: flagString(ctx, 'dir') ?? ctx.cwd, inSolution: null }
+    const base = placed.base
 
     /**
      * Which of the two jobs this is, decided the way `shadcn init` decides it:
@@ -179,7 +197,8 @@ export const appInit: Command = {
       throw new UsageError('unsupported framework', 'use --framework next or --framework react')
     }
     const framework: AppFramework = (requested as AppFramework | undefined) ?? 'next'
-    const target = resolve(join(flagString(ctx, 'dir') ?? ctx.cwd, name))
+    const target = resolve(join(base, name))
+    if (placed.inSolution) ctx.output.note(`  in the solution at ${placed.inSolution}: the App goes under apps/`)
 
     // Both checks precede the first write. A scaffold that fails halfway is
     // worse than one that never started, because the caller cannot tell which
@@ -236,6 +255,20 @@ export const appInit: Command = {
       ctx.output.note('')
     }
 
+    // A local runtime that runs from a platform checkout has that checkout's SDK, which can be ahead of
+    // every npm release: the App installs the checkout's packages (`frontera app sdk use-local`).
+    const checkout = framework === 'next' ? checkoutSdkFor(target) : null
+    if (checkout) {
+      try {
+        const used = useCheckoutSdk(target, checkout)
+        ctx.output.note(`  SDK source  the platform checkout the local runtime runs from (${checkout.version}): ${used.packages.map((p) => p.pkg).join(', ')} packed into ${LOCAL_SDK_DIR}/`)
+        ctx.output.note('              `frontera app sdk use-local --npm` switches to the published packages')
+      } catch (err) {
+        ctx.output.note(`  SDK source  npm: the checkout's SDK could not be packed (${(err as Error).message}); \`frontera app sdk use-local\` tries again`)
+      }
+      ctx.output.note('')
+    }
+
     let installed = false
     if (!flagBool(ctx, 'no-install')) {
       const result = await ctx.output.task('Installing dependencies with bun', () =>
@@ -289,7 +322,7 @@ export const appInit: Command = {
       ...(framework === 'react'
         ? ['  bun run dev', '  bun run typecheck', '  bun run build']
         : ['  frontera app dev', '  bun run check']),
-      '  frontera app deploy --no-promote',
+      '  frontera app deploy',
     ]
 
     return {

package/src/commands/app/promote.ts

@@ -1,36 +1,62 @@
 import { AppsApi } from '../../api/apps-api'
-import { UsageError } from '../../errors'
+import { CliError, UsageError } from '../../errors'
 import { projectApp, requireProjectFrom } from './shared'
-import type { Command } from '../types'
+import { flagBool, flagString, type Command } from '../types'
 
+/**
+ * Point production at an existing deployment. No rebuild: the reviewed
+ * artifact is what goes live. Required checks hold it; `--force` skips them
+ * with a reason, audited. A pinned production refuses until the rollback is
+ * undone or the pin lifted.
+ */
 export const appPromote: Command = {
   meta: {
     noun: 'app',
     verb: 'promote',
-    args: [{
-      name: 'version',
-      required: true,
-      description: 'version to make live, from `frontera app versions`',
-      producer: 'frontera app versions — then `frontera app promote <version>`',
-    }],
-    flags: {},
-    summary: 'Move the live pointer to an already-published version',
-    examples: ['frontera app promote 1.4.0'],
+    args: [
+      {
+        name: 'deployment',
+        required: true,
+        description: 'the deployment id or release label, from `frontera app deployments`',
+        producer: 'frontera app deployments — then `frontera app promote <deployment>`',
+      },
+    ],
+    flags: { force: 'boolean', reason: 'string' },
+    summary: 'Point production at an existing deployment, once its required checks pass',
+    examples: ['frontera app promote dpl_01j…', 'frontera app promote 1.4.0', 'frontera app promote 1.4.0 --force --reason "hotfix for the outage"'],
     needsProject: true,
   },
 
   async run(ctx) {
-    const version = ctx.positional[0]
-    if (!version) throw new UsageError('missing <version>', 'frontera app promote <version>')
-
+    const deployment = ctx.positional[0]
+    if (!deployment) throw new UsageError('missing <deployment>', 'frontera app promote <deployment>')
+    const force = flagBool(ctx, 'force')
+    const reason = flagString(ctx, 'reason')
+    if (force && !reason?.trim()) throw new UsageError('--force needs --reason', 'frontera app promote <deployment> --force --reason "why the checks can wait"')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
     const app = await projectApp(client, project)
-    const res = await client.deploy(app.id, version)
-
-    return {
-      data: { app: app.slug, appId: app.id, deployedVersion: res.deployedVersion },
-      text: `Promoted ${app.slug}@${res.deployedVersion}`,
+    try {
+      const res = await client.promote(app.id, { deployment, ...(force ? { force: true, reason } : {}) })
+      const name = res.label ?? res.promoted
+      return {
+        data: { app: app.slug, appId: app.id, ...res },
+        text: `Promoted ${app.slug}@${name}${res.forced.length ? ` (skipped required checks: ${res.forced.join(', ')})` : ''}${res.liveUrl ? `\n\nLive at ${res.liveUrl}` : ''}`,
+      }
+    } catch (err) {
+      const details = (err as { details?: { code?: string; checks?: Array<{ label: string; detail: string; required: boolean; status: string }> } }).details
+      if (details?.code === 'CHECKS_FAILED') {
+        const blocking = (details.checks ?? []).filter((c) => c.required && c.status !== 'passed')
+        throw new CliError(`${deployment} did not go live: required checks did not pass`, {
+          code: 'CONFLICT',
+          hint: `${blocking.map((c) => `${c.label} — ${c.detail}`).join('; ')}. Fix them and deploy again, or --force --reason "…"`,
+          details,
+        })
+      }
+      if (details?.code === 'PRODUCTION_PINNED') {
+        throw new CliError((err as Error).message, { code: 'CONFLICT', hint: 'frontera app rollback --undo returns to what served before the rollback; unpin on the App\'s Deployments keeps what serves now' })
+      }
+      throw err
     }
   },
 }

package/src/commands/app/pull.ts

@@ -94,7 +94,9 @@ export const appPull: Command = {
     }
 
     const count = unpackTo(dir, bytes)
-    writeState(dir, { appId: app.id, parentVersion })
+    // What was pulled, apart from a deployment from here: the folder is not read as deployed until `app deploy`,
+    // whose parent is this version (`readProject`). A deployment recorded before this pull no longer describes the tree.
+    writeState(dir, { appId: app.id, parentVersion: null, pulledFrom: app.id, pulledVersion: parentVersion })
 
     // Pull's contract is "give me a working copy", and a copy that cannot
     // `bun install` is not one. Apps stored by an older toolchain carry

package/src/commands/app/rollback.ts

@@ -0,0 +1,46 @@
+import { AppsApi } from '../../api/apps-api'
+import { UsageError } from '../../errors'
+import { projectApp, requireProjectFrom } from './shared'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * Point production at an earlier production deployment (the previous one
+ * when none is named) and pin it: nothing promotes until `--undo` or an
+ * audited Unpin, so the next routine deploy cannot replace the rollback.
+ */
+export const appRollback: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'rollback',
+    args: [{ name: 'deployment', required: false, description: 'an earlier production deployment (id or label); the previous one by default' }],
+    flags: { reason: 'string', undo: 'boolean' },
+    summary: 'Roll production back and pin it; --undo restores what served before',
+    examples: ['frontera app rollback --reason "checkout broke"', 'frontera app rollback 1.3.0 --reason "back to the last good release"', 'frontera app rollback --undo'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const undo = flagBool(ctx, 'undo')
+    const reason = flagString(ctx, 'reason')
+    if (!undo && !reason?.trim()) throw new UsageError('a rollback needs --reason', 'frontera app rollback --reason "what went wrong"')
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    if (undo) {
+      const res = await client.undoRollback(app.id)
+      return {
+        data: { app: app.slug, appId: app.id, ...res },
+        // A platform from before the undo refused a missing origin answers with nothing restored: say what happened.
+        text: res.restored
+          ? `Undid the rollback of ${app.slug}: production serves ${res.label ?? res.restored} again and is no longer pinned`
+          : `Lifted the pin on ${app.slug}, but nothing was restored: the deployment production served before the rollback is gone, so production still serves what it does now`,
+      }
+    }
+    const deployment = ctx.positional[0]
+    const res = await client.rollback(app.id, { ...(deployment ? { deployment } : {}), reason: reason! })
+    return {
+      data: { app: app.slug, appId: app.id, ...res },
+      text: `Rolled ${app.slug} back to ${res.label ?? res.to}${res.from ? ` from ${res.fromLabel ?? res.from}` : ''}. Production is pinned: new deployments won't go live until \`frontera app rollback --undo\` or an Unpin.`,
+    }
+  },
+}

package/src/commands/app/sdk.ts

@@ -1,26 +1,72 @@
-import { UsageError } from '../../errors'
+import { CliError, UsageError } from '../../errors'
+import { checkoutSdkFor, LOCAL_SDK_DIR, sdkSwitchChangeLines, useCheckoutSdk, useNpmSdk } from '../../local/local-app-sdk'
+import { installDependencies } from '../../project-bootstrap'
 import { syncVendoredAppSdk } from '../../sdk-sync'
 import { requireProjectFrom } from './shared'
-import type { Command } from '../types'
+import { flagBool, type Command } from '../types'
 
 export const appSdk: Command = {
   meta: {
     noun: 'app',
     verb: 'sdk',
-    args: [{ name: 'action', required: true, description: 'sync', producer: 'frontera app sdk sync' }],
-    flags: {},
-    summary: 'Refresh the generated SDK tree in a legacy vendored App',
-    examples: ['frontera app sdk sync'],
+    args: [{ name: 'action', required: true, description: 'sync | use-local', producer: 'frontera app sdk use-local' }],
+    flags: { npm: 'boolean' },
+    summary: 'Use the SDK of the platform checkout the local runtime runs from (use-local), or refresh a legacy vendored SDK (sync)',
+    details: [
+      `\`use-local\`: when the local runtime runs in source mode (a platform checkout), the App's @frontera-sdk packages are packed from that checkout into ${LOCAL_SDK_DIR}/ and package.json depends on them (\`file:./${LOCAL_SDK_DIR}/<tarball>\`, a relative path), then \`bun install\` runs. It writes package.json and a tarball per package in ${LOCAL_SDK_DIR}/, deletes an older tarball of the same package, and the install writes node_modules and updates bun.lock. Commit package.json, bun.lock and ${LOCAL_SDK_DIR}/: a clone, CI and \`app deploy\` build the same SDK. Run it again after the checkout's SDK changes.`,
+      `\`use-local --npm\`: back to the published packages, then \`bun install\` runs. Each @frontera-sdk dependency on a checkout tarball or on the SDK copy under src/frontera/ is set to the release the App's lockfile installed (\`^<that version>\`, and the lockfile's own record of the range is rewritten to match), else to the CLI's \`^<version>\`. It deletes ${LOCAL_SDK_DIR}/ and each SDK copy under src/frontera/ (src/frontera/core/, src/frontera/blueprint/, and src/frontera/ when that leaves it empty) with the tsconfig.json paths that point at them. A Vite App whose config aliases its copy keeps it. The output lists every file it changed or deleted: review them before you commit.`,
+      '`sync`: refreshes the SDK tree a legacy (Vite) App vendors under src/frontera/.',
+    ],
+    examples: ['frontera app sdk use-local', 'frontera app sdk use-local --npm', 'frontera app sdk sync'],
     needsProject: true,
+    // Local files and a local install: no credential.
+    offline: true,
   },
   async run(ctx) {
-    if (ctx.positional[0] !== 'sync') throw new UsageError('expected sync', 'frontera app sdk sync')
+    const action = ctx.positional[0]
     const project = requireProjectFrom(ctx)
+    if (action === 'use-local') {
+      const npm = flagBool(ctx, 'npm')
+      const checkout = npm ? null : checkoutSdkFor(project.root)
+      if (!npm && !checkout) {
+        throw new UsageError(
+          'the local runtime does not run from a platform checkout here, so there is no local SDK to use',
+          'source mode is set by `frontera local start --source <checkout>`; in image mode the App uses the published packages (`frontera app sdk use-local --npm`)',
+        )
+      }
+      let switched
+      try {
+        switched = npm ? useNpmSdk(project.root) : useCheckoutSdk(project.root, checkout!)
+      } catch (err) {
+        throw new CliError((err as Error).message, { code: 'FAILURE', hint: 'check that bun is on PATH and the checkout has packages/sdk-core and packages/sdk-blueprint' })
+      }
+      const install = await installDependencies(project.root)
+      if (!install.installed) throw new CliError(`package.json now names the ${npm ? 'published' : 'checkout'} SDK, but bun install failed: ${install.summary}`, { code: 'FAILURE', hint: 'run `bun install` in the App' })
+      // What package.json now says, and where a range comes from: the release its lockfile installed, or this CLI's SDK.
+      const lines = switched.packages.map((p) => `  ${p.pkg.padEnd(26)} ${p.spec}${npm ? (p.locked ? `  (the release its lockfile installed, ${p.locked}, recorded there with the same range)` : `  (this CLI's SDK range: no lockfile recorded a published release)`) : ''}`)
+      // Every file the switch wrote or deleted, by name, then what the install changed.
+      const changes = sdkSwitchChangeLines(switched.changes)
+      return {
+        data: { source: npm ? 'npm' : 'checkout', ...(checkout ? { checkout: checkout.platformSource, version: checkout.version } : {}), packages: switched.packages, changes: switched.changes, installed: install.installed },
+        text: [
+          switched.packages.length
+            ? npm ? 'The App uses the published SDK again. package.json now names:' : `The App uses the SDK of the platform checkout (${checkout!.version}):`
+            : 'The App already used the published SDK.',
+          ...lines,
+          ...(changes.length ? ['Changed in the App:', ...changes.map((c) => `  ${c}`)] : []),
+          `  bun install: ${install.summary} (node_modules, and bun.lock where what it resolves changed)`,
+          npm
+            ? changes.length ? 'Review these changes, then commit them.' : ''
+            : `Commit package.json, bun.lock and ${LOCAL_SDK_DIR}/. Run this again after the checkout's SDK changes; \`--npm\` switches back.`,
+        ].filter(Boolean).join('\n'),
+      }
+    }
+    if (action !== 'sync') throw new UsageError('expected use-local or sync', 'frontera app sdk use-local')
     const result = syncVendoredAppSdk(project.root)
     if (result.kind === 'published') {
       return {
         data: result,
-        text: 'This App uses published @frontera-sdk packages; update them with the package manager.',
+        text: 'This App uses published @frontera-sdk packages; update them with the package manager, or `frontera app sdk use-local` for the local runtime\'s checkout.',
       }
     }
     return {

package/src/commands/app/unpin.ts

@@ -0,0 +1,27 @@
+import { AppsApi } from '../../api/apps-api'
+import { UsageError } from '../../errors'
+import { projectApp, requireProjectFrom } from './shared'
+import { flagString, type Command } from '../types'
+
+/** Lift the pin a rollback left, keeping what serves: new deployments may go live again. Audited. */
+export const appUnpin: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'unpin',
+    args: [],
+    flags: { reason: 'string' },
+    summary: 'Unpin production after a rollback, keeping what serves now',
+    examples: ['frontera app unpin --reason "fixed forward in 1.4.1"'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const reason = flagString(ctx, 'reason')
+    if (!reason?.trim()) throw new UsageError('unpinning needs --reason', 'frontera app unpin --reason "why production may move again"')
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    const res = await client.unpin(app.id, reason)
+    return { data: { app: app.slug, appId: app.id, ...res }, text: `Unpinned ${app.slug}: production keeps serving ${res.productionLabel ?? res.production ?? 'what it serves'}, and promotion works again` }
+  },
+}

package/src/commands/app/versions.ts

@@ -9,7 +9,7 @@ export const appVersions: Command = {
     verb: 'versions',
     args: [],
     flags: {},
-    summary: 'List published versions, newest first; * marks the live one',
+    summary: 'List deployments, newest first; * marks production (see app deployments)',
     examples: ['frontera app versions', 'frontera app versions --json'],
     needsProject: true,
   },

package/src/commands/automation/bindings.ts

@@ -161,7 +161,8 @@ const bindings: Command = {
                   // still has a row, and a list that showed only the row would
                   // read as a working permission.
                   b.projects ? 'yes' : 'no',
-                  b.requiresApproval ? 'required' : 'auto',
+                  // `requiresApproval: false` is not "never asks": in an attended chat the person's approval mode still asks.
+                  b.requiresApproval ? 'required' : 'unattended (no card)',
                   `${b.waitSeconds}s`,
                   b.inertReason ?? '',
                 ]),
@@ -181,7 +182,8 @@ const bindings: Command = {
                 b.agentSlug,
                 b.agentName,
                 String(b.enabled),
-                b.requiresApproval ? 'required' : 'auto',
+                // `requiresApproval: false` is not "never asks": in an attended chat the person's approval mode still asks.
+                  b.requiresApproval ? 'required' : 'unattended (no card)',
                 `${b.waitSeconds}s`,
                 b.createdBy,
               ]),

package/src/commands/automation/build-entry.ts

@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 
 import { UsageError } from '../../errors'
+import { bundleIdMapFromEnv, mapBundleIds } from '../../local/local-function-ids'
 
 /**
  * Building an automation entry file, extracted from `index-commands`.
@@ -51,7 +52,9 @@ export async function buildAndExtract(file: string): Promise<{
     )
   }
 
-  const code = await built.outputs[0]!.text()
+  // `local dev` deploying a pulled Function to the local runtime: the workspace's object type ids
+  // its code hard-codes become this runtime's, in the bundle only (`local-function-ids.ts`).
+  const code = mapBundleIds(await built.outputs[0]!.text(), bundleIdMapFromEnv())
 
   const dir = mkdtempSync(join(tmpdir(), 'frontera-automation-'))
   try {

package/src/commands/automation/index-commands.ts

@@ -6,6 +6,7 @@ import { validateManifest } from '@frontera-sdk/functions'
 
 import { AutomationApi } from '../../api/automation-api'
 import { UsageError } from '../../errors'
+import { outsideImports } from '../../function-outside-imports'
 import { packDirectory } from '../../pack'
 import { automationInit } from './init'
 import { automationPull } from './pull'
@@ -118,7 +119,8 @@ const deploy: Command = {
     const projectRoot = findAutomationProjectRoot(resolve(file))
     let source: Uint8Array | undefined
     if (projectRoot) {
-      source = packDirectory(projectRoot, ctx.output, 'source').tgz
+      // With the files it imports from outside its folder, so a pull brings a Function that builds.
+      source = packDirectory(projectRoot, ctx.output, 'source', outsideImports(projectRoot, resolve(file))).tgz
     } else {
       // Degrade honestly rather than refuse. Authoring inside this monorepo is
       // still supported and simply cannot retain source — there is no

package/src/commands/automation/pull.ts

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, readdirSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 
 import { AutomationApi } from '../../api/automation-api'
 import { UsageError } from '../../errors'
+import { OUTSIDE_DIR } from '../../function-outside-imports'
 import { unpackTo } from '../../untar'
 import { flagBool, type Command } from '../types'
 
@@ -109,11 +110,15 @@ export const automationPull: Command = {
     const gz = await client.downloadSource(slug, resolved)
     mkdirSync(target, { recursive: true })
     const count = unpackTo(target, gz)
+    // Files it imports from beside its folder travel under `frontera-imports/` (`function-outside-imports.ts`):
+    // they are said, since this folder alone has nowhere beside it to put them.
+    const beside = existsSync(join(target, OUTSIDE_DIR))
 
     return {
       data: { slug, version: resolved, path: target, files: count },
       text: [
         `Pulled ${slug} v${resolved} into ${target} (${count} files)`,
+        ...(beside ? [`  ${OUTSIDE_DIR}/ holds the files it imports from beside its folder, by their path from it (each __up__ is ..): put them there before deploying, or pull the project with \`frontera local sync pull\`, which does`] : []),
         '',
         `  cd ${target}`,
         '  bun install',