@frontera-sdk/cli 1.52.39 → 1.52.40

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

@@ -0,0 +1,88 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * How a running `frontera app dev` last fared minting the browser's App
+ * session, kept beside its server record (`.frontera/local/app-dev/<slug>.session`)
+ * so `frontera local status` can say a dev server needs a restart, which only
+ * the dev server itself can see.
+ *
+ * A session is minted for the App's id on the runtime. After `frontera local
+ * snapshot restore` (or a `local check` rollback) to a baseline taken before
+ * the App existed, that id is gone: the dev server registers the App again by
+ * its slug and mints for the new id (`mintDevSession`). When that fails too,
+ * the record says so, with the platform's words.
+ */
+export interface DevSessionState {
+  ok: boolean
+  at: string
+  /** The platform's refusal, when the last mint failed. */
+  error?: string
+  /** The App was registered again on the runtime, under this id, before the session could be minted. */
+  reRegistered?: string
+}
+
+const sessionFile = (solutionStateDir: string, slug: string) => join(solutionStateDir, 'app-dev', `${slug.replace(/[^a-z0-9-]+/gi, '-')}.session`)
+
+export function writeDevSessionState(solutionStateDir: string, slug: string, state: DevSessionState): void {
+  try {
+    mkdirSync(join(solutionStateDir, 'app-dev'), { recursive: true })
+    writeFileSync(sessionFile(solutionStateDir, slug), `${JSON.stringify(state, null, 2)}\n`)
+  } catch {
+    // Only status reads it; the session itself does not need it.
+  }
+}
+
+export function readDevSessionState(solutionStateDir: string, slug: string): DevSessionState | null {
+  try {
+    const state = JSON.parse(readFileSync(sessionFile(solutionStateDir, slug), 'utf8')) as Partial<DevSessionState>
+    return typeof state.ok === 'boolean' && typeof state.at === 'string' ? (state as DevSessionState) : null
+  } catch {
+    return null
+  }
+}
+
+/** A platform answer that means "no such App here" or "this App's credential is no longer good": re-registering may fix it. */
+export function isAppGone(error: unknown): boolean {
+  const status = (error as { status?: unknown } | null)?.status
+  const code = (error as { code?: unknown } | null)?.code
+  return status === 401 || status === 403 || status === 404 || code === 'NOT_FOUND' || code === 'UNAUTHORIZED'
+}
+
+/**
+ * Mint a session for the App, registering it again first when the runtime no
+ * longer has it. `appId` is the current id; `reRegister` asks the runtime for
+ * the App by its slug (creating it), and returns the id to mint for.
+ */
+export async function mintDevSession<T>(args: {
+  appId: string
+  mint: (appId: string) => Promise<T>
+  reRegister: () => Promise<string>
+  /** Told the id the App has now, after a re-registration. */
+  onReRegistered?: (appId: string) => void
+  record?: (state: DevSessionState) => void
+  now?: () => Date
+}): Promise<{ session: T; appId: string }> {
+  const at = () => (args.now ?? (() => new Date()))().toISOString()
+  try {
+    const session = await args.mint(args.appId)
+    args.record?.({ ok: true, at: at() })
+    return { session, appId: args.appId }
+  } catch (first) {
+    if (!isAppGone(first)) {
+      args.record?.({ ok: false, at: at(), error: (first as Error)?.message ?? String(first) })
+      throw first
+    }
+    try {
+      const appId = await args.reRegister()
+      args.onReRegistered?.(appId)
+      const session = await args.mint(appId)
+      args.record?.({ ok: true, at: at(), ...(appId !== args.appId ? { reRegistered: appId } : {}) })
+      return { session, appId }
+    } catch (second) {
+      const error = `${(second as Error)?.message ?? String(second)} (the runtime no longer has this App or its credential, and registering it again failed: stop this dev server and start it again)`
+      args.record?.({ ok: false, at: at(), error })
+      throw new Error(error)
+    }
+  }
+}

package/src/local/local-app-lock-install.ts

@@ -0,0 +1,114 @@
+import { copyFileSync, cpSync, existsSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { lockedSdkVersions } from '../app-lock'
+import type { InstallOptions, InstallResult } from '../project-bootstrap'
+
+/**
+ * A pulled App's packages, installed as its `bun.lock` records them: the
+ * deployed App's actual dependencies, from the npm registry.
+ *
+ * An older pull left such an App with package.json naming the SDK copy
+ * under src/frontera/ (`file:./src/frontera/core`) where bun.lock installed a
+ * published release (`@frontera-sdk/core@1.50.61`), the one its code was
+ * written against. A frozen install refuses the two as they disagree, and an
+ * install from the copy builds the code against an older SDK than it was
+ * written for.
+ *
+ * So the install runs in a temporary folder holding a copy of package.json
+ * whose SDK entries name the ranges bun.lock records for them (`^1.43.10`),
+ * and bun.lock as it is: `bun install --frozen-lockfile` there installs
+ * exactly what the lockfile says, and its node_modules is moved into the App.
+ * Neither the App's package.json nor its bun.lock is opened for writing.
+ *
+ * Null when it can't be done that way: bun.lock records no range for one of
+ * the packages, or package.json takes another package from a local path the
+ * temporary folder doesn't have. The caller then installs from the copy.
+ */
+
+/** Files beside package.json that change how an install resolves: copied to the temporary folder too. */
+const INSTALL_CONFIG = ['.npmrc', 'bunfig.toml']
+
+const LOCAL_SPEC = /^(file|link|workspace|portal):/
+
+export interface LockInstall extends InstallResult {
+  /** The packages installed as the lockfile records them, with the release it installed. */
+  fromLock: Array<{ pkg: string; version: string }>
+}
+
+export async function installFromLock(
+  appRoot: string,
+  shadows: ReadonlyArray<{ pkg: string; version: string }>,
+  install: (dir: string, options?: InstallOptions) => Promise<InstallResult>,
+): Promise<LockInstall | null> {
+  if (!shadows.length || !existsSync(join(appRoot, 'bun.lock'))) return null
+  const locked = lockedSdkVersions(appRoot)
+  const ranges = new Map<string, string>()
+  for (const s of shadows) {
+    const range = locked.get(s.pkg)?.range
+    if (!range) return null
+    ranges.set(s.pkg, range)
+  }
+  let manifest: Record<string, unknown>
+  try {
+    manifest = JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8')) as Record<string, unknown>
+  } catch {
+    return null
+  }
+  const sections = ['dependencies', 'devDependencies', 'optionalDependencies'] as const
+  // Another package from a local path would not resolve from the temporary folder: installed from the copy instead.
+  for (const section of sections) {
+    for (const [pkg, spec] of Object.entries((manifest[section] as Record<string, string> | undefined) ?? {})) {
+      if (!ranges.has(pkg) && typeof spec === 'string' && LOCAL_SPEC.test(spec)) return null
+    }
+  }
+  const asLocked = { ...manifest }
+  for (const section of sections) {
+    const deps = manifest[section] as Record<string, string> | undefined
+    if (!deps) continue
+    asLocked[section] = Object.fromEntries(Object.entries(deps).map(([pkg, spec]) => [pkg, ranges.get(pkg) ?? spec]))
+  }
+  const stage = mkdtempSync(join(tmpdir(), 'frontera-lock-install-'))
+  try {
+    writeFileSync(join(stage, 'package.json'), `${JSON.stringify(asLocked, null, 2)}\n`)
+    copyFileSync(join(appRoot, 'bun.lock'), join(stage, 'bun.lock'))
+    for (const name of INSTALL_CONFIG) if (existsSync(join(appRoot, name))) copyFileSync(join(appRoot, name), join(stage, name))
+    const result = await install(stage, { frozenLockfile: true })
+    const fromLock = shadows.map((s) => ({ pkg: s.pkg, version: locked.get(s.pkg)!.version }))
+    if (!result.installed || !existsSync(join(stage, 'node_modules'))) {
+      return { installed: false, summary: result.installed ? 'it wrote no node_modules' : result.summary, fromLock, ...(result.lockMismatch ? { lockMismatch: true } : {}) }
+    }
+    // The release the lockfile records, or the install did something else: not moved in.
+    const wrong = fromLock.find((s) => installedVersion(stage, s.pkg) !== s.version)
+    if (wrong) return { installed: false, summary: `it installed ${wrong.pkg} ${installedVersion(stage, wrong.pkg) ?? '(none)'}, not the ${wrong.version} bun.lock records`, fromLock }
+    moveInto(join(stage, 'node_modules'), join(appRoot, 'node_modules'))
+    return { installed: true, summary: result.summary, fromLock }
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+}
+
+/** The version of `pkg` a folder's node_modules holds, or null. */
+export function installedVersion(dir: string, pkg: string): string | null {
+  try {
+    return (JSON.parse(readFileSync(join(dir, 'node_modules', pkg, 'package.json'), 'utf8')) as { version?: string }).version ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Move a folder, copying it (links kept as they are) where a rename can't cross file systems. */
+function moveInto(from: string, to: string): void {
+  try {
+    renameSync(from, to)
+  } catch {
+    cpSync(from, to, { recursive: true, verbatimSymlinks: true })
+  }
+}
+
+/** What the install did, in words: the releases installed and that neither file changed. */
+export function lockInstallLine(fromLock: LockInstall['fromLock'], summary: string): string {
+  const released = fromLock.map((s) => `${s.pkg} ${s.version}`).join(' and ')
+  return `installed what its bun.lock records from npm (${summary}): the published ${released} its code was written against, where package.json names the SDK copy under src/frontera/. The install ran in a temporary folder whose copy of package.json names those releases, with \`bun install --frozen-lockfile\`; the App's package.json and bun.lock are unchanged`
+}

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

@@ -0,0 +1,167 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+import { writeState } from '../project'
+import { fileAsWas, putBackAsWas, type FileAsWas } from './local-app-dev-files'
+import { readLock } from './local-sync-plan'
+
+/**
+ * A pulled Custom App's code as the pull left it: each source file's hash,
+ * kept in the App folder's state (`.frontera/state.json`, `pulledFiles`) when
+ * its code is pulled. `local check` reads it the way it reads `frontera.lock`
+ * for the rest of the project: an App whose source is all as pulled, with no
+ * file added or removed, fails its check through no change of the person's,
+ * so the failure is inherited from the workspace (`--strict` still fails it).
+ *
+ * What a build or an install writes is not source and is left out of both
+ * sides: `node_modules/`, `.next/`, build output, `*.tsbuildinfo`,
+ * `next-env.d.ts`, `.env*`, the folder's own `.frontera/`.
+ */
+
+/** Generated wherever they are. */
+const GENERATED_DIRS = new Set(['node_modules', '.next', '.turbo', '.vercel', '.git'])
+/** Generated at the folder's top only: a `src/build/` may be source. */
+const GENERATED_TOP = new Set(['.frontera', 'dist', 'build', 'out', 'coverage'])
+/** Written by a build, an install or a dev host (`.env.local`, which `app dev` points at the local runtime), never source. */
+const isGenerated = (name: string) => name.endsWith('.tsbuildinfo') || name === 'next-env.d.ts' || name === '.DS_Store' || name.endsWith('.log') || name === '.env' || name.startsWith('.env.')
+
+const hashBytes = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex').slice(0, 16)
+
+/** Each source file of an App folder: its path in the folder and when it was last written. */
+function appSourceFiles(dir: string): Array<{ rel: string; path: string; mtimeMs: number }> {
+  const out: Array<{ rel: string; path: string; mtimeMs: number }> = []
+  const walk = (at: string, rel: string) => {
+    for (const name of readdirSync(at).sort()) {
+      const path = join(at, name)
+      const st = statSync(path)
+      if (st.isDirectory()) {
+        if (!GENERATED_DIRS.has(name) && !(rel === '' && GENERATED_TOP.has(name))) walk(path, rel ? `${rel}/${name}` : name)
+      } else if (st.isFile() && !isGenerated(name)) {
+        out.push({ rel: rel ? `${rel}/${name}` : name, path, mtimeMs: st.mtimeMs })
+      }
+    }
+  }
+  if (existsSync(dir)) walk(dir, '')
+  return out
+}
+
+/** Each source file of an App folder, by its path in the folder, with its hash. */
+export function appSourceHashes(dir: string): Record<string, string> {
+  return Object.fromEntries(appSourceFiles(dir).map((f) => [f.rel, hashBytes(readFileSync(f.path))]))
+}
+
+/** Record the folder's source as pulled (after the pull's own repairs): the baseline `local check` compares with. */
+export function recordPulledFiles(dir: string): void {
+  writeState(dir, { pulledFiles: appSourceHashes(dir) })
+}
+
+/**
+ * Whether an App folder's source is all as its pull left it: true, false, or
+ * null when the folder was never pulled with a record (an older CLI's pull, or
+ * the project's own App), which counts as the person's.
+ */
+export function appUnchangedSincePull(dir: string): boolean | null {
+  let recorded: Record<string, string> | undefined
+  try {
+    recorded = (JSON.parse(readFileSync(join(dir, '.frontera', 'state.json'), 'utf8')) as { pulledFiles?: Record<string, string> }).pulledFiles
+  } catch {
+    return null
+  }
+  if (!recorded || typeof recorded !== 'object' || !Object.keys(recorded).length) return null
+  const now = appSourceHashes(dir)
+  const paths = new Set([...Object.keys(recorded), ...Object.keys(now)])
+  for (const p of paths) if (recorded[p] !== now[p]) return false
+  return true
+}
+
+/** How long one App's unpack (and the repairs right after it) takes at most. */
+const UNPACK_SPAN_MS = 60_000
+/** How long after the lock's `pulledAt` a pull can still be bringing App code (documents come first). */
+const UNPACK_AFTER_PULL_MS = 30 * 60_000
+/** Clock slack between the lock's timestamp and the file system's. */
+const CLOCK_SLACK_MS = 5_000
+
+const bare = (v: unknown) => (typeof v === 'string' ? v.replace(/^v/, '') : undefined)
+
+/**
+ * Whether a project's App folder (`apps/<slug>`) is all as the pull left it.
+ * The folder's own record (`pulledFiles`) decides when there is one. An App
+ * pulled before pulls kept that record has only its lineage (`pulledFrom`,
+ * `pulledVersion`), and the project's `frontera.lock` entry for `app/<slug>`:
+ * when that entry names the same App and version, and every source file was
+ * written in the one unpack (within a minute of each other) that began at
+ * that pull, nothing has been written since and it is as pulled. A file
+ * written later is a change (false). Anything that can't be told (no
+ * lineage, no lock entry, another App or version, code older or much newer
+ * than the pull, as a copy of the folder would be) is null: the person's.
+ */
+export function appPulledAsIs(root: string, appDir: string): boolean | null {
+  const dir = join(root, appDir)
+  const recorded = appUnchangedSincePull(dir)
+  if (recorded !== null) return recorded
+  let state: { pulledFrom?: unknown; pulledVersion?: unknown }
+  try {
+    state = JSON.parse(readFileSync(join(dir, '.frontera', 'state.json'), 'utf8')) as typeof state
+  } catch {
+    return null
+  }
+  if (typeof state.pulledFrom !== 'string' || !state.pulledFrom) return null
+  const entry = readLock(root)?.items[`app/${basename(dir)}`]
+  if (!entry) return null
+  if (entry.id && entry.id !== state.pulledFrom) return null
+  if (entry.version && bare(state.pulledVersion) && bare(entry.version) !== bare(state.pulledVersion)) return null
+  const pulledAt = Date.parse(entry.pulledAt)
+  const files = appSourceFiles(dir)
+  if (!files.length || !Number.isFinite(pulledAt)) return null
+  const first = Math.min(...files.map((f) => f.mtimeMs))
+  const last = Math.max(...files.map((f) => f.mtimeMs))
+  if (first < pulledAt - CLOCK_SLACK_MS || first > pulledAt + UNPACK_AFTER_PULL_MS) return null
+  return last - first <= UNPACK_SPAN_MS
+}
+
+/**
+ * Written into an App folder's top by a typecheck or a build: `tsc
+ * --incremental`'s build info, and what `next build` writes: `next-env.d.ts`,
+ * and `tsconfig.json`, which it reconfigures (its `include` and options) to
+ * what it wants.
+ */
+const isBuildWritten = (name: string) => name.endsWith('.tsbuildinfo') || name === 'next-env.d.ts' || name === 'tsconfig.json'
+
+/**
+ * Keep what an App's own check writes into its folder's top out of the
+ * tree: the build info (`tsconfig.tsbuildinfo`), `next-env.d.ts` and
+ * `tsconfig.json` as they were before it ran. The returned function puts
+ * each back (removes one the check made) and names what it put back. A
+ * pulled App tracks them, and a check is not a change. Only these: a
+ * snapshot of the whole folder would also undo an edit made while the check
+ * ran.
+ */
+export function keepBuildWrittenFiles(dir: string): () => string[] {
+  const before = new Map<string, FileAsWas>()
+  const names = () => (existsSync(dir) ? readdirSync(dir).filter(isBuildWritten) : [])
+  for (const name of names()) {
+    const was = fileAsWas(join(dir, name))
+    // Unreadable: left as the check leaves it.
+    if (was) before.set(name, was)
+  }
+  return () => {
+    const restored: string[] = []
+    for (const name of new Set([...names(), ...before.keys()])) {
+      const path = join(dir, name)
+      const was = before.get(name)
+      try {
+        if (!was) {
+          rmSync(path, { force: true })
+          restored.push(name)
+        } else if (putBackAsWas(path, was)) {
+          // Its time goes back too, so a render before the check is still fresh after it.
+          restored.push(name)
+        }
+      } catch {
+        // Best effort: a file that can't be put back stays as the check left it.
+      }
+    }
+    return restored
+  }
+}

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

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+import { readState, writeState } from '../project'
+import { customAppFolders } from './local-apps'
+
+/**
+ * Custom Apps and the database baseline (`local-db-snapshot.ts`).
+ *
+ * `frontera app deploy` writes the App and its deployment into the runtime's
+ * database, and records the deployment in the App folder
+ * (`.frontera/state.json`). A restore puts back the database as the baseline
+ * holds it, so a deployment made after the baseline is gone from the runtime
+ * while the folder still names it. The baseline keeps the deployment each App
+ * folder named when it was taken; a restore puts that back in the folder, marks
+ * what it lost (`restoredAway`), and the next `frontera local dev` deploys
+ * the App again.
+ */
+
+const STATE = join('.frontera', 'state.json')
+
+/** Each Custom App folder's last deployment from here, by folder (relative to the project): what the runtime should hold. */
+export function appDeployments(root: string): Record<string, string | null> {
+  const out: Record<string, string | null> = {}
+  for (const dir of customAppFolders(root)) {
+    const state = readState(join(root, dir))
+    out[dir] = typeof state.parentVersion === 'string' && state.parentVersion ? state.parentVersion : null
+  }
+  return out
+}
+
+const CROCKFORD = '0123456789abcdefghjkmnpqrstvwxyz'
+
+/** When a deployment was made, from its id (`dpl_` and a ULID, whose first ten characters are the time); null for any other id. */
+export function deploymentTime(id: string): number | null {
+  const m = /^dpl_([0-9a-hjkmnp-tv-z]{26})$/i.exec(id)
+  if (!m) return null
+  let ms = 0
+  for (const ch of m[1]!.slice(0, 10).toLowerCase()) ms = ms * 32 + CROCKFORD.indexOf(ch)
+  return ms
+}
+
+export interface AppLostByRestore {
+  dir: string
+  name: string
+  /** The deployment the folder named, which the restored database does not have. */
+  lost: string
+  /** The deployment the baseline holds for it, when it holds one. */
+  back: string | null
+}
+
+/**
+ * The App folders whose deployment the database being restored does not
+ * have. With the deployments the baseline recorded (`atBaseline`), any folder
+ * naming another one; for a baseline recorded before they were kept, any
+ * deployment made after it was taken (by the time in its id, else by when
+ * the folder recorded it).
+ */
+export function appsLostByRestore(root: string, baseline: { atBaseline?: Record<string, string | null> | null; savedAt: string }): AppLostByRestore[] {
+  const savedAt = Date.parse(baseline.savedAt)
+  const out: AppLostByRestore[] = []
+  for (const [dir, now] of Object.entries(appDeployments(root))) {
+    if (!now) continue
+    if (baseline.atBaseline) {
+      const was = baseline.atBaseline[dir] ?? null
+      if (was !== now) out.push({ dir, name: basename(dir), lost: now, back: was })
+      continue
+    }
+    let at = deploymentTime(now)
+    if (at === null) {
+      try {
+        at = statSync(join(root, dir, STATE)).mtimeMs
+      } catch {
+        at = null
+      }
+    }
+    if (at !== null && Number.isFinite(savedAt) && at > savedAt) out.push({ dir, name: basename(dir), lost: now, back: null })
+  }
+  return out
+}
+
+/** Put the baseline's deployment back in each folder, and mark what the restore took away. */
+export function markAppsLostByRestore(root: string, lost: readonly AppLostByRestore[], restoredAt: string): void {
+  for (const app of lost) {
+    // Deployed again and lost again: the newest deployment lost is the one named.
+    writeState(join(root, app.dir), { parentVersion: app.back, restoredAway: { deployment: app.lost, restoredAt } })
+  }
+}
+
+/** The App folders a restore took a deployment from, still waiting to be deployed again. */
+export function appsAwayByRestore(root: string): Array<{ dir: string; name: string; deployment: string }> {
+  const out: Array<{ dir: string; name: string; deployment: string }> = []
+  for (const dir of customAppFolders(root)) {
+    const path = join(root, dir, STATE)
+    if (!existsSync(path)) continue
+    try {
+      const away = (JSON.parse(readFileSync(path, 'utf8')) as { restoredAway?: { deployment?: unknown } }).restoredAway
+      if (away && typeof away.deployment === 'string') out.push({ dir, name: basename(dir), deployment: away.deployment })
+    } catch {
+      // Unreadable: nothing to say about it.
+    }
+  }
+  return out
+}
+
+/** A restore's line about the Apps it took deployments from; empty when there are none. */
+export function appsLostWords(lost: readonly AppLostByRestore[]): string {
+  if (!lost.length) return ''
+  const names = lost.map((a) => `${a.name} (${a.lost})`).join(', ')
+  return `${lost.length === 1 ? 'the Custom App' : `${lost.length} Custom Apps`} ${names} ${lost.length === 1 ? 'was' : 'were'} deployed after the baseline and ${lost.length === 1 ? 'is' : 'are'} not on the runtime now: the next \`frontera local dev\` deploys ${lost.length === 1 ? 'it' : 'them'} again (or \`frontera app deploy\` in ${lost.map((a) => a.dir).join(', ')})`
+}

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

@@ -0,0 +1,68 @@
+import { join } from 'node:path'
+
+import { readState } from '../project'
+import { customAppFolders } from './local-apps'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Whether the runtime has each Custom App's deployment, as the App folder
+ * names it. The folder's record (`.frontera/state.json`) says what was
+ * deployed from here; only the runtime says whether it is still there (a
+ * restore of its database, a reset, a deployment made to another runtime).
+ * `frontera local status` reads it, so a status that says "Deployed to this
+ * runtime" is one the runtime agrees with.
+ */
+export interface LiveApp {
+  /** The runtime has an App by the folder's id. */
+  app: boolean
+  /** The runtime has the deployment the folder names; null when it was not asked (no App). */
+  deployment: boolean | null
+}
+
+type Get = (path: string) => Promise<{ status: number; body: unknown }>
+
+/** GET with the workspace key, answering status and body; never throws on an answer. */
+export function workspaceGet(serviceUrl: string, creds: Pick<LocalCredentials, 'workspaceKey' | 'organizationId'>, fetcher: typeof fetch = fetch): Get | null {
+  if (!creds.workspaceKey) return null
+  return async (path) => {
+    const res = await fetcher(new URL(path, serviceUrl), { headers: { authorization: `Bearer ${creds.workspaceKey}`, 'x-org-id': creds.organizationId }, signal: AbortSignal.timeout(5_000) })
+    const text = await res.text()
+    let body: unknown = text
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body }
+  }
+}
+
+/**
+ * Each App folder that names a deployment, by folder name, as the runtime
+ * holds it. Null when the runtime could not be asked; a folder the runtime
+ * could not answer for is left out (the folder's record speaks for it).
+ */
+export async function liveAppDeployments(root: string, get: Get | null): Promise<Map<string, LiveApp> | null> {
+  if (!get) return null
+  const out = new Map<string, LiveApp>()
+  for (const dir of customAppFolders(root)) {
+    const state = readState(join(root, dir))
+    const deployment = typeof state.parentVersion === 'string' && state.parentVersion ? state.parentVersion : null
+    if (!deployment || !state.appId) continue
+    const name = dir.split('/').pop()!
+    try {
+      const res = await get(`/v1/platform-apps/${encodeURIComponent(state.appId)}/deployments`)
+      if (res.status === 404) {
+        out.set(name, { app: false, deployment: null })
+        continue
+      }
+      if (res.status !== 200) continue
+      const data = ((res.body as { data?: unknown })?.data ?? res.body) as { deployments?: Array<{ id?: unknown }> } | null
+      const ids = (data?.deployments ?? []).map((d) => d.id)
+      out.set(name, { app: true, deployment: ids.includes(deployment) })
+    } catch {
+      // Not answered: the folder's record speaks for this one.
+    }
+  }
+  return out
+}