@frontera-sdk/cli 0.1.0

package/src/heal.ts

@@ -0,0 +1,418 @@
+/**
+ * Repair a working tree that was packaged before the scaffold could package
+ * itself.
+ *
+ * ## The defect
+ *
+ * `frontera app pull` promises "a working copy". For an app stored by an older
+ * toolchain it did not deliver one: the `package.json` in storage declares
+ *
+ * ```json
+ * "@frontera-sdk/blueprint": "file:/Users/…/worktrees/…/packages/sdk-blueprint"
+ * ```
+ *
+ * — an absolute path into a git worktree on one developer's laptop that no
+ * longer exists. `bun install` fails on every machine, including the one that
+ * authored it. There is no `src/frontera/`, and `tsconfig` carries only `@/*`,
+ * so nothing else resolves `@frontera-sdk/*` either.
+ *
+ * An agent handed that tree cannot install, cannot build, and cannot verify.
+ * The session this was written from spent roughly 42 operations working around
+ * it and finished by hand-writing a fake `@frontera-sdk/blueprint` — which then
+ * produced the screenshots it presented as evidence. Every number in them came
+ * from a linear congruential generator the agent wrote twenty minutes earlier.
+ *
+ * So this runs on pull, not as a separate `frontera app doctor` the model has
+ * to know to reach for. A repair the caller must discover is a repair that does
+ * not happen.
+ *
+ * ## How it repairs
+ *
+ * The vendored SDK is written into `src/frontera/<pkg>/`, the same layout
+ * `frontera app init` produces, and each directory is given a `package.json`
+ * whose `exports` map its subpaths. The app's `@frontera-sdk/*` dependency is then
+ * pointed at that directory with `file:`.
+ *
+ * That last step is what lets this touch no code. Aliases are the scaffold's
+ * mechanism and they are fine when the scaffold writes `vite.config.ts` itself
+ * — but a pulled project's Vite config is arbitrary TypeScript, and a healer
+ * that rewrites arbitrary TypeScript is a healer that eventually eats someone's
+ * config. A `file:` dependency is resolved by the package manager, honoured by
+ * both Vite and `tsc`, and expressed entirely in JSON. A scaffolded app keeps
+ * its aliases; they point at the same files and win first.
+ *
+ * Nothing here reaches the network: the SDK source is already compiled into the
+ * CLI (`src/vendor/sdk-sources.json`).
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import {
+  APP_SDK_PACKAGES,
+  LEGACY_SDK_ALIASES,
+  currentSdkPackage,
+  devHostHtml,
+  sdkPackageFiles,
+  type AppSdkPackage,
+} from './template'
+
+/**
+ * Dependency specs a package manager cannot resolve away from the machine that
+ * wrote them. `workspace:` needs this monorepo; `file:`/`link:`/`portal:` need
+ * a path that survived; `git+ssh` needs a key a sandbox does not have.
+ */
+const UNRESOLVABLE = /^(file|link|portal|workspace|git\+ssh):/
+
+const SDK_PACKAGE_NAMES = Object.keys(APP_SDK_PACKAGES) as AppSdkPackage[]
+
+export interface HealResult {
+  /** One line per repair, in the order they were applied. Empty = nothing to do. */
+  repairs: string[]
+}
+
+interface PackageJson {
+  name?: string
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  [key: string]: unknown
+}
+
+/**
+ * Bring a pulled working tree up to something that installs and builds.
+ *
+ * Idempotent: a tree already in good shape gets no repairs and no writes, so
+ * re-pulling does not churn files. Never throws — a project too unusual to
+ * repair is left exactly as it was, because a half-repaired tree is worse than
+ * an honestly broken one.
+ */
+export function healProject(dir: string): HealResult {
+  const repairs: string[] = []
+
+  const manifestPath = join(dir, 'package.json')
+  let manifest: PackageJson | null = null
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as PackageJson
+  } catch {
+    // No manifest, or not JSON. Not a project this CLI knows how to repair —
+    // and `pull` has already put the files on disk, which is the part the
+    // caller asked for.
+    return { repairs }
+  }
+
+  const name = typeof manifest.name === 'string' && manifest.name ? manifest.name : 'app'
+  let manifestChanged = false
+
+  // Packages a legacy tree needs declared under their CURRENT name as well, so
+  // the vendored copy resolves the siblings it imports internally.
+  const needCurrentScope = new Set<AppSdkPackage>()
+
+  // Legacy spellings this particular app uses. Only these get tsconfig paths:
+  // adding both spellings unconditionally reports a repair on a HEALTHY
+  // scaffolded app, which breaks the idempotency this function promises.
+  const legacyInUse = new Map<string, AppSdkPackage>()
+
+  // ── SDK dependencies, in either scope ───────────────────────────────────────
+  //
+  // A stored app declares whatever scope was current when it was packaged, and
+  // every app in storage predates `@frontera-sdk`. Matching only the new scope
+  // is matching only trees that do not need repairing.
+  //
+  // A legacy name keeps its key and is pointed at the vendored directory. The
+  // key is what the app's own `from '@frontera/blueprint/hooks'` resolves
+  // through, and a `file:` dependency installs under its key regardless of the
+  // name in the target's manifest — so one vendored copy serves both spellings
+  // and no source file has to be rewritten.
+  for (const field of ['dependencies', 'devDependencies'] as const) {
+    const deps = manifest[field]
+    if (!deps || typeof deps !== 'object') continue
+    for (const [dep, spec] of Object.entries(deps)) {
+      if (!dep.startsWith('@frontera-sdk/') && !dep.startsWith('@frontera/')) continue
+      if (typeof spec !== 'string' || !UNRESOLVABLE.test(spec)) continue
+
+      const pkg = currentSdkPackage(dep)
+      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
+        // itself and report a repair that did nothing.
+        if (spec === `file:./${APP_SDK_PACKAGES[pkg].dir}` && vendorPresent(dir, pkg)) continue
+        vendorSdkPackage(dir, pkg)
+        deps[dep] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
+        const under = dep === pkg ? '' : ` (legacy name, now ${pkg})`
+        repairs.push(`vendored ${dep} into ${APP_SDK_PACKAGES[pkg].dir}${under} (was ${truncate(spec)})`)
+
+        // The vendored source imports its sibling by the CURRENT name, so a
+        // legacy tree needs that spelling installed too or the copy cannot
+        // resolve its own imports.
+        if (dep !== pkg) {
+          needCurrentScope.add(pkg)
+          legacyInUse.set(dep, pkg)
+        }
+      } else {
+        // Not vendorable. Leaving a dead `file:` spec is the difference between
+        // a tree that installs and one that does not, so it goes — but the two
+        // reasons are not the same and the repair line should not pretend they
+        // are.
+        //
+        // The CLI is genuinely not a build input: it lives on PATH, and an app
+        // never imports it. Anything else here (`@frontera-sdk/automation`) is a
+        // real package that this app may well import, and dropping it trades a
+        // failing `bun install` for a failing `bun run build`. Rewriting it to a
+        // version range is the actual repair and is not available yet — nothing
+        // is on the registry — so the honest move is to say what was lost.
+        const isCli = dep.endsWith('/cli')
+        delete deps[dep]
+        repairs.push(
+          isCli
+            ? `dropped ${dep} — the CLI is on PATH, not a build input (was ${truncate(spec)})`
+            : `dropped ${dep} — unresolvable and not vendorable; anything importing it will not build (was ${truncate(spec)})`,
+        )
+      }
+      manifestChanged = true
+    }
+  }
+
+  // An app can also IMPORT the SDK without declaring it — the monorepo used to
+  // resolve `@frontera-sdk/*` for free, so a project authored there installs
+  // nowhere else and says nothing about why.
+  //
+  // A SCAFFOLDED app looks the same from the manifest and is not broken: it
+  // resolves through tsconfig `paths` and a matching Vite alias into the
+  // directory it already carries. `vendorPresent` is what tells them apart, and
+  // getting it wrong would write a second, differently-wired copy of the SDK
+  // into a project that has one — which is how a project ends up with two
+  // Reacts.
+  const imported = importedSdkPackages(join(dir, 'src'))
+  for (const { specifier, pkg } of imported) {
+    if (declares(manifest, specifier) || (specifier === pkg && vendorPresent(dir, pkg))) continue
+    vendorSdkPackage(dir, pkg)
+    manifest.dependencies ??= {}
+    manifest.dependencies[specifier] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
+    manifestChanged = true
+    const under = specifier === pkg ? '' : ` (legacy name, now ${pkg})`
+    repairs.push(`vendored ${specifier} into ${APP_SDK_PACKAGES[pkg].dir}${under} (imported but never declared)`)
+    if (specifier !== pkg) {
+      needCurrentScope.add(pkg)
+      legacyInUse.set(specifier, pkg)
+    }
+  }
+
+  // The vendored source's own imports are written in the current scope. A tree
+  // that only ever mentions the old one still needs those resolvable, or the
+  // copy this function just wrote cannot import its own sibling.
+  for (const pkg of needCurrentScope) {
+    if (declares(manifest, pkg)) continue
+    vendorSdkPackage(dir, pkg)
+    manifest.dependencies ??= {}
+    manifest.dependencies[pkg] = `file:./${APP_SDK_PACKAGES[pkg].dir}`
+    manifestChanged = true
+    repairs.push(`declared ${pkg} (the vendored copy imports it under its current name)`)
+  }
+
+  // The SDK's `config.ts` reads `process.env` behind a guard, so vendoring it
+  // into a project without `@types/node` turns `bun run typecheck` — one of the
+  // two commands the shipped skill says to run before claiming done — red, with
+  // four errors inside code the author was told not to edit. An agent that sees
+  // that goes and fixes the SDK.
+  if (vendored(dir) && !manifest.devDependencies?.['@types/node'] && !manifest.dependencies?.['@types/node']) {
+    manifest.devDependencies ??= {}
+    manifest.devDependencies['@types/node'] = '^22'
+    manifestChanged = true
+    repairs.push('added @types/node (the vendored SDK type-checks a `process` guard)')
+  }
+
+  if (manifestChanged) writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+
+  // Point the editor at the vendored copy directly. Without this TypeScript
+  // reaches it through the `file:` link instead and reports every diagnostic
+  // twice — once under `src/`, once under `node_modules/` — for one file.
+  // Vite is unaffected either way: it resolves the link to the same real path.
+  const tsconfigRepair = ensureTsconfigPaths(dir, legacyInUse)
+  if (tsconfigRepair) repairs.push(tsconfigRepair)
+
+  // ── the dev host ──────────────────────────────────────────────────────────
+  // `bun run dev` serves the app at `/`, where `connectToHost` refuses an
+  // unknown parent and renders a panel. Without this page there is no way to
+  // see the app running at all, and a screenshot of `/` proves nothing.
+  const devHost = join(dir, 'dev-host.html')
+  if (!existsSync(devHost)) {
+    writeFileSync(devHost, devHostHtml(name))
+    repairs.push('wrote dev-host.html (open /dev-host.html, never /)')
+  }
+
+  return { repairs }
+}
+
+function isSdkPackage(dep: string): dep is AppSdkPackage {
+  return (SDK_PACKAGE_NAMES as string[]).includes(dep)
+}
+
+/** Does this tree already carry the SDK's source where the scaffold puts it? */
+function vendorPresent(dir: string, pkg: AppSdkPackage): boolean {
+  return existsSync(join(dir, APP_SDK_PACKAGES[pkg].dir))
+}
+
+/** Does it carry any of them? */
+function vendored(dir: string): boolean {
+  return SDK_PACKAGE_NAMES.some((pkg) => vendorPresent(dir, pkg))
+}
+
+/**
+ * Add the two `@frontera-sdk/*` path mappings, keeping everything already there.
+ *
+ * Returns a repair line, or null when there was nothing to do — including when
+ * `tsconfig.json` is missing or is JSON with comments, which `JSON.parse`
+ * refuses. Skipping is the right answer there: the `file:` dependency already
+ * makes the imports resolve, so this is a duplicate-diagnostics fix, and a
+ * healer that reformats someone's commented config to win it is a bad trade.
+ */
+function ensureTsconfigPaths(dir: string, legacyInUse: Map<string, AppSdkPackage>): string | null {
+  const path = join(dir, 'tsconfig.json')
+  let config: { compilerOptions?: { paths?: Record<string, string[]> } }
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+    config = JSON.parse(raw) as typeof config
+  } catch {
+    return null
+  }
+  if (!config.compilerOptions) return null
+
+  const paths = config.compilerOptions.paths ?? {}
+  let added = false
+  // Current names always; legacy names only where this app uses them, so an
+  // editor follows a legacy import to the vendored source instead of through the
+  // `file:` link and reporting every diagnostic twice.
+  const spellings: Array<[string, AppSdkPackage]> = [
+    ...SDK_PACKAGE_NAMES.map((pkg) => [pkg, pkg] as [string, AppSdkPackage]),
+    ...legacyInUse,
+  ]
+  for (const [specifier, pkg] of spellings) {
+    const key = `${specifier}/*`
+    if (paths[key] || !vendorPresent(dir, pkg)) continue
+    paths[key] = [`./${APP_SDK_PACKAGES[pkg].dir}/*`]
+    added = true
+  }
+  if (!added) return null
+
+  config.compilerOptions.paths = paths
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`)
+  return 'mapped @frontera-sdk/* in tsconfig paths'
+}
+
+function declares(manifest: PackageJson, dep: string): boolean {
+  return Boolean(manifest.dependencies?.[dep] ?? manifest.devDependencies?.[dep])
+}
+
+function truncate(spec: string): string {
+  return spec.length > 60 ? `${spec.slice(0, 57)}…` : spec
+}
+
+/**
+ * Write one SDK package's source into the project, plus the `package.json`
+ * that makes the directory resolvable as `@frontera-sdk/<pkg>`.
+ *
+ * Overwrites unconditionally. The vendored copy is not the author's code — it
+ * is the SDK, and the shipped skill says so ("Read it freely; do not edit it").
+ * A tree being healed has already proven it cannot resolve the real thing, so
+ * preferring whatever partial copy is on disk would mean preferring the fake
+ * one an agent wrote to get past this.
+ */
+function vendorSdkPackage(dir: string, pkg: AppSdkPackage): void {
+  const target = join(dir, APP_SDK_PACKAGES[pkg].dir)
+  const sources = sdkPackageFiles(pkg)
+
+  for (const [rel, content] of Object.entries(sources)) {
+    const full = join(target, rel)
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+  }
+
+  writeFileSync(
+    join(target, 'package.json'),
+    `${JSON.stringify(vendoredManifest(pkg, Object.keys(sources)), null, 2)}\n`,
+  )
+}
+
+/**
+ * The manifest for a vendored SDK directory.
+ *
+ * `exports` is derived from the files actually written rather than copied from
+ * the real package, so a module added to the SDK cannot be vendored-but-
+ * unreachable. Subpaths point at `.ts`/`.tsx` directly: the consumer is always
+ * a bundler or `tsc`, never Node, and shipping a build step into every healed
+ * app to produce sources it would immediately re-transpile buys nothing.
+ */
+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()) {
+    if (!/\.tsx?$/.test(rel)) continue
+    exports[`./${rel.replace(/\.tsx?$/, '')}`] = { types: `./${rel}`, import: `./${rel}` }
+  }
+  return {
+    name: pkg,
+    version: '0.0.0-vendored',
+    private: true,
+    // The terms the copied source arrives under. `LICENSE` sits beside it,
+    // written from the same vendored set as the modules.
+    license: 'Apache-2.0',
+    type: 'module',
+    exports,
+  }
+}
+
+/** Which SDK packages this project's own source imports. */
+function importedSdkPackages(srcDir: string): Array<{ specifier: string; pkg: AppSdkPackage }> {
+  // Keyed by the specifier the app actually wrote, because that is what has to
+  // resolve. Scanning for current names only would miss every stored app, all
+  // of which import the old scope.
+  const found = new Map<string, AppSdkPackage>()
+  const candidates = [...SDK_PACKAGE_NAMES as string[], ...Object.keys(LEGACY_SDK_ALIASES)]
+  for (const file of walk(srcDir)) {
+    if (!/\.(ts|tsx|js|jsx)$/.test(file)) continue
+    // Skip the vendored copies themselves: `@frontera-sdk/blueprint` imports
+    // `@frontera-sdk/core/client`, and reading that as an app import would make
+    // the scan self-fulfilling.
+    if (file.includes(`${join('src', 'frontera')}`)) continue
+    let text: string
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    for (const specifier of candidates) {
+      if (!text.includes(`'${specifier}/`) && !text.includes(`"${specifier}/`)) continue
+      found.set(specifier, currentSdkPackage(specifier)!)
+    }
+  }
+  // blueprint re-exports types from core, so an app that imports only the former
+  // still needs both on disk — in whichever spelling it is already using.
+  for (const [specifier, pkg] of [...found]) {
+    if (pkg !== '@frontera-sdk/blueprint') continue
+    const core = specifier.startsWith('@frontera/') ? '@frontera/sdk-core' : '@frontera-sdk/core'
+    if (!found.has(core)) found.set(core, '@frontera-sdk/core')
+  }
+  return [...found].map(([specifier, pkg]) => ({ specifier, pkg }))
+}
+
+function walk(dir: string, out: string[] = []): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === 'dist' || entry.startsWith('.')) continue
+    const full = join(dir, entry)
+    let stats
+    try {
+      stats = statSync(full)
+    } catch {
+      continue
+    }
+    if (stats.isDirectory()) walk(full, out)
+    else out.push(full)
+  }
+  return out
+}

package/src/help.ts

@@ -0,0 +1,128 @@
+/**
+ * Layout and colour for help text.
+ *
+ * Help was a `padEnd(46)` and a summary, which meant every description longer
+ * than the remaining columns wrapped at the terminal edge — mid-word, back to
+ * column zero, so `frontera app add`'s summary read "…from the registry i /
+ * to this project". Codex and Claude Code both wrap with a hanging indent and
+ * are legible at 80 columns; Bun does not, and its own `--help` breaks the same
+ * way. This follows the ones that work.
+ *
+ * Colour is opt-out via NO_COLOR, and off entirely when stdout is not a TTY —
+ * an agent capturing `--help` gets clean text with no escape sequences to strip.
+ */
+
+const MIN_WIDTH = 60
+const MAX_WIDTH = 100
+
+export function terminalWidth(): number {
+  const columns = process.stdout.columns
+  if (!columns || Number.isNaN(columns)) return 80
+  return Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, columns))
+}
+
+function colorEnabled(): boolean {
+  // https://no-color.org — any value, including empty, disables.
+  if (process.env.NO_COLOR !== undefined) return false
+  if (process.env.FORCE_COLOR !== undefined) return true
+  return Boolean(process.stdout.isTTY)
+}
+
+function paint(code: string, close: string) {
+  return (text: string): string => (colorEnabled() ? `\x1b[${code}m${text}\x1b[${close}m` : text)
+}
+
+export const bold = paint('1', '22')
+export const dim = paint('2', '22')
+/** Command names, matching the accent Bun and Codex use for the same thing. */
+export const accent = paint('36', '39')
+
+/** Visible width, ignoring any escape sequences already applied. */
+function visibleLength(text: string): number {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[\d+m/g, '').length
+}
+
+/**
+ * Greedy wrap. Words longer than the line (a URL, a long flag) are left whole
+ * and allowed to overflow rather than broken — a split identifier cannot be
+ * copied, which is the same reason `table.ts` never truncates an id.
+ */
+export function wrap(text: string, width: number): string[] {
+  if (width <= 0) return [text]
+  const lines: string[] = []
+  let current = ''
+
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    if (!current) current = word
+    else if (current.length + 1 + word.length <= width) current += ` ${word}`
+    else {
+      lines.push(current)
+      current = word
+    }
+  }
+  if (current) lines.push(current)
+  return lines.length > 0 ? lines : ['']
+}
+
+export interface DefinitionOptions {
+  /** Leading spaces before the term. */
+  indent?: number
+  /** Spaces between the term column and the description column. */
+  gap?: number
+  width?: number
+  /**
+   * Terms wider than this get their description on the following line rather
+   * than pushing every description off the right edge.
+   */
+  maxTerm?: number
+}
+
+/**
+ * A term/description list — the shape every section of every help page uses.
+ *
+ * The description column is computed from the widest term that fits, and
+ * continuation lines align under it, so a wrapped summary still reads as one
+ * block instead of drifting back to the margin.
+ */
+export function definitions(
+  rows: ReadonlyArray<readonly [string, string]>,
+  options: DefinitionOptions = {},
+): string[] {
+  const indent = options.indent ?? 2
+  const gap = options.gap ?? 2
+  const width = options.width ?? terminalWidth()
+  const maxTerm = options.maxTerm ?? 34
+
+  const fitting = rows.map(([term]) => visibleLength(term)).filter((n) => n <= maxTerm)
+  const termWidth = fitting.length > 0 ? Math.max(...fitting) : maxTerm
+  const descColumn = indent + termWidth + gap
+  const descWidth = Math.max(20, width - descColumn)
+
+  const out: string[] = []
+  for (const [term, description] of rows) {
+    const pad = ' '.repeat(indent)
+    if (!description) {
+      out.push(`${pad}${term}`)
+      continue
+    }
+
+    const lines = wrap(description, descWidth)
+    if (visibleLength(term) > termWidth) {
+      // Too wide to share a line — the description starts underneath.
+      out.push(`${pad}${term}`)
+      for (const line of lines) out.push(`${' '.repeat(descColumn)}${line}`)
+      continue
+    }
+
+    const padding = ' '.repeat(termWidth - visibleLength(term) + gap)
+    out.push(`${pad}${term}${padding}${lines[0]}`)
+    for (const line of lines.slice(1)) out.push(`${' '.repeat(descColumn)}${line}`)
+  }
+  return out
+}
+
+/** A section heading, matching the `Usage` / `Commands` style of codex. */
+export function heading(text: string): string {
+  return bold(text)
+}