@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-app-sdk-paths.ts

@@ -0,0 +1,149 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { APP_SDK_PACKAGES } from '../template'
+import { fileAsWas, putBackAsWas } from './local-app-dev-files'
+import { installedVersion } from './local-app-lock-install'
+import { vendoredShadows } from './local-app-sdk'
+import { isAlive } from './local-state'
+
+/**
+ * A pulled App whose node_modules holds the SDK release its bun.lock records
+ * (`installFromLock`), while its tsconfig.json still sends the SDK's
+ * subpaths (`@frontera-sdk/blueprint/*`) to the older copy under
+ * src/frontera/: TypeScript, `bun test` and Next.js follow `paths` before
+ * node_modules, so the code would still build against the copy.
+ *
+ * Its own check and its dev server run with those paths set aside: tsconfig.json
+ * without them for as long as they run, put back byte for byte after, with
+ * its modification time, so the put-back is no change to the App (a render
+ * made meanwhile stays fresh). The original is kept in the App's
+ * `.frontera/` (never tracked) until it is put
+ * back, so a run that was killed is put back by the next one. Only those
+ * `paths` entries change, and a tsconfig.json edited meanwhile is never
+ * overwritten.
+ */
+
+const RECORD = 'tsconfig.set-aside.json'
+const recordPath = (appRoot: string) => join(appRoot, '.frontera', RECORD)
+const hash = (bytes: Buffer | string) => createHash('sha256').update(bytes).digest('hex')
+
+interface SetAsideRecord {
+  /** tsconfig.json as it was, base64. */
+  original: string
+  /** The hash of tsconfig.json as written without the paths. */
+  written: string
+  paths: string[]
+  /** The process that set them aside: while it runs, another run leaves them set aside. */
+  pid: number
+  /** tsconfig.json's times as it was, put back with it (absent in a record an older CLI wrote). */
+  atimeMs?: number
+  mtimeMs?: number
+}
+
+function readRecord(appRoot: string): SetAsideRecord | null {
+  try {
+    return JSON.parse(readFileSync(recordPath(appRoot), 'utf8')) as SetAsideRecord
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The `compilerOptions.paths` keys that send a package to the SDK copy under
+ * src/frontera/ while node_modules holds the release bun.lock records, with
+ * that release. Empty when there are none, the install came from the copy,
+ * or tsconfig.json isn't plain JSON.
+ */
+export function copyPathsOverRelease(appRoot: string): { keys: string[]; releases: Array<{ pkg: string; version: string }> } {
+  const none = { keys: [], releases: [] }
+  const releases = vendoredShadows(appRoot).filter((s) => installedVersion(appRoot, s.pkg) === s.version)
+  if (!releases.length) return none
+  let config: { compilerOptions?: { paths?: Record<string, string[]> } }
+  try {
+    config = JSON.parse(readFileSync(join(appRoot, 'tsconfig.json'), 'utf8')) as typeof config
+  } catch {
+    return none
+  }
+  const dirs = releases.map((r) => (APP_SDK_PACKAGES as Record<string, { dir: string } | undefined>)[r.pkg]?.dir).filter((d): d is string => !!d)
+  const keys = Object.entries(config.compilerOptions?.paths ?? {})
+    .filter(([, targets]) => Array.isArray(targets) && targets.some((t) => dirs.some((d) => t.replace(/^\.\//, '') === d || t.replace(/^\.\//, '').startsWith(`${d}/`))))
+    .map(([key]) => key)
+  return keys.length ? { keys, releases } : none
+}
+
+export interface SetAside {
+  /** What was set aside, for the output. */
+  line: string
+  /** Put tsconfig.json back; what was done, for the output. */
+  restore(): string
+}
+
+/** Set the copy's `paths` aside in tsconfig.json for a run; null when there are none to set aside. */
+export function setAsideCopyPaths(appRoot: string): SetAside | null {
+  // Another run that is still going (the App's dev server) set them aside: left to it to put back.
+  const running = readRecord(appRoot)
+  if (running && running.pid !== process.pid && isAlive(running.pid)) {
+    return { line: `tsconfig.json: its path${running.paths.length === 1 ? '' : 's'} ${running.paths.join(', ')} to the SDK copy under src/frontera/ already set aside by a run still going (pid ${running.pid}), which puts ${running.paths.length === 1 ? 'it' : 'them'} back`, restore: () => 'tsconfig.json: left to that run to put back' }
+  }
+  // A run that was killed left its set-aside behind: put back first.
+  restoreSetAsideTsconfig(appRoot)
+  const { keys, releases } = copyPathsOverRelease(appRoot)
+  if (!keys.length) return null
+  const path = join(appRoot, 'tsconfig.json')
+  const was = fileAsWas(path)
+  if (!was) return null
+  const original = was.bytes
+  const config = JSON.parse(original.toString('utf8')) as { compilerOptions: { paths: Record<string, string[]> } }
+  for (const key of keys) delete config.compilerOptions.paths[key]
+  const written = `${JSON.stringify(config, null, 2)}\n`
+  mkdirSync(join(appRoot, '.frontera'), { recursive: true })
+  const record: SetAsideRecord = { original: original.toString('base64'), written: hash(written), paths: keys, pid: process.pid, atimeMs: was.atimeMs, mtimeMs: was.mtimeMs }
+  writeFileSync(recordPath(appRoot), `${JSON.stringify(record, null, 2)}\n`)
+  writeFileSync(path, written)
+  const released = releases.map((r) => `${r.pkg} ${r.version}`).join(' and ')
+  return {
+    line: `tsconfig.json: its path${keys.length === 1 ? '' : 's'} ${keys.join(', ')} to the SDK copy under src/frontera/ set aside while it runs, so it builds against the published ${released} that bun.lock records and node_modules holds; put back byte for byte after`,
+    restore: () => restoreSetAsideTsconfig(appRoot) ?? 'tsconfig.json: already as it was',
+  }
+}
+
+/**
+ * tsconfig.json as it is the App's, while a run has its copy paths set aside:
+ * the original kept in `.frontera/`, byte for byte, when tsconfig.json is
+ * still as the set-aside wrote it. Null when nothing is set aside, or
+ * tsconfig.json was edited since (the edit is the App's). What a deploy or a
+ * save packages while the App's dev server runs, so the source it uploads is
+ * never the set-aside.
+ */
+export function tsconfigAsKept(appRoot: string): Buffer | null {
+  const record = readRecord(appRoot)
+  if (!record || typeof record.original !== 'string') return null
+  try {
+    return hash(readFileSync(join(appRoot, 'tsconfig.json'))) === record.written ? Buffer.from(record.original, 'base64') : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Put back a tsconfig.json whose copy paths were set aside: when it is still
+ * as the set-aside wrote it. Edited since, it is left as it is (and said). Null
+ * when nothing was set aside.
+ */
+export function restoreSetAsideTsconfig(appRoot: string): string | null {
+  const record = readRecord(appRoot)
+  if (!record) return null
+  const path = join(appRoot, 'tsconfig.json')
+  const original = Buffer.from(record.original, 'base64')
+  const now = existsSync(path) ? readFileSync(path) : null
+  rmSync(recordPath(appRoot), { force: true })
+  if (now && hash(now) !== record.written && !now.equals(original)) return `tsconfig.json: changed while it ran, so left as it is (its paths ${record.paths.join(', ')} were set aside; put them back if you need them)`
+  // With its modification time as it was: a render made while it was set aside is still of this source (`render-evidence.ts`).
+  const times = typeof record.mtimeMs === 'number' ? { atimeMs: record.atimeMs ?? record.mtimeMs, mtimeMs: record.mtimeMs } : null
+  const already = !!now && now.equals(original)
+  if (times) putBackAsWas(path, { bytes: original, ...times })
+  else if (!already) writeFileSync(path, original)
+  return already ? 'tsconfig.json: already as it was' : 'tsconfig.json: put back byte for byte'
+}

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

@@ -0,0 +1,509 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+
+import vendored from '../vendor/sdk-sources.json'
+import { isRegistryRange, lockedSdkVersions, lockedSpec, recordLockedRanges } from '../app-lock'
+import { unvendorSdkPackageDetail, viteAliasesSdk, type Unvendored } from '../heal'
+import { APP_SDK_PACKAGES, sdkPackageFiles, type AppSdkPackage } from '../template'
+
+/**
+ * An App's `@frontera-sdk/*` packages against the SDK the runtime it is built
+ * for has.
+ *
+ * In image mode that is the CLI's own SDK (the one its skills and scaffold
+ * describe; a scaffold pins `^<sdkVersion>` from npm). In source mode the
+ * local runtime runs from a platform checkout, whose SDK can be ahead of
+ * every npm release: the App then installs the checkout's packages instead.
+ *
+ * How the checkout's SDK reaches an App: each package is packed (`bun pm
+ * pack`, deterministic) into a tarball in the App's own `vendor/frontera-sdk/`,
+ * and the App depends on `file:./vendor/frontera-sdk/<tarball>`. Chosen over
+ * the alternatives because:
+ *  - a `file:`/`link:` dependency on the checkout's folder writes a personal
+ *    absolute path into package.json, and Bun links a folder dependency file
+ *    by file, so imports resolve back into the checkout, outside the App:
+ *    TypeScript and Turbopack (rooted at the App) then can't find the App's
+ *    react or the SDK's sibling package;
+ *  - an overlay copied into node_modules leaves package.json alone, but the
+ *    next `bun install` puts the npm package back;
+ *  - a tarball is extracted into node_modules as a plain copy inside the App,
+ *    survives `bun install`, has a relative path, and is committed with the
+ *    App, so a clone, CI and `app deploy` build the same SDK. Its file name
+ *    carries a hash of its content, so a changed checkout is a new file the
+ *    lockfile notices, and the same checkout packs to the same file.
+ * The packed package.json drops the checkout's devDependencies and scripts,
+ * and names a sibling `@frontera-sdk` package as a peer (the App depends on it
+ * directly), so the App holds one copy of each and one React.
+ */
+
+/** Where an App keeps the checkout's SDK tarballs, relative to the App. */
+export const LOCAL_SDK_DIR = join('vendor', 'frontera-sdk')
+
+export interface SdkDrift {
+  pkg: string
+  installed: string
+  /** The version the App should have: the checkout's in source mode, else the CLI's. */
+  cli: string
+  /** The installed version is older than that. */
+  older: boolean
+  /** Names that SDK exports which the installed package does not. */
+  missing: string[]
+  /** Where the reference SDK is: the platform checkout (source mode) or the CLI's own (npm). */
+  source: 'checkout' | 'npm'
+  /**
+   * The published version the App's bun.lock installed, when package.json
+   * names the SDK copy under src/frontera/ in its place: the copy shadows the
+   * release the code was written against, and `use-local --npm` goes back.
+   */
+  shadowsLocked?: string
+  /**
+   * The App deliberately builds against a published release: package.json
+   * names a registry range and its lockfile installed exactly the version in
+   * node_modules (as `app sdk use-local --npm` leaves it). Said as a note,
+   * never a warning: the App is consistent with itself.
+   */
+  published?: boolean
+}
+
+/** The version a CLI's SDK is: `1.52.28` of `1.52.28-dev`. */
+export const CLI_SDK_VERSION: string = vendored.sdkVersion
+
+/** The local runtime's platform checkout, when it runs in source mode. */
+export interface CheckoutSdk {
+  platformSource: string
+  /** The checkout's SDK version (sdk-core's package.json). */
+  version: string
+}
+
+/** -1, 0 or 1: `a` against `b`, by their numbers (a pre-release tag sorts before its release). */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => {
+    const [core, pre] = v.trim().replace(/^v/, '').split('-', 2) as [string, string | undefined]
+    return { nums: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre }
+  }
+  const x = parse(a)
+  const y = parse(b)
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) {
+    const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0)
+    if (d) return d < 0 ? -1 : 1
+  }
+  if (x.pre && !y.pre) return -1
+  if (!x.pre && y.pre) return 1
+  return 0
+}
+
+/** The names a TypeScript module exports: declarations and `export { a, b as c }` lists. */
+export function exportedNames(source: string): Set<string> {
+  const out = new Set<string>()
+  for (const m of source.matchAll(/^export\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|const|let|var|class|interface|type|enum|abstract\s+class)\s+([A-Za-z_$][\w$]*)/gm)) out.add(m[1]!)
+  for (const m of source.matchAll(/^export\s+(?:type\s+)?\{([^}]*)\}/gm)) {
+    for (const part of m[1]!.split(',')) {
+      const name = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop()?.trim()
+      if (name) out.add(name)
+    }
+  }
+  return out
+}
+
+const readJson = (path: string): Record<string, unknown> | null => {
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? (doc as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The platform checkout an App's runtime runs from: the nearest
+ * `.frontera/local/config.json` above the App that says `mode: source` and
+ * names a `platformSource` with the SDK packages. Null in image mode, or
+ * outside a solution.
+ */
+export function checkoutSdkFor(dir: string): CheckoutSdk | null {
+  let at = dir
+  for (;;) {
+    const config = readJson(join(at, '.frontera', 'local', 'config.json'))
+    if (config) {
+      const source = typeof config.platformSource === 'string' ? config.platformSource : ''
+      if (config.mode !== 'source' || !source) return null
+      // The runtime as it last started, when it has: a runtime started from release images has no checkout SDK,
+      // whatever the config now says, so neither the advice nor `app sdk use-local` reaches for one.
+      const state = readJson(join(at, '.frontera', 'local', 'state.json'))
+      if (state && typeof state.mode === 'string' && state.mode !== 'source') return null
+      const core = readJson(join(source, 'packages', 'sdk-core', 'package.json'))
+      return core && typeof core.version === 'string' ? { platformSource: source, version: core.version } : null
+    }
+    const up = dirname(at)
+    if (up === at) return null
+    at = up
+  }
+}
+
+/** `@frontera-sdk/blueprint` → the checkout's `packages/sdk-blueprint`, when it has it. */
+export function checkoutPackageDir(checkout: CheckoutSdk, pkg: string): string | null {
+  const m = /^@frontera-sdk\/([a-z0-9-]+)$/.exec(pkg)
+  if (!m) return null
+  const dir = join(checkout.platformSource, 'packages', `sdk-${m[1]}`)
+  return existsSync(join(dir, 'package.json')) ? dir : null
+}
+
+/** A package's TypeScript sources, by path relative to its `src/` (tests left out). */
+function sourceFiles(srcDir: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  const walk = (dir: string, rel: string) => {
+    if (!existsSync(dir)) return
+    for (const name of readdirSync(dir).sort()) {
+      const full = join(dir, name)
+      const r = rel ? `${rel}/${name}` : name
+      if (statSync(full).isDirectory()) {
+        if (name !== '__tests__' && name !== 'node_modules') walk(full, r)
+      } else if (/\.tsx?$/.test(name) && !/\.test\.tsx?$/.test(name)) out[r] = readFileSync(full, 'utf8')
+    }
+  }
+  walk(srcDir, '')
+  return out
+}
+
+/** The SDK an App should have, per package: the checkout's sources in source mode, else the CLI's vendored copy. */
+function referenceFiles(pkg: string, checkout: CheckoutSdk | null): Record<string, string> | null {
+  if (checkout) {
+    const dir = checkoutPackageDir(checkout, pkg)
+    return dir ? sourceFiles(join(dir, 'src')) : null
+  }
+  try {
+    return sdkPackageFiles(pkg as AppSdkPackage)
+  } catch {
+    return null
+  }
+}
+
+/** Where a package is installed for an App: its own node_modules, or one above it (a hoisted workspace install). */
+function installedDir(appRoot: string, pkg: string): string | null {
+  let dir = appRoot
+  for (;;) {
+    const candidate = join(dir, 'node_modules', pkg)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+function appDependencies(appRoot: string): Record<string, string> | null {
+  const manifest = readJson(join(appRoot, 'package.json')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | null
+  return manifest ? { ...manifest.devDependencies, ...manifest.dependencies } : null
+}
+
+/**
+ * Each `@frontera-sdk/*` the App depends on and has installed, where it
+ * differs from the SDK its runtime has (`checkout` in source mode, else the
+ * CLI's); [] when none does.
+ */
+export function appSdkDrift(appRoot: string, checkout: CheckoutSdk | null = checkoutSdkFor(appRoot)): SdkDrift[] {
+  const deps = appDependencies(appRoot)
+  if (!deps) return []
+  const want = checkout?.version ?? CLI_SDK_VERSION
+  const shadowed = new Map(vendoredShadows(appRoot).map((v) => [v.pkg, v.version] as const))
+  const locked = lockedSdkVersions(appRoot)
+  const out: SdkDrift[] = []
+  for (const pkg of Object.keys(deps).filter((d) => d.startsWith('@frontera-sdk/')).sort()) {
+    const reference = referenceFiles(pkg, checkout)
+    if (!reference) continue
+    const dir = installedDir(appRoot, pkg)
+    if (!dir) continue
+    const installed = String(readJson(join(dir, 'package.json'))?.version ?? '')
+    if (!installed) continue
+    const missing: string[] = []
+    for (const [rel, content] of Object.entries(reference)) {
+      if (!/\.tsx?$/.test(rel)) continue
+      const theirs = [join(dir, 'src', rel), join(dir, rel)].find((p) => existsSync(p))
+      const have = theirs ? exportedNames(readFileSync(theirs, 'utf8')) : new Set<string>()
+      for (const name of exportedNames(content)) if (!have.has(name)) missing.push(name)
+    }
+    const older = compareVersions(installed, want) < 0
+    const shadows = shadowed.get(pkg)
+    const published = !shadows && isRegistryRange(deps[pkg]) && locked.get(pkg)?.version === installed
+    if (older || missing.length) out.push({ pkg, installed, cli: want, older, missing: [...new Set(missing)].sort(), source: checkout ? 'checkout' : 'npm', ...(shadows ? { shadowsLocked: shadows } : {}), ...(published ? { published: true } : {}) })
+  }
+  return out
+}
+
+/**
+ * What `local check` and `app_dev` say about an App's SDK, one line each; []
+ * when it matches. A warning (`warning: …`) when the App's SDK is a copy or a
+ * `file:` path that is not what its own lockfile installed, or a release its
+ * lockfile does not record; a note (`note: …`) when the App deliberately
+ * builds against a published release its lockfile installed, so the line
+ * never asks to undo `frontera app sdk use-local --npm`.
+ */
+export function sdkDriftLines(app: string, drift: SdkDrift[]): string[] {
+  return drift.map((d) => {
+    if (d.published) {
+      const runs = d.source === 'checkout' ? `the local runtime runs ${d.cli} from the platform checkout` : `this CLI's SDK is ${d.cli}`
+      const switchTo = d.source === 'checkout' ? `\`frontera app sdk use-local\` in ${app} builds against the checkout` : `\`bun add ${d.pkg}@^${d.cli}\` in ${app} moves to it`
+      const extra = d.missing.length ? ` (${d.source === 'checkout' ? 'the checkout' : 'that SDK'} adds ${d.missing.slice(0, 4).join(', ')}${d.missing.length > 4 ? ` and ${d.missing.length - 4} more` : ''})` : ''
+      return `note: ${app} is built against the published ${d.pkg} ${d.installed} (its package.json and lockfile agree); ${runs}${extra}. ${switchTo} if you want that.`
+    }
+    const names = d.missing.length ? ` It lacks ${d.missing.slice(0, 6).join(', ')}${d.missing.length > 6 ? ` and ${d.missing.length - 6} more` : ''}, which ${d.source === 'checkout' ? 'the platform checkout’s SDK' : 'this CLI’s SDK'} and its skills use.` : ''
+    // A copy under src/frontera/ in place of the release its bun.lock installed: back to that release, whatever the runtime.
+    if (d.shadowsLocked) {
+      return `warning: ${app} uses the SDK copy under src/frontera/ for ${d.pkg} (${d.installed}), where its bun.lock installed the published ${d.pkg} ${d.shadowsLocked} its code was written against. To fix, run \`frontera app sdk use-local --npm\` in ${app}: it goes back to that release.`
+    }
+    if (d.source === 'checkout') {
+      // npm has nothing newer than the checkout: the App builds against the checkout's own packages.
+      return `warning: ${app} has ${d.pkg} ${d.installed} installed, not the SDK of the platform checkout the local runtime runs from (${d.cli}).${names} To fix, run \`frontera app sdk use-local\` in ${app}: it packs the checkout's SDK into ${app}/${LOCAL_SDK_DIR} and installs it (\`--npm\` switches back).`
+    }
+    const fix = d.older
+      ? `upgrade it: \`bun add ${d.pkg}@^${d.cli}\` in ${app}`
+      : `install a release that has them (this CLI's is ${d.cli}: \`bun add ${d.pkg}@${d.cli}\` in ${app}), or write against the installed API`
+    return `warning: ${app} has ${d.pkg} ${d.installed} installed, ${d.older ? 'older than' : 'not the same as'} this CLI's SDK ${d.cli}.${names} To fix, ${fix}.`
+  })
+}
+
+/**
+ * Why an App's frozen install refused (package.json and its bun.lock
+ * disagree), and what fixes it, for `app_render`, `app_dev` and `app dev`.
+ * Nothing was installed and the lockfile was left as it is. When package.json
+ * names the SDK copy under src/frontera/ where the lockfile installed a
+ * published release (a pull's repair, or an older scaffold), the copy shadows
+ * the release the code was written against: `app sdk use-local --npm` goes
+ * back to it. Otherwise the person decides which of the two files is right.
+ */
+export function lockMismatchAdvice(appRoot: string): string {
+  const shadowed = vendoredShadows(appRoot)
+  const kept = 'package.json and bun.lock disagree, so nothing was installed and bun.lock was left as it is'
+  if (shadowed.length) {
+    return `${kept}: package.json names the SDK copy under src/frontera/ for ${shadowed.map((v) => v.pkg).join(' and ')}, where bun.lock installed the published ${shadowed.map((v) => `${v.pkg} ${v.version}`).join(' and ')} its code was written against. Run \`frontera app sdk use-local --npm\` in the App to go back to the published SDK, then try again`
+  }
+  return `${kept}. If package.json is right, run \`bun install\` in the App to update bun.lock; if bun.lock is, put package.json back as it was`
+}
+
+/**
+ * Each `@frontera-sdk` package an App's package.json takes from the copy
+ * under src/frontera/ while its lockfile installed a published release, with
+ * that release: the copy shadows what the code was written against.
+ */
+export function vendoredShadows(appRoot: string): Array<{ pkg: string; version: string }> {
+  const deps = (readJson(join(appRoot, 'package.json')) as { dependencies?: Record<string, string> } | null)?.dependencies ?? {}
+  const locked = lockedSdkVersions(appRoot)
+  return Object.entries(deps).flatMap(([pkg, spec]) => (isVendoredSpec(pkg, spec) && locked.has(pkg) ? [{ pkg, version: locked.get(pkg)!.version }] : []))
+}
+
+/**
+ * The shadows an install can take from the App's own SDK copy, as its
+ * package.json says (`bun install --no-save`, which writes neither
+ * package.json nor bun.lock): each copy's folder under src/frontera/ still
+ * holds its package.json. [] when nothing shadows a locked release, or a copy
+ * is gone (only `frontera app sdk use-local --npm` or a pull settles that).
+ */
+export function copyInstallShadows(appRoot: string): Array<{ pkg: string; version: string }> {
+  const shadowed = vendoredShadows(appRoot)
+  if (!shadowed.length) return []
+  const deps = (readJson(join(appRoot, 'package.json')) as { dependencies?: Record<string, string> } | null)?.dependencies ?? {}
+  const present = shadowed.every((s) => existsSync(join(appRoot, String(deps[s.pkg]).replace(/^file:(\.\/)?/, ''), 'package.json')))
+  return present ? shadowed : []
+}
+
+// ── Switching an App to the checkout's SDK, and back ───────────────────────
+
+/** Each `@frontera-sdk` package a package.json names in its dependencies. */
+const sdkDepsOf = (manifest: Record<string, unknown>): string[] => Object.keys((manifest.dependencies as Record<string, string> | undefined) ?? {}).filter((d) => d.startsWith('@frontera-sdk/'))
+
+/**
+ * Pack one checkout package into `<appRoot>/vendor/frontera-sdk/`: its
+ * sources (tests left out), README and LICENSE, and a package.json without
+ * devDependencies or scripts that names its sibling SDK packages as peers.
+ * Returns the tarball's path relative to the App. Older tarballs of the same
+ * package are removed.
+ */
+export function packCheckoutPackage(appRoot: string, checkout: CheckoutSdk, pkg: string): string {
+  const dir = checkoutPackageDir(checkout, pkg)
+  if (!dir) throw new Error(`the platform checkout at ${checkout.platformSource} has no ${pkg} (packages/sdk-…)`)
+  const manifest = readJson(join(dir, 'package.json'))!
+  const stage = mkdtempSync(join(tmpdir(), 'frontera-sdk-pack-'))
+  try {
+    const files = sourceFiles(join(dir, 'src'))
+    for (const [rel, content] of Object.entries(files)) {
+      mkdirSync(dirname(join(stage, 'src', rel)), { recursive: true })
+      writeFileSync(join(stage, 'src', rel), content)
+    }
+    for (const extra of ['README.md', 'LICENSE']) if (existsSync(join(dir, extra))) copyFileSync(join(dir, extra), join(stage, extra))
+    const { devDependencies: _dev, scripts: _scripts, dependencies, peerDependencies, ...rest } = manifest as Record<string, unknown> & { dependencies?: Record<string, string>; peerDependencies?: Record<string, string> }
+    const deps: Record<string, string> = {}
+    const peers: Record<string, string> = { ...(peerDependencies ?? {}) }
+    for (const [name, range] of Object.entries(dependencies ?? {})) {
+      if (name.startsWith('@frontera-sdk/')) peers[name] = '*'
+      else deps[name] = range.startsWith('workspace:') ? String(checkout.version) : range
+    }
+    const packed = { ...rest, ...(Object.keys(deps).length ? { dependencies: deps } : {}), ...(Object.keys(peers).length ? { peerDependencies: peers } : {}), files: ['src', 'README.md', 'LICENSE'] }
+    writeFileSync(join(stage, 'package.json'), `${JSON.stringify(packed, null, 2)}\n`)
+    const hash = createHash('sha256')
+    for (const rel of Object.keys(files).sort()) hash.update(rel).update('\0').update(files[rel]!).update('\0')
+    hash.update(JSON.stringify(packed))
+    const short = pkg.replace(/^@frontera-sdk\//, '')
+    const name = `frontera-sdk-${short}-${String(manifest.version)}-${hash.digest('hex').slice(0, 8)}.tgz`
+    const outDir = join(appRoot, LOCAL_SDK_DIR)
+    mkdirSync(outDir, { recursive: true })
+    // The App's own package manager packs it, as it installs it.
+    const res = spawnSync('bun', ['pm', 'pack', '--ignore-scripts', '--quiet', '--filename', join(outDir, name)], { cwd: stage, encoding: 'utf8' })
+    if (res.status !== 0 || !existsSync(join(outDir, name))) throw new Error(`packing ${pkg} failed: ${(res.stderr || res.stdout || '').trim().split('\n').pop() ?? `exit ${res.status}`}`)
+    for (const old of readdirSync(outDir)) if (old !== name && old.startsWith(`frontera-sdk-${short}-`) && old.endsWith('.tgz')) rmSync(join(outDir, old))
+    return relative(appRoot, join(outDir, name)).split('\\').join('/')
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+}
+
+/** Is a package.json dependency spec one of this App's checkout tarballs? */
+export const isCheckoutSpec = (spec: string | undefined) => !!spec && /^file:(\.\/)?vendor\/frontera-sdk\/frontera-sdk-[A-Za-z0-9.-]+\.tgz$/.test(spec)
+
+export interface SdkSwitch {
+  /** Each SDK package and the dependency spec now in package.json; `locked`: the release its lockfile installed, when the spec pins it. */
+  packages: Array<{ pkg: string; spec: string; locked?: string }>
+  /**
+   * What the switch itself changed in the App, by path relative to it, before
+   * the caller's install: so the command can say every file it wrote or deleted.
+   */
+  changes: SdkSwitchChanges
+}
+
+export interface SdkSwitchChanges {
+  /** package.json, when its @frontera-sdk dependencies were rewritten. */
+  manifest: boolean
+  /** The lockfile whose root workspace ranges were rewritten to match (resolutions untouched), when one was. */
+  lockfile?: string
+  /** Each copy under src/frontera/ deleted, with its files and the tsconfig.json paths to it that went too. */
+  unvendored: Unvendored[]
+  /** Each checkout tarball written under vendor/frontera-sdk/ (`use-local`). */
+  tarballsWritten: string[]
+  /** Each checkout tarball deleted from vendor/frontera-sdk/: an older pack (`use-local`), or all of them (`--npm`). */
+  tarballsRemoved: string[]
+}
+
+/** The checkout tarballs an App holds, by path relative to it. */
+function tarballsIn(appRoot: string): string[] {
+  const dir = join(appRoot, LOCAL_SDK_DIR)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((n) => n.endsWith('.tgz')).sort().map((n) => `${LOCAL_SDK_DIR.split('\\').join('/')}/${n}`)
+}
+
+/**
+ * One line per change, for the command's text: what was written, and every
+ * file deleted, by name. [] when nothing changed.
+ */
+export function sdkSwitchChangeLines(changes: SdkSwitchChanges): string[] {
+  const lines: string[] = []
+  if (changes.manifest) lines.push('package.json: the @frontera-sdk dependencies above')
+  if (changes.lockfile) lines.push(`${changes.lockfile}: the root workspace's ranges for them, to match (resolutions untouched)`)
+  for (const u of changes.unvendored) {
+    if (u.tsconfigPaths.length) lines.push(`tsconfig.json: removed the path${u.tsconfigPaths.length === 1 ? '' : 's'} ${u.tsconfigPaths.join(', ')} (pointing at ${u.dir}/)`)
+  }
+  for (const t of changes.tarballsWritten) lines.push(`wrote ${t}`)
+  for (const u of changes.unvendored) {
+    if (u.files.length) lines.push(`deleted ${u.dir}/, the SDK copy (${u.files.length} file${u.files.length === 1 ? '' : 's'}: ${u.files.join(', ')})`)
+  }
+  const emptied = [...new Set(changes.unvendored.flatMap((u) => (u.parentRemoved ? [u.parentRemoved] : [])))]
+  for (const p of emptied) lines.push(`deleted ${p}/, left empty`)
+  for (const t of changes.tarballsRemoved) lines.push(`deleted ${t}`)
+  return lines
+}
+
+function writeDependencies(appRoot: string, specs: Record<string, string>): void {
+  const path = join(appRoot, 'package.json')
+  const text = readFileSync(path, 'utf8')
+  const manifest = JSON.parse(text) as Record<string, unknown> & { dependencies?: Record<string, string> }
+  manifest.dependencies = { ...(manifest.dependencies ?? {}), ...specs }
+  const indent = /^(\s+)"/m.exec(text)?.[1] ?? '  '
+  writeFileSync(path, `${JSON.stringify(manifest, null, indent)}\n`)
+}
+
+/**
+ * Point the App's `@frontera-sdk` dependencies at the checkout's packages:
+ * each one it names (and each sibling those need, sdk-core for blueprint) is
+ * packed into `vendor/frontera-sdk/` and its spec becomes
+ * `file:./vendor/frontera-sdk/<tarball>`. Writes package.json; the caller
+ * installs.
+ */
+export function useCheckoutSdk(appRoot: string, checkout: CheckoutSdk): SdkSwitch {
+  const manifest = readJson(join(appRoot, 'package.json'))
+  if (!manifest) throw new Error(`${appRoot} has no package.json`)
+  const wanted = new Set(sdkDepsOf(manifest).filter((pkg) => checkoutPackageDir(checkout, pkg)))
+  // A package the App's SDK packages need from each other, held by the App itself so there is one copy.
+  for (const pkg of [...wanted]) {
+    const own = readJson(join(checkoutPackageDir(checkout, pkg)!, 'package.json'))
+    for (const dep of own ? sdkDepsOf(own) : []) if (checkoutPackageDir(checkout, dep)) wanted.add(dep)
+  }
+  if (!wanted.size) throw new Error('the App depends on no @frontera-sdk package the checkout has')
+  const before = new Set(tarballsIn(appRoot))
+  const specs: Record<string, string> = {}
+  for (const pkg of [...wanted].sort()) specs[pkg] = `file:./${packCheckoutPackage(appRoot, checkout, pkg)}`
+  const manifestBefore = readFileSync(join(appRoot, 'package.json'), 'utf8')
+  writeDependencies(appRoot, specs)
+  const after = tarballsIn(appRoot)
+  return {
+    packages: Object.entries(specs).map(([pkg, spec]) => ({ pkg, spec })),
+    changes: {
+      manifest: readFileSync(join(appRoot, 'package.json'), 'utf8') !== manifestBefore,
+      unvendored: [],
+      // The same checkout packs to the same file: only a new name is a write.
+      tarballsWritten: after.filter((t) => !before.has(t)),
+      tarballsRemoved: [...before].filter((t) => !after.includes(t)),
+    },
+  }
+}
+
+/** Is a spec the copy a pull's repair (or an old scaffold) vendored under src/frontera/? */
+export const isVendoredSpec = (pkg: string, spec: string | undefined) => {
+  const dir = (APP_SDK_PACKAGES as Record<string, { dir: string } | undefined>)[pkg]?.dir
+  return !!spec && !!dir && spec.replace(/^file:(\.\/)?/, '') === dir && spec.startsWith('file:')
+}
+
+/**
+ * Back to npm: every checkout tarball spec, and every copy vendored under
+ * src/frontera/ (a pulled App's repair), becomes a published range: the one
+ * the App's own lockfile installed when it has one (the SDK its code was
+ * written against), else `^<version>` (the CLI's SDK range, as the scaffold
+ * pins). `vendor/frontera-sdk/` and the vendored copies (with their tsconfig
+ * paths) are removed. Writes package.json; the caller installs.
+ */
+export function useNpmSdk(appRoot: string, version: string = CLI_SDK_VERSION): SdkSwitch {
+  const manifest = readJson(join(appRoot, 'package.json')) as { dependencies?: Record<string, string> } | null
+  if (!manifest) throw new Error(`${appRoot} has no package.json`)
+  const locked = lockedSdkVersions(appRoot)
+  const specs: Record<string, string> = {}
+  const fromLock: Record<string, string> = {}
+  const unvendored: Unvendored[] = []
+  for (const [pkg, spec] of Object.entries(manifest.dependencies ?? {})) {
+    if (!pkg.startsWith('@frontera-sdk/') || !(isCheckoutSpec(spec) || isVendoredSpec(pkg, spec))) continue
+    // A Vite App aliases its vendored copy: that is how it resolves the SDK (`frontera app sdk sync` refreshes it).
+    if (isVendoredSpec(pkg, spec) && viteAliasesSdk(appRoot, pkg as AppSdkPackage)) continue
+    const lockedAt = locked.get(pkg)
+    specs[pkg] = lockedAt ? lockedSpec(lockedAt) : `^${version}`
+    if (lockedAt) fromLock[pkg] = lockedAt.version
+    if (isVendoredSpec(pkg, spec)) {
+      const removed = unvendorSdkPackageDetail(appRoot, pkg as AppSdkPackage)
+      if (removed && (removed.files.length || removed.tsconfigPaths.length)) unvendored.push(removed)
+    }
+  }
+  if (Object.keys(specs).length) writeDependencies(appRoot, specs)
+  // The lockfile's own record of the ranges follows, so it and package.json agree before the install.
+  const lockRecorded = recordLockedRanges(appRoot, Object.fromEntries(Object.keys(fromLock).map((pkg) => [pkg, specs[pkg]!])))
+  const tarballsRemoved = tarballsIn(appRoot)
+  rmSync(join(appRoot, LOCAL_SDK_DIR), { recursive: true, force: true })
+  const vendorDir = join(appRoot, 'vendor')
+  if (existsSync(vendorDir) && readdirSync(vendorDir).length === 0) rmSync(vendorDir, { recursive: true })
+  return {
+    packages: Object.entries(specs).map(([pkg, spec]) => ({ pkg, spec, ...(fromLock[pkg] ? { locked: fromLock[pkg] } : {}) })),
+    changes: {
+      manifest: Object.keys(specs).length > 0,
+      ...(lockRecorded ? { lockfile: existsSync(join(appRoot, 'bun.lock')) ? 'bun.lock' : 'package-lock.json' } : {}),
+      unvendored,
+      tarballsWritten: [],
+      tarballsRemoved,
+    },
+  }
+}