@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/harness.ts

@@ -25,6 +25,16 @@ description: Use when reading or changing anything on the Frontera platform from
 never out of date — read it instead of guessing, and instead of trusting this
 file for syntax.
 
+## In a project with the Frontera MCP server
+
+A project made by \`frontera local\` registers the \`frontera\` MCP server
+(\`.mcp.json\`). When its tools are offered (\`mcp__frontera__*\` in Claude
+Code), use them for the local loop instead of the shell: \`status\`,
+\`apply\`, \`test_run\`, \`logs\`, \`read_file_schema\` and the documentation
+tools. The person approves the server once, where every shell command can
+ask again. Run \`frontera local …\` only when the tools aren't offered, or
+for a step that has no tool (\`frontera local start\`, \`frontera local check\`).
+
 ## Preflight: know which customer you are about to change
 
 \`\`\`bash
@@ -63,7 +73,10 @@ Two fields decide whether a call can work at all:
   key: set \`FRONTERA_TOKEN\` to the session token and \`FRONTERA_API_URL\` (or
   pass \`--api-url\`). The CLI refuses an \`sk-ws-\`/\`sk-org-\` key on those
   before sending anything; \`frontera login\` stores keys only, so it cannot
-  supply the session.
+  supply the session. On a project's local runtime, never fetch a person's
+  session: \`--as <persona>\` runs \`action available\`, \`submit\`,
+  \`approve\` and \`reject\` as a local persona (\`--as submitter\`,
+  \`--as <approver>\`; \`frontera local status\` lists them).
 - \`available\` — \`false\` means the verb is named but unbuilt, and
   \`unavailableReason\` says why. Pick another route rather than retrying.
 
@@ -126,7 +139,7 @@ Pass \`--json\` for machine-readable output. The contract:
 | 0 | success | continue |
 | 1 | transient or remote failure | retry, then report |
 | 2 | usage, input, or profile selection | fix the command |
-| 3 | conflict — someone changed it first | re-fetch, reapply, retry |
+| 3 | conflict or refusal — someone changed it first, or the record's state refuses it | re-read, change the input or the record, then send it again; never retry it unchanged |
 | 4 | auth or permission | different credential, or ask an admin |
 
 Errors carry a \`hint\` naming the next command. Read it.
@@ -192,8 +205,9 @@ frontera blueprint instance <apiName> <pk>
   app or agent sees at runtime. Anything absent here is absent for them too.
 
 \`--where\` takes \`<property>:<value>\` or \`<property>:<op>:<value>\` for one
-condition; pass a JSON where-node for anything with and/or in it, or
-\`--file\` a whole query document for unions and link traversals.
+condition, and \`<property>:in:<a>,<b>\` (also \`notIn\`, \`between\`) for a list;
+repeat it for conditions that must all hold. Pass a JSON where-node for an
+or/not, or \`--file\` a whole query document for unions and link traversals.
 
 ## Configuring an agent
 
@@ -239,14 +253,13 @@ means someone else changed it: re-read and retry, never force.
 ## Building an app
 
 \`\`\`bash
-frontera app init <name>        # scaffold — installs with public npm only
-bun install
+frontera app init <name>        # Next.js static export — installs with public npm only
+cd <name>
 frontera blueprint list         # what data this workspace actually has
-frontera app add <component>    # registry source into the project
-bun run typecheck               # vite build does NOT type-check
-bun run build                   # the deploy gate — must succeed
-frontera app deploy --no-promote
-frontera app promote <version>
+frontera app dev                # the App against real data, with a short-lived token
+bun run check                   # typecheck, tests and build: the gate
+frontera app deploy --build     # build, then a preview deployment with its link
+frontera app promote <deployment>
 \`\`\`
 
 Read \`frontera blueprint list\` and \`frontera blueprint get <apiName>\` before
@@ -254,19 +267,24 @@ designing against data. What they return is the slice this workspace is granted,
 which is exactly what the app will be able to query at runtime — so anything
 absent there will be absent for the app too.
 
-\`src/frontera/\` in a scaffolded project is the SDK, copied in as source so the
-project installs anywhere. Read it; never edit it, never rewrite an
-\`@frontera-sdk/…\` import to a relative path, never add \`@frontera-sdk/*\` to
-\`package.json\`. The project's own \`using-frontera-sdk\` skill has the detail.
-
-\`bun run dev\` serves the app, but opening \`/\` directly renders "This app runs
-inside Frontera" instead of mounting: the handshake refuses an unknown parent,
-which is correct, not a broken build.
-
-Open **\`/dev-host.html\`** instead. It frames the app and plays the host side of
-the bridge, so the app mounts and reads real data. That is the URL to screenshot
-or click through when verifying your work — a screenshot of \`/\` is a screenshot
-of the refusal panel.
+The SDK depends on how the App was made:
+
+- **Next.js (the default).** \`@frontera-sdk/core\` and \`@frontera-sdk/blueprint\`
+  (and \`@frontera-sdk/agents\` when used) are public npm packages in
+  \`package.json\`, kept at the release \`frontera app init\` wrote and updated
+  with the package manager. Never copy SDK source into \`src/\`. Open the App
+  through \`frontera app dev\`: it serves on \`http://127.0.0.1:<port>\` and
+  hands the page its session; never write that session into \`.env\`.
+- **Vite (legacy, \`--framework react\`).** \`src/frontera/\` is the SDK, copied
+  in as source. Read it; never edit it, never rewrite an \`@frontera-sdk/…\`
+  import to a relative path, and never add \`@frontera-sdk/*\` to
+  \`package.json\` there. \`frontera app sdk sync\` refreshes the copy. Opening
+  \`/\` renders "This app runs inside Frontera" (the handshake refuses an
+  unknown parent); open **\`/dev-host.html\`** instead, which frames the app and
+  plays the host side of the bridge.
+
+The project's own skills (\`.agents/skills/\`) have the detail for its
+framework.
 `
 
 export const AGENTS_MD = `# Frontera

package/src/heal.ts

@@ -45,9 +45,10 @@
  * CLI (`src/vendor/sdk-sources.json`).
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
+import { lockedSdkVersions, lockedSpec, recordLockedRanges } from './app-lock'
 import {
   APP_SDK_PACKAGES,
   LEGACY_SDK_ALIASES,
@@ -102,6 +103,10 @@ export function healProject(dir: string): HealResult {
 
   const name = typeof manifest.name === 'string' && manifest.name ? manifest.name : 'app'
   let manifestChanged = false
+  // What the App's own lockfile installed from the registry: the SDK its code was written against.
+  const locked = lockedSdkVersions(dir)
+  // The specs restored to a locked release, recorded in the lockfile too so the two agree.
+  const restored: Record<string, string> = {}
 
   // Packages a legacy tree needs declared under their CURRENT name as well, so
   // the vendored copy resolves the siblings it imports internally.
@@ -131,6 +136,18 @@ export function healProject(dir: string): HealResult {
       if (typeof spec !== 'string' || !UNRESOLVABLE.test(spec)) continue
 
       const pkg = currentSdkPackage(dep)
+      // The lockfile installed a published version: that is the SDK the code was checked against, so
+      // the App goes back to it rather than to a copy of another SDK (a pulled App's typecheck depends on it).
+      const lockedAt = pkg && dep === pkg ? locked.get(pkg) : undefined
+      if (lockedAt) {
+        deps[dep] = lockedSpec(lockedAt)
+        restored[dep] = deps[dep]
+        repairs.push(`restored ${dep} to ${deps[dep]}, the published release its bun.lock installed (was ${truncate(spec)})`)
+        manifestChanged = true
+        // A copy left under src/frontera/ would still win through tsconfig paths: it goes.
+        if (unvendorSdkPackage(dir, pkg!)) repairs.push(`removed the vendored copy in ${APP_SDK_PACKAGES[pkg!].dir} and its tsconfig path`)
+        continue
+      }
       if (pkg) {
         // Already pointing at the copy in this tree — that is the shape this
         // function produces, so re-pulling must not rewrite it back over
@@ -188,6 +205,10 @@ export function healProject(dir: string): HealResult {
     // still carry a stale copy, which is the ordinary state of every app
     // scaffolded before the SDK grew a module.
     if (vendorCurrent(dir, pkg) && (declares(manifest, specifier) || specifier === pkg)) continue
+    // Declared with a published range (`^1.43.10`): the package manager installs it, and the code was written against
+    // that release. Vendoring this CLI's copy over it swaps the SDK under the code (a pulled Next.js App's case).
+    const spec = manifest.dependencies?.[specifier] ?? manifest.devDependencies?.[specifier]
+    if (typeof spec === 'string' && !UNRESOLVABLE.test(spec)) continue
     vendorSdkPackage(dir, pkg)
     manifest.dependencies ??= {}
     manifest.dependencies[specifier] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
@@ -225,6 +246,8 @@ export function healProject(dir: string): HealResult {
   }
 
   if (manifestChanged) writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  // The lockfile's record of what package.json asks for follows, so a frozen install takes the restored package.json.
+  if (recordLockedRanges(dir, restored)) repairs.push(`recorded ${Object.entries(restored).map(([d, s]) => `${d} ${s}`).join(' and ')} in the lockfile, which already installed that release`)
 
   // Point the editor at the vendored copy directly. Without this TypeScript
   // reaches it through the `file:` link instead and reports every diagnostic
@@ -246,6 +269,94 @@ export function healProject(dir: string): HealResult {
   return { repairs }
 }
 
+/**
+ * Take a vendored SDK package out of an App that installs the published one:
+ * its directory under src/frontera/ and the tsconfig `paths` entries that
+ * point at it (which would otherwise resolve imports to the copy instead of
+ * node_modules). True when anything was removed. A Vite App whose config
+ * aliases the copy keeps it: the alias is how it resolves the SDK.
+ */
+/** Does the App's Vite config alias the vendored copy (a scaffolded Vite App resolves the SDK that way)? */
+export function viteAliasesSdk(dir: string, pkg: AppSdkPackage): boolean {
+  const rel = APP_SDK_PACKAGES[pkg].dir
+  return ['vite.config.ts', 'vite.config.js', 'vite.config.mts'].some((f) => {
+    try {
+      return readFileSync(join(dir, f), 'utf8').includes(rel)
+    } catch {
+      return false
+    }
+  })
+}
+
+export function unvendorSdkPackage(dir: string, pkg: AppSdkPackage): boolean {
+  const removed = unvendorSdkPackageDetail(dir, pkg)
+  return !!removed && (removed.files.length > 0 || removed.tsconfigPaths.length > 0)
+}
+
+/** What taking a vendored SDK package out of an App removed: the copy's files, and the tsconfig paths to it. */
+export interface Unvendored {
+  /** The copy's directory, relative to the App (`src/frontera/blueprint`). */
+  dir: string
+  /** Each file deleted with it, relative to that directory, sorted. */
+  files: string[]
+  /** The directory above it, when it was left empty and deleted too (`src/frontera`). */
+  parentRemoved?: string
+  /** Each `compilerOptions.paths` key removed from tsconfig.json because it pointed at the copy. */
+  tsconfigPaths: string[]
+}
+
+/** `unvendorSdkPackage`, saying what it removed; null when the App's Vite config aliases the copy, so it is kept. */
+export function unvendorSdkPackageDetail(dir: string, pkg: AppSdkPackage): Unvendored | null {
+  const rel = APP_SDK_PACKAGES[pkg].dir
+  if (viteAliasesSdk(dir, pkg)) return null
+  const out: Unvendored = { dir: rel, files: [], tsconfigPaths: [] }
+  if (existsSync(join(dir, rel))) {
+    out.files = filesUnder(join(dir, rel))
+    rmSync(join(dir, rel), { recursive: true, force: true })
+    const parent = dirname(join(dir, rel))
+    try {
+      if (readdirSync(parent).length === 0) {
+        rmSync(parent, { recursive: true })
+        out.parentRemoved = dirname(rel)
+      }
+    } catch {
+      // Gone already.
+    }
+  }
+  const tsconfig = join(dir, 'tsconfig.json')
+  try {
+    const config = JSON.parse(readFileSync(tsconfig, 'utf8')) as { compilerOptions?: { paths?: Record<string, string[]> } }
+    const paths = config.compilerOptions?.paths
+    if (paths) {
+      for (const [key, targets] of Object.entries(paths)) {
+        if (Array.isArray(targets) && targets.some((t) => t.replace(/^\.\//, '').startsWith(`${rel}/`) || t.replace(/^\.\//, '') === rel)) {
+          delete paths[key]
+          out.tsconfigPaths.push(key)
+        }
+      }
+      if (out.tsconfigPaths.length) writeFileSync(tsconfig, `${JSON.stringify(config, null, 2)}\n`)
+    }
+  } catch {
+    // No tsconfig, or JSON with comments: left as it is.
+  }
+  return out
+}
+
+/** Every file under a directory, by its path relative to it, sorted. */
+function filesUnder(root: string): string[] {
+  const out: string[] = []
+  const walk = (at: string, rel: string) => {
+    for (const name of readdirSync(at).sort()) {
+      const path = join(at, name)
+      const r = rel ? `${rel}/${name}` : name
+      if (statSync(path).isDirectory()) walk(path, r)
+      else out.push(r)
+    }
+  }
+  walk(root, '')
+  return out
+}
+
 function isSdkPackage(dep: string): dep is AppSdkPackage {
   return (SDK_PACKAGE_NAMES as string[]).includes(dep)
 }
@@ -380,7 +491,7 @@ function vendorSdkPackage(dir: string, pkg: AppSdkPackage): void {
  */
 export function vendoredManifest(pkg: AppSdkPackage, files: string[]): Record<string, unknown> {
   const exports: Record<string, unknown> = { './package.json': './package.json' }
-  for (const rel of files.sort()) {
+  for (const rel of files.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     if (!/\.tsx?$/.test(rel)) continue
     exports[`./${rel.replace(/\.tsx?$/, '')}`] = { types: `./${rel}`, import: `./${rel}` }
   }

package/src/kit.ts

@@ -135,7 +135,7 @@ export interface RenderedProject {
 /** One source, two native projections — Codex reads neither host's other tree. */
 export function renderKit(kit: KitAssets = KIT): RenderedProject {
   const generated: Record<string, string> = {}
-  for (const rel of Object.keys(kit.assets).sort()) {
+  for (const rel of Object.keys(kit.assets).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     const content = kit.assets[rel]!
     if (kit.hosts.codex) generated[join('.agents', 'skills', rel)] = content
     if (kit.hosts.claudeCode) generated[join('.claude', 'skills', rel)] = content

package/src/local/fix-words.ts

@@ -0,0 +1,12 @@
+/**
+ * A message and what fixes it, said as one sentence pair: "… the type
+ * allows. Fix: change …". The message keeps its own end mark when it has
+ * one (a runtime's error often ends with a period), so the join never says
+ * "allows.. Fix:"; a trailing comma, colon or semicolon gives way to the
+ * period. Without a fix, the message as it is.
+ */
+export function withFix(message: string, fix: string | null | undefined): string {
+  const said = message.trim().replace(/[\s,;:]+$/, '')
+  if (!fix?.trim()) return said
+  return `${said}${/[.!?…]$/.test(said) ? '' : '.'} Fix: ${fix.trim()}`
+}