@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/commands/action/retire.ts

@@ -1,21 +1,29 @@
-import { GovernedActionApi } from '../../api/governed-action-api'
+import { randomUUID } from 'node:crypto'
+
+import { GovernedActionApi, type ExternalWritePath } from '../../api/governed-action-api'
 import { CliError, UsageError } from '../../errors'
-import { flagString, type Command } from '../types'
+import { canPrompt, promptConfirm } from '../../prompt'
+import { flagBool, flagString, type Command } from '../types'
 
 /**
- * Retire an Action's deployment decision (Forge improvement plan X11).
+ * Retire an Action's deployment, so a changed Action can publish (Forge
+ * improvement plan X11).
  *
- * `action prepare` records that a drafted Action ships switched off, and the
- * decision pins the Action's contract as it was then: editing the drafted
- * Action after preparing it left it stranded, since publish refuses the
- * changed contract and a second prepare refuses a second decision. Retiring
- * the decision stands it down, so `action prepare` can record one for the
- * contract as it is now.
+ * A deployment pins the Action's contract as it was when it was decided:
+ * prepared, or deployed and turned on. Publish refuses a changed contract while
+ * a deployment still pins the old one, and a deployment cannot follow a new
+ * contract. Retiring stands it down, and the next `blueprint publish` records
+ * that the Action as it is now ships switched off.
  *
- * Only a decision that was never bound, or one already draining, retires:
- * the service refuses an active deployment, which is switched off first. It
- * arms nothing and removes nothing from the Blueprint. It takes a signed-in
- * person with `actionBinding: retire`.
+ * A running deployment is switched off first, as the service's `disable` does
+ * it: the running one drains and a disabled decision takes its place. Then
+ * every draining deployment of the Action and the decision are retired. A run
+ * cut short is finished by running it again. It takes a signed-in person with
+ * `actionBinding: activate` and `retire`, and removes nothing from the Blueprint.
+ * Switching off a running deployment is asked first, naming the Action and the
+ * host; `--yes` answers for a caller with no terminal. When the write path the
+ * Action last ran calls another system, it says that a second person reviews
+ * the one that replaces it, which retiring does not change.
  */
 export const actionRetire: Command = {
   meta: {
@@ -24,14 +32,17 @@ export const actionRetire: Command = {
     authLane: 'session',
     args: [{ name: 'action', required: true, description: 'The Action’s API name' }],
     flags: { reason: 'string' },
-    summary: 'Retire an Action’s deployment decision, so a changed draft can be prepared again',
+    summary: 'Switch off and retire an Action’s deployment, so a changed Action can publish',
     details: [
-      'For an Action prepared before its draft changed: retire, then `frontera action prepare <action>` records a decision for the contract as it is now.',
-      'An active deployment is refused: switch it off in Console first.',
+      'For an Action changed after it was prepared or deployed: retire, then `frontera blueprint publish` records a decision for the Action as it is now.',
+      'A running deployment is switched off first; the Action does not run again until `frontera action deploy <action>` turns it on.',
+      'It asks before switching off a running deployment, naming the Action and the host; --yes switches it off without asking.',
     ],
     examples: [
-      'frontera action retire escalateTicket --reason "draft changed"',
-      'frontera action prepare escalateTicket',
+      'frontera action retire escalateTicket --reason "the Action changed"',
+      'frontera action retire escalateTicket --reason "the Action changed" --yes',
+      'frontera blueprint publish',
+      'frontera action deploy escalateTicket',
     ],
   },
 
@@ -39,22 +50,63 @@ export const actionRetire: Command = {
     const apiName = ctx.positional[0]
     if (!apiName) throw new UsageError('missing <action>', 'frontera action retire escalateTicket --reason "…"')
     const reason = flagString(ctx, 'reason')?.trim()
-    if (!reason) throw new UsageError('say why with --reason', 'the reason is kept with the deployment’s history: frontera action retire escalateTicket --reason "the draft changed after it was prepared"')
+    if (!reason) throw new UsageError('say why with --reason', 'the reason is kept with the deployment’s history: frontera action retire escalateTicket --reason "the Action changed"')
 
     const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const definitionId = await client.actionDefinitionId(apiName)
     if (!definitionId) throw new CliError(`No Action "${apiName}" on the draft or in the release.`, { code: 'ACTION_NOT_FOUND', hint: 'frontera action list' })
     const current = await client.currentDeployment(definitionId)
-    if (!current) {
-      return { data: { action: apiName, retired: false }, text: `"${apiName}" carries no deployment decision: nothing to retire. \`frontera action prepare ${apiName}\` records one.` }
+    const running = current?.state === 'active'
+    const at = typeof ctx.flags.profile === 'string' ? ` --profile ${ctx.flags.profile}` : ''
+    if (running && !flagBool(ctx, 'yes')) {
+      const said = `"${apiName}" is running on ${new URL(ctx.apiUrl).host}; retiring it switches it off until it is deployed again`
+      const go = (ctx.interactive ?? canPrompt()) && ctx.flags['no-input'] !== true ? await promptConfirm(`${said}. Switch it off?`) : false
+      if (!go) {
+        throw new CliError(`${said}, so nothing was retired.`, {
+          code: 'USAGE',
+          hint: `to switch it off, add --yes: frontera action retire ${apiName} --reason ${JSON.stringify(reason)} --yes${at}`,
+        })
+      }
+    }
+    const decision = current?.state === 'active'
+      ? await client.disableDeployment(randomUUID(), {
+        bindingId: randomUUID(),
+        actionDefinitionId: definitionId,
+        actionContractDigest: current.actionContractDigest,
+        expectedCurrentStateId: current.stateId,
+        expectedCurrentGeneration: current.generation,
+        reason,
+      })
+      : current
+    const draining = await client.drainingDeployments(definitionId)
+    for (const deployment of draining) await client.retireDeployment(deployment.stateId, deployment.generation, reason)
+    const retired = decision ? await client.retireDeployment(decision.stateId, decision.generation, reason) : null
+
+    if (!current && draining.length === 0) {
+      return { data: { action: apiName, retired: false }, text: `"${apiName}" carries no deployment decision: nothing to retire. \`frontera blueprint publish\` records one.` }
     }
-    if (current.state === 'active') {
-      throw new CliError(`"${apiName}" is deployed and switched on; an active deployment isn't retired.`, { code: 'CONFLICT', hint: 'switch it off in Console (the Action’s deployment) first, then retire it' })
+    // Read after the writes landed, so a failure here is reported as a note, not as a failed retire.
+    let external: ExternalWritePath | null = null
+    let unread: string | null = null
+    try {
+      external = await client.externalWritePath(definitionId)
+    } catch (err) {
+      unread = err instanceof Error ? err.message : String(err)
     }
-    const retired = await client.retireDeployment(current.stateId, current.generation, reason)
+    const secondPerson = unread !== null
+      ? `Could not read whether the last write path "${apiName}" ran calls another system (${unread}). If it does, a second person reviews the one that replaces it; \`frontera action deploy ${apiName}${at}\` reads it again before it builds.\n\n`
+      : external
+        ? `The last write path "${apiName}" ran calls another system (${external.planKind ?? 'a kind the platform cannot read'}), which a second person reviewed, so a second person reviews the one that replaces it. `
+          + `\`frontera action deploy ${apiName}${at}\` builds it and prints the command they run.\n\n`
+        : ''
+    const what = running
+      ? `Switched off the running deployment of "${apiName}" and retired it. "${apiName}" does not run until it is deployed again.`
+      : current
+        ? `Retired the ${current.state} deployment decision of "${apiName}".`
+        : `Retired the deployment of "${apiName}" that was still draining.`
     return {
-      data: { action: apiName, retired: true, from: current.state, deployment: retired },
-      text: `Retired the ${current.state} deployment decision of "${apiName}".\n\nNext:\n  frontera action prepare ${apiName}`,
+      data: { action: apiName, retired: true, from: current?.state ?? 'draining', switchedOff: running, deployment: retired, externalWritePath: external, ...(unread !== null ? { externalWritePathError: unread } : {}) },
+      text: `${what}\n\n${secondPerson}Next:\n  frontera blueprint publish${at}${running ? `\n  frontera action deploy ${apiName}${at}` : ''}`,
     }
   },
 }

package/src/commands/action/review.ts

@@ -1,16 +1,18 @@
-import { GovernedActionApi } from '../../api/governed-action-api'
+import { GovernedActionApi, type ExternalWritePath } from '../../api/governed-action-api'
 import { CliError, UsageError } from '../../errors'
 import { flagString, type Command, type CommandContext } from '../types'
 
 /**
  * Approve a validated write path, and switch it on.
  *
- * Its own verb because it must run as a DIFFERENT principal: the service
- * refuses a reviewer who authored the Binding, the connector or the plan. An
- * organization key's principal is `orgkey:<org>:<key>`, so a second key is a
- * second reviewer — no second human required to arm a deployment in a
- * non-production organization, and a real one required wherever the roles are
- * held by people.
+ * Its own verb because only a person's session may review, and `action
+ * deploy` may have built the write path with an organization key. The person
+ * who built a write path that only edits Blueprint records may review it; one
+ * that calls another system needs a second person, and the service refuses
+ * its author. So does one that replaces a write path calling another system,
+ * and nobody's review turns that one on when an API key built it, so it asks
+ * before it reviews. `action deploy` run as a person does both and ends with
+ * the same two steps.
  *
  * Review and activate are one command because the bookkeeping between them is
  * not a decision: activation names the generation review left the revision's
@@ -35,15 +37,50 @@ const READ_REFUSED_HINT =
  * longer switch on. The message stays the service's; the hint says which step
  * refused and what did not happen.
  */
-async function requireReadableRevision(client: GovernedActionApi, bindingRevisionId: string): Promise<void> {
+async function requireReadableRevision(client: GovernedActionApi, bindingRevisionId: string) {
   try {
-    await client.getBindingRevision(bindingRevisionId)
+    return await client.getBindingRevision(bindingRevisionId)
   } catch (err) {
     if (!(err instanceof CliError) || err.code !== 'FORBIDDEN') throw err
     throw new CliError(err.message, { code: 'FORBIDDEN', hint: READ_REFUSED_HINT, cause: err })
   }
 }
 
+/** What the Action does on a write path that calls another system, said of `subject`. */
+export function externalWritePathSentence(subject: string, external: ExternalWritePath): string {
+  const where = external.state === 'active' ? 'runs on' : external.state === 'draining' ? 'is still finishing requests on' : 'last ran on'
+  return `${subject} ${where} a write path that calls another system (${external.planKind ?? 'a kind the platform cannot read'}), which a second person reviewed.`
+}
+
+/**
+ * Asked before a review that activation follows. While the Action runs,
+ * drains or last ran a write path that calls another system, activation turns
+ * a new one on only for a reviewer who built none of it, and never one an API
+ * key built, so a review it would refuse is not recorded.
+ */
+async function requireReviewTurnsItOn(
+  client: GovernedActionApi,
+  revision: { id: string; actionDefinitionId: string },
+  validationReportId: string,
+): Promise<void> {
+  const external = await client.externalWritePath(revision.actionDefinitionId, revision.id)
+  if (!external?.reviewRefusal) return
+  const keyBuilt = external.reviewRefusal === 'key_built'
+  throw new CliError(
+    `${externalWritePathSentence('The Action', external)} `
+    + (keyBuilt
+      ? 'This one was built with an API key, so no review turns it on in its place, and nothing was reviewed.'
+      : 'You built this one, so a second person reviews it, and nothing was reviewed.'),
+    {
+      code: 'CONFLICT',
+      hint: keyBuilt
+        ? 'a person signed in as themselves runs `frontera action deploy` for this Action, which builds a new one as them, and a second person reviews it with the command it prints'
+        : `a second person who may review Actions turns it on with: frontera action review ${revision.id} --report ${validationReportId}`,
+      details: { reviewRefusal: external.reviewRefusal, replacedPlanKind: external.planKind, replacedState: external.state },
+    },
+  )
+}
+
 /** The review has landed and the states activation names could not be read. */
 function notReadable(cause?: unknown): CliError {
   return new CliError('Reviewed, but the deployment state for this revision is not readable.', {
@@ -83,6 +120,43 @@ async function readActivation(client: GovernedActionApi, bindingRevisionId: stri
   }
 }
 
+/**
+ * Review the revision at the exact validation it read. When it will be
+ * activated next, a reviewer who may not read it, or whose review activation
+ * would refuse, is refused first, with nothing reviewed.
+ */
+export async function reviewRevision(client: GovernedActionApi, input: {
+  bindingRevisionId: string
+  validationReportId: string
+  activating: boolean
+}): Promise<void> {
+  if (input.activating) {
+    const revision = await requireReadableRevision(client, input.bindingRevisionId)
+    await requireReviewTurnsItOn(client, revision, input.validationReportId)
+  }
+  // The generation is the service's, not ours: validation left the state at 2.
+  await client.reviewBindingRevision(input.bindingRevisionId, {
+    validationReportId: input.validationReportId,
+    expectedStateGeneration: 2,
+  })
+}
+
+/** Switch a reviewed revision on over whatever its Action is on now. */
+export async function activateReviewed(
+  client: GovernedActionApi,
+  bindingRevisionId: string,
+  reason = 'Activated from the CLI after review.',
+): Promise<{ stateId: string }> {
+  const { target, current } = await readActivation(client, bindingRevisionId)
+  await client.activateDeployment(target.stateId, {
+    expectedGeneration: target.generation,
+    expectedCurrentStateId: current?.stateId ?? null,
+    expectedCurrentGeneration: current?.generation ?? null,
+    reason,
+  })
+  return { stateId: target.stateId }
+}
+
 export const actionReview: Command = {
   meta: {
     noun: 'action',
@@ -113,13 +187,7 @@ export const actionReview: Command = {
     const client = api(ctx)
     const activate = ctx.flags['no-activate'] !== true
 
-    if (activate) await requireReadableRevision(client, bindingRevisionId)
-
-    // The generation is the service's, not ours: validation left the state at 2.
-    await client.reviewBindingRevision(bindingRevisionId, {
-      validationReportId,
-      expectedStateGeneration: 2,
-    })
+    await reviewRevision(client, { bindingRevisionId, validationReportId, activating: activate })
 
     if (!activate) {
       return {
@@ -128,17 +196,10 @@ export const actionReview: Command = {
       }
     }
 
-    const { target, current } = await readActivation(client, bindingRevisionId)
-
-    await client.activateDeployment(target.stateId, {
-      expectedGeneration: target.generation,
-      expectedCurrentStateId: current?.stateId ?? null,
-      expectedCurrentGeneration: current?.generation ?? null,
-      reason: flagString(ctx, 'reason') ?? 'Activated from the CLI after review.',
-    })
+    const { stateId } = await activateReviewed(client, bindingRevisionId, flagString(ctx, 'reason'))
 
     return {
-      data: { bindingRevisionId, stateId: target.stateId, reviewed: true, activated: true },
+      data: { bindingRevisionId, stateId, reviewed: true, activated: true },
       text: 'Reviewed and activated. The Action can now be invoked.',
     }
   },

package/src/commands/app/checks.ts

@@ -37,7 +37,7 @@ export const appChecks: Command = {
     if (!deployment) throw new UsageError('say which deployment', 'frontera app checks <deployment id or label>')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const res = await client.checks(app.id, deployment)
     return { data: res, text: renderChecks(res.deployment, res.checks) }
   },

package/src/commands/app/deploy.ts

@@ -9,14 +9,14 @@ import { resolveManifest } from '../../manifest'
 import { collectSourceFiles, formatBytes } from '../../packaging'
 import { packDirectory } from '../../pack'
 import { collectAppContract } from '../../app-contract'
-import { writeAppId, writeState } from '../../project'
+import { writeState } from '../../project'
 import { collectBuildProvenance } from '../../provenance'
 import { validateStaticAppProject } from '../../static-app-validation'
 import { describeRenderEvidence, readRenderEvidence, readRenderThumbnail, type RenderEvidence } from '../../render-evidence'
 import { createTarGz } from '../../tar'
 import { keepBuildWrittenFiles } from '../../local/local-app-pulled'
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
-import { requireProjectFrom } from './shared'
+import { ensureProjectApp, requireProjectFrom } from './shared'
 import { canPrompt } from '../../prompt'
 import { flagBool, flagString, type Command } from '../types'
 
@@ -196,12 +196,14 @@ export const appDeploy: Command = {
     noun: 'app',
     verb: 'deploy',
     args: [],
-    flags: { label: 'string', version: 'string', prod: 'boolean', preview: 'boolean', 'no-promote': 'boolean', 'skip-build-check': 'boolean', build: 'boolean' },
+    flags: { label: 'string', version: 'string', prod: 'boolean', preview: 'boolean', 'no-promote': 'boolean', 'skip-build-check': 'boolean', build: 'boolean', app: 'string' },
+    flagHelp: { app: 'an App this workspace already has, by its slug: deploy to it, and keep this folder deploying to it here' },
     summary: 'Upload the build as a preview deployment; --build to build first, --prod to go live',
     details: [
       'A deploy is a preview unless --prod is given. A pipeline (a key, no terminal) must say which it wants: --prod or --preview. Without either it exits with an error, so a pipeline written when a deploy went live stops instead of silently making previews.',
+      'The folder deploys to the App it deployed to before in the same workspace, whatever its package.json name says now: a deploy never renames an App. In a workspace it has not deployed to, it deploys to the App named like the folder, and creates that App when there is none, which the output says.',
     ],
-    examples: ['frontera app deploy', 'frontera app deploy --build', 'frontera app deploy --label 1.4.0', 'frontera app deploy --prod', 'frontera app deploy --preview', 'frontera app deploy --prod --no-promote'],
+    examples: ['frontera app deploy', 'frontera app deploy --build', 'frontera app deploy --label 1.4.0', 'frontera app deploy --prod', 'frontera app deploy --preview', 'frontera app deploy --prod --no-promote', 'frontera app deploy --app acme-shipments'],
     needsProject: true,
   },
 
@@ -284,7 +286,7 @@ export const appDeploy: Command = {
     }
 
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await client.ensureApp(project.slug, project.displayName, project.appId, { icon: project.icon })
+    const app = await ensureProjectApp(ctx, client, project, flagString(ctx, 'app'))
 
     ctx.output.note(
       `  bundle ${distFiles.length} files, ${formatBytes(distFiles.reduce((n, f) => n + f.bytes.byteLength, 0))}`,
@@ -342,10 +344,7 @@ export const appDeploy: Command = {
     const deployment = res.deployment ?? res.version
 
     // On the runtime again: whatever a database restore had taken away is back.
-    writeState(project.root, { appId: app.id, parentVersion: deployment, restoredAway: undefined })
-    // Local environment binding: source remains portable and package.json
-    // remains ordinary package metadata.
-    writeAppId(project.root, app.id)
+    writeState(project.root, { parentVersion: deployment, restoredAway: undefined })
 
     // Where a person opens what was just made: its own link, and the moving
     // links of its branch and session. A preview was once described as one
@@ -360,6 +359,7 @@ export const appDeploy: Command = {
     const data = {
       app: app.slug,
       appId: app.id,
+      ...(app.created ? { created: app.created } : {}),
       deployment,
       // The same id, under its earlier name, for scripts that read `version`.
       version: deployment,

package/src/commands/app/deployments.ts

@@ -72,7 +72,7 @@ export const appDeployments: Command = {
   async run(ctx) {
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const ledger = await client.deployments(app.id)
     // The checks of the newest deployments that still have files; an older or
     // failed read falls back to the render evidence the ledger already carries.

package/src/commands/app/dev.ts

@@ -1,19 +1,31 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
 import { AppsApi } from '../../api/apps-api'
 import { PlatformApi } from '../../api/platform-api'
 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 {
+  DEV_OWNER_ENV,
+  devServerHome,
+  devServerLine,
+  enclosingSolution,
+  ensureDevServer,
+  forgetDevServer,
+  readDevServer,
+  registerDevServer,
+  stopDevServerAndSay,
+  watchOwner,
+} from '../../mcp/mcp-apps'
 import { ensureAppPackages } from '../../project-bootstrap'
 import { detectAppFramework } from '../../provenance'
-import { writeAppId } from '../../project'
+import type { AppProject } from '../../context'
+import { bindApp } 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'
+import { ensureProjectApp, requireProjectFrom } from './shared'
+import { flagBool, flagString, type Command, type CommandContext, type CommandResult } from '../types'
 
 const DEFAULT_PORT = 3000
 const READY_TIMEOUT_MS = 30_000
@@ -74,19 +86,69 @@ function withoutOwner(env: NodeJS.ProcessEnv): Record<string, string> {
   return rest as Record<string, string>
 }
 
+/**
+ * `--detach`: the same server, started by `ensureDevServer` in its own session with its output in a log, so it
+ * outlives the shell that started it (an agent's background command is killed at its time limit, with its whole
+ * process group). Recorded where `--stop`, `local stop`, MCP `app_dev` and Forge find it; a live one is reused.
+ */
+async function detach(ctx: CommandContext, project: AppProject): Promise<CommandResult> {
+  const raw = flagString(ctx, 'port')
+  const port = raw === undefined ? 0 : appPort(raw)
+  // Here, not in the server's log: a creation is said where the caller reads it, and a bad credential fails now.
+  const app = await ensureProjectApp(ctx, new AppsApi(ctx.apiUrl, ctx.token), project)
+  const home = devServerHome(project.root)
+  const ref = { slug: project.slug, name: project.displayName, root: project.root, path: relative(home.root, project.root) || '.', framework: detectAppFramework(project.root) }
+  let started: Awaited<ReturnType<typeof ensureDevServer>>
+  try {
+    started = await ensureDevServer(home, ref, { env: { FRONTERA_API_URL: ctx.apiUrl }, token: ctx.token, target: app.target }, { owner: 'detached', port })
+  } catch (error) {
+    throw new CliError((error as Error).message, { code: 'FAILURE', cause: error, hint: '`frontera app dev` without --detach runs the server in the foreground, where its output shows as it starts' })
+  }
+  const { server, reused, installed, trackedFiles } = started
+  if (installed) ctx.output.note(`[dev] ${installed}`)
+  for (const line of trackedFiles ?? []) ctx.output.note(`[dev] ${line}`)
+  const logFile = join(home.root, server.log)
+  const log = existsSync(logFile) ? relative(ctx.cwd, logFile) : server.log
+  return {
+    data: { appId: app.id, origin: server.url, port: server.port, pid: server.pid, log, reused },
+    text: [
+      reused ? `Reused the dev server already running: ${devServerLine(server)}.` : `${app.slug} runs at ${server.url} in its own session: it keeps running after this shell ends.`,
+      `  log: ${log}`,
+      '  stop it: `frontera app dev --stop` in this folder',
+    ].join('\n'),
+  }
+}
+
+/** `--stop`: the App's recorded dev server, however it was started, and what it put back as it stopped. */
+async function stopRecorded(ctx: CommandContext, project: AppProject): Promise<CommandResult> {
+  const home = devServerHome(project.root)
+  const server = readDevServer(home, project.slug)
+  const { stopped, trackedFiles } = await stopDevServerAndSay(home, project.slug)
+  for (const line of trackedFiles) ctx.output.note(`[dev] ${line}`)
+  if (!stopped || !server) return { data: { stopped: false }, text: `${project.slug} had no dev server running.` }
+  return { data: { stopped: true, port: server.port, pid: server.pid }, text: `Stopped ${project.slug}'s dev server (port ${server.port}).` }
+}
+
 export const appDev: Command = {
   meta: {
     noun: 'app',
     verb: 'dev',
     args: [],
-    flags: { port: 'string', 'no-open': 'boolean' },
+    flags: { port: 'string', 'no-open': 'boolean', detach: 'boolean', stop: 'boolean' },
+    flagHelp: { stop: 'stop this App\'s dev server, however it was started, and exit' },
     summary: 'Run an App locally with short-lived authenticated Blueprint access',
-    examples: ['frontera app dev', 'frontera app dev --port 3210 --no-open', 'frontera app dev --port 0'],
+    details: [
+      'Without --detach the server runs in the foreground until you stop it (Ctrl+C). With --detach it starts in its own session, returns once the App answers, and prints its URL, its log and how to stop it: use it from a coding agent, whose background commands end at a time limit. Run it again to get the same server back.',
+    ],
+    examples: ['frontera app dev', 'frontera app dev --detach', 'frontera app dev --stop', 'frontera app dev --port 3210 --no-open', 'frontera app dev --port 0'],
     needsProject: true,
   },
 
   async run(ctx) {
     const project = requireProjectFrom(ctx)
+    if (flagBool(ctx, 'detach') && flagBool(ctx, 'stop')) throw new UsageError('--detach and --stop do opposite things', 'start it with `frontera app dev --detach`, stop it with `frontera app dev --stop`')
+    if (flagBool(ctx, 'stop')) return stopRecorded(ctx, project)
+    if (flagBool(ctx, 'detach')) return detach(ctx, project)
     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
@@ -109,10 +171,10 @@ export const appDev: Command = {
     }
     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, { icon: project.icon })
-    writeAppId(project.root, app.id)
+    const app = await ensureProjectApp(ctx, apps, project)
     // The solution this App is in, if any: where status reads how this server's sessions fare.
     const solution = enclosingSolution(project.root)
+    const home = devServerHome(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
 
@@ -132,12 +194,12 @@ export const appDev: Command = {
             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, { icon: project.icon })).id,
+            reRegister: async () => (await apps.ensureApp(app.slug, project.displayName, null, { icon: project.icon })).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)
+              bindApp(project.root, app.target, id)
             },
             record: solution ? (state) => writeDevSessionState(solution.stateDir, project.slug, state) : undefined,
           })
@@ -235,8 +297,11 @@ export const appDev: Command = {
       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' })
+      // Said where agents, Forge and `--detach` look, so they use this server instead of starting another. One
+      // `--detach` started is already recorded, with its log; a live one another process recorded stays.
+      if (!owner && !readDevServer(home, project.slug)) {
+        registerDevServer(home, { slug: project.slug, pid: process.pid, port, url: targetUrl, startedAt: new Date().toISOString(), log: 'the terminal running frontera app dev', ...(app.target ? { target: app.target } : {}) })
+      }
       if (!flagBool(ctx, 'no-open')) openBrowser(targetUrl)
       const exitCode = await child.exited
       if (!stopped && exitCode !== 0) {
@@ -253,7 +318,7 @@ export const appDev: Command = {
       unwatch?.()
       process.off('SIGINT', onSignal)
       process.off('SIGTERM', onSignal)
-      if (solution) forgetDevServer(solution, project.slug, process.pid)
+      forgetDevServer(home, 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)])

package/src/commands/app/promote.ts

@@ -35,7 +35,7 @@ export const appPromote: Command = {
     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 app = await projectApp(ctx, client, project)
     try {
       const res = await client.promote(app.id, { deployment, ...(force ? { force: true, reason } : {}) })
       const name = res.label ?? res.promoted

package/src/commands/app/pull.ts

@@ -3,9 +3,10 @@ import { join } from 'node:path'
 import { AppsApi } from '../../api/apps-api'
 import { CliError, UsageError } from '../../errors'
 import { healProject } from '../../heal'
-import { dirtyFiles, writeState } from '../../project'
+import { bindApp, dirtyFiles, writeState } from '../../project'
 import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
 import { flagBool, type Command } from '../types'
+import { credentialTarget } from './shared'
 import { unpackTo } from '../../untar'
 
 export const appPull: Command = {
@@ -96,7 +97,8 @@ export const appPull: Command = {
     const count = unpackTo(dir, bytes)
     // 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 })
+    writeState(dir, { parentVersion: null, pulledFrom: app.id, pulledVersion: parentVersion })
+    bindApp(dir, await credentialTarget(ctx), app.id)
 
     // 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

@@ -25,7 +25,7 @@ export const appRollback: Command = {
     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)
+    const app = await projectApp(ctx, client, project)
     if (undo) {
       const res = await client.undoRollback(app.id)
       return {

package/src/commands/app/save.ts

@@ -1,7 +1,6 @@
 import { AppsApi } from '../../api/apps-api'
 import { packDirectory } from '../../pack'
-import { writeAppId, writeState } from '../../project'
-import { requireProjectFrom } from './shared'
+import { ensureProjectApp, requireProjectFrom } from './shared'
 import type { Command } from '../types'
 
 export const appSave: Command = {
@@ -21,15 +20,12 @@ export const appSave: Command = {
 
     // save and deploy are the only verbs that may bring an app into
     // existence; every read verb resolves instead.
-    const app = await client.ensureApp(project.slug, project.displayName, project.appId, { icon: project.icon })
+    const app = await ensureProjectApp(ctx, client, project)
     const { tgz } = packDirectory(project.root, ctx.output, 'packaged')
     const res = await client.saveDraft(app.id, tgz, project.parentVersion)
 
-    writeState(project.root, { appId: app.id })
-    writeAppId(project.root, app.id)
-
     return {
-      data: { app: app.slug, appId: app.id, fileCount: res.fileCount },
+      data: { app: app.slug, appId: app.id, ...(app.created ? { created: app.created } : {}), fileCount: res.fileCount },
       text: `Saved draft for ${app.slug} (${res.fileCount} files)`,
     }
   },