@nifrajs/cli 2.14.1 → 3.2.0

package/src/cli.ts

@@ -9,8 +9,9 @@
  *
  * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
  */
-import { existsSync, readFileSync } from "node:fs"
+import { existsSync, readFileSync, realpathSync } from "node:fs"
 import { resolve } from "node:path"
+import { fileURLToPath } from "node:url"
 import { inProcessClient } from "@nifrajs/client"
 import {
   type CreateWebAppOptions,
@@ -21,6 +22,7 @@ import {
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.ts"
+import { applyEnvFiles, takeEnvFileFlags } from "./env-file.ts"
 import { type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
@@ -46,6 +48,23 @@ export interface Flags {
   readonly allowDuplicateIdentity: boolean
 }
 
+/** Forward a re-exec'd Bun child's output without relying on Windows inheriting a pipe-of-a-pipe. */
+async function forwardChildOutput(
+  stream: ReadableStream<Uint8Array>,
+  sink: { write(chunk: Uint8Array): unknown },
+): Promise<void> {
+  const reader = stream.getReader()
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) return
+      await sink.write(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
 const HELP = `nifra - zero-config dev/build/start for a nifra app
 
 Usage:
@@ -188,10 +207,16 @@ routes/ from the current directory. Run from your project root.
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).
 
+Env: \`--env-file <path>\` works on EVERY command and may be repeated (later files win). Commands that
+reflect your app import it, so an app that validates its environment at module scope needs that
+environment present - without it the app aborts before nifra runs a single check. A variable already
+set in the process environment is never overwritten by a file.
+  e.g. \`nifra check --env-file .env.local\`
+
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.14.1"
+const CLI_VERSION = "3.2.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -275,6 +300,11 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
         )
       }
       const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd, app.configPath)
+      // Bun 1.4 on Windows may discard the script-relative portion of argv when `--config` is
+      // present. Keep a second, authenticated copy of the user vector in the child's environment so
+      // the configured process cannot silently fall back to `nifra`'s help and exit 0. The launch token
+      // is still the proof boundary; these arguments are only a transport, never authorization.
+      const childCliArgv = [...cliArgv()]
       const child = Bun.spawn(
         [
           process.execPath,
@@ -288,14 +318,27 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
           // One flag per condition. `--conditions=a,b` is accepted and matches nothing: Bun takes the
           // whole string as a single condition name, so the comma form fails silently.
           ...(app.framework.conditions ?? []).map((condition) => `--conditions=${condition}`),
-          ...process.argv.slice(1),
+          // Reuse the actual loaded module rather than trusting either runtime's reconstructed
+          // `argv[1]` spelling. This also works when a package-bin shim launches the CLI. `cliArgv()`
+          // is important here: Bun 1.4 on Windows can omit the script from Bun.argv, making the
+          // command start at index 1 instead of index 2. Slicing at a fixed index would silently drop
+          // `dev`, causing the child to load this module and exit successfully without starting it.
+          fileURLToPath(import.meta.url),
+          ...childCliArgv,
         ],
         {
-          stdio: ["inherit", "inherit", "inherit"],
+          // On Windows, inheriting the parent's already-piped stdout/stderr can make a nested Bun
+          // process exit successfully without exposing either its banner or its error. Use explicit
+          // pipes and forward them from this process instead; the caller still observes one CLI stream,
+          // while the child gets real handles it can write to on every platform.
+          stdin: "inherit",
+          stdout: "pipe",
+          stderr: "pipe",
           env: {
             ...process.env,
             NIFRA_BUN_DEV_TOKEN: launchToken,
             NIFRA_BUN_DEV_DEPTH: String(depth + 1),
+            NIFRA_BUN_DEV_ARGS: JSON.stringify(childCliArgv),
             // The child is the process that renders, so it is the one that needs dev-shaped runtimes.
             // A library ships its dev build behind the `development` export condition with a `NODE_ENV`
             // fallback for resolvers that set no conditions - which is Bun's runtime, where SSR runs,
@@ -307,11 +350,28 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
           },
         },
       )
+      const forwarded = Promise.all([
+        forwardChildOutput(child.stdout as ReadableStream<Uint8Array>, Bun.stdout),
+        forwardChildOutput(child.stderr as ReadableStream<Uint8Array>, Bun.stderr),
+      ])
       const forward = (): void => child.kill("SIGINT")
       process.on("SIGINT", forward)
       process.on("SIGTERM", forward)
-      process.exit(await child.exited)
+      try {
+        const [code] = await Promise.all([child.exited, forwarded])
+        process.exitCode = code
+      } finally {
+        process.off("SIGINT", forward)
+        process.off("SIGTERM", forward)
+      }
+      return
     }
+    // The verified child no longer needs the transport or its launch proof. Remove both from the
+    // long-lived dev process so command-line values (which may include an env-file path) are not
+    // inherited by an app-spawned subprocess or exposed through its environment diagnostics.
+    delete process.env.NIFRA_BUN_DEV_ARGS
+    delete process.env.NIFRA_BUN_DEV_TOKEN
+    delete process.env.NIFRA_BUN_DEV_DEPTH
     // SSR runs in THIS process, on Bun's runtime - a different loader from the dev-server bundler the
     // bunfig above configures. Both halves have to agree, so the runtime gets the same transforms:
     //
@@ -474,6 +534,8 @@ async function assertFreshWorkspaceDists(cwd: string): Promise<void> {
   let rootPackage: Record<string, unknown>
   try {
     rootPackage = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>
+    // @nifra-gate-reviewed: not a security gate. An unreadable/non-JSON package.json is a separate
+    // build problem; returning here skips the freshness check rather than masking a denial.
   } catch {
     return // an unreadable/!JSON package.json is a separate problem; don't mask it as a stale-dist failure
   }
@@ -661,10 +723,42 @@ export function assureBundleRequested(argv: readonly string[]): boolean {
   )
 }
 
+/**
+ * A command that reflects the project imports it, and an app that validates its environment at module
+ * scope calls `process.exit` from inside that import. Nothing is throwable at that point, so the whole
+ * output is the app's own abort message with no hint that a nifra command triggered it. Name the cause
+ * on the way out and point at the flag that supplies the environment.
+ */
+function installReflectionExitHint(): (command: string | undefined) => void {
+  let inFlight: string | undefined
+  process.on("exit", (code) => {
+    if (inFlight === undefined || code === 0) return
+    process.stderr.write(
+      `\n[nifra] \`nifra ${inFlight}\` reflects this project by importing it, and the import exited ` +
+        `with code ${code} before the command produced a result - the message above came from your app, not nifra.\n` +
+        `        If it is the app's environment validation, supply the environment and re-run:\n` +
+        `        nifra ${inFlight} --env-file .env.local\n`,
+    )
+  })
+  return (command) => {
+    inFlight = command
+  }
+}
+
 async function main(): Promise<void> {
-  const argv = Bun.argv.slice(2)
+  const { argv: rawArgv, files: envFiles } = takeEnvFileFlags(cliArgv())
+  // Applied before any command runs: a reflecting command imports the app on its first await, and the
+  // app reads its environment at module scope, so the variables must already be in place by then.
+  if (envFiles.length > 0) await applyEnvFiles(process.cwd(), envFiles)
+  const argv = rawArgv
   const command = argv[0]
   if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+    if (command === undefined && isBunDevReexecChild()) {
+      throw new Error(
+        "[nifra] the configured Bun dev child lost its command arguments; refusing to serve without " +
+          "the verified dev configuration. Re-run `nifra dev`.",
+      )
+    }
     console.log(HELP)
     return
   }
@@ -707,11 +801,33 @@ async function main(): Promise<void> {
     )
     return
   }
+  // `frontend` prints the client-side footgun catalog (the human head of `nifra_frontend`).
+  // Project-independent and static. `nifra frontend` for the index, `nifra frontend vue "lost reactivity"`
+  // to filter by adapter and/or symptom (either arg may be omitted; an adapter is recognized by name).
+  if (command === "frontend") {
+    const { renderFrontendResult, parseAdapter } = await import("./frontend-guidance.ts")
+    const first = argv[1]
+    const maybeAdapter = parseAdapter(first)
+    const adapter = maybeAdapter === undefined ? undefined : first
+    const symptom = (maybeAdapter === undefined ? argv.slice(1) : argv.slice(2))
+      .filter((a) => !a.startsWith("-"))
+      .join(" ")
+    console.log(
+      renderFrontendResult({
+        adapter,
+        symptom: symptom.length > 0 ? symptom : undefined,
+      }),
+    )
+    return
+  }
   const catalogSpec = command === undefined ? undefined : findCommandSpec(command)
   if (catalogSpec?.transports.includes("cli")) {
+    const markReflecting = installReflectionExitHint()
     try {
       const input = bindCommandArgv(catalogSpec, argv.slice(1))
+      markReflecting(command)
       const output = await catalogSpec.run(input, { cwd: process.cwd(), cliVersion: CLI_VERSION })
+      markReflecting(undefined)
       const asRecord = output as unknown as Record<string, unknown>
       const wantsJson = asRecord.json === true || argv.includes("--json")
       if (wantsJson) {
@@ -723,6 +839,9 @@ async function main(): Promise<void> {
       if (catalogSpec.success !== undefined && !catalogSpec.success(output, input))
         process.exitCode = 1
     } catch (err) {
+      // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
+      // hint stays reserved for the case where the process died inside the app import.
+      markReflecting(undefined)
       console.error(formatCliError(err))
       process.exitCode = 1
     }
@@ -809,11 +928,173 @@ async function main(): Promise<void> {
   else await start(app, flags)
 }
 
+/**
+ * Bun 1.4 on Windows can report `import.meta.main === false` for a module launched after a `--config`
+ * re-exec, even though that module is the process entry. Treat the runtime flag as authoritative when
+ * it is true, but recover from that false negative by comparing the runtime's entry path with this file.
+ * The comparison is deliberately realpath-based so a package-bin symlink is accepted while an imported
+ * copy of the CLI remains inert (tests import `parseFlags` from this module).
+ */
+function isMainModule(): boolean {
+  if (import.meta.main) return true
+  const target = fileURLToPath(import.meta.url)
+  /**
+   * Bun's `--config`/`--conditions` flags can sit before the script in the child argv. `argv[1]` is
+   * therefore a runtime flag on Bun 1.4/Windows, not the entry module. `Bun.main` is the authoritative
+   * runtime answer when available; the bounded argv fallback covers Bun releases that do not expose it.
+   * Only non-flag entries are considered and every match must resolve to this exact file, so an
+   * unresolved or arbitrary flag can never turn an imported CLI module into a running CLI.
+   */
+  const bunMain = (Bun as unknown as { main?: unknown }).main
+  const argvEntries = (argv: readonly string[]): string[] => {
+    const entries: string[] = []
+    for (const value of argv.slice(1)) {
+      if (value === "--") break
+      if (value.startsWith("-")) continue
+      entries.push(value)
+      // The script is before the user's command/flags. A small bound keeps a caller's arbitrary
+      // arguments from becoming an entry-point probe while covering a config plus a few conditions.
+      if (entries.length === 4) break
+    }
+    return entries
+  }
+  const entries = [
+    ...(typeof bunMain === "string" ? [bunMain] : []),
+    ...argvEntries(Bun.argv),
+    ...argvEntries(process.argv),
+  ]
+  const canonical = (value: string): Set<string> => {
+    const paths = new Set<string>()
+    const add = (path: string): void => {
+      const slashed = path
+        .replaceAll("\\", "/")
+        .replace(/^\/\/\?\/UNC\//i, "//")
+        .replace(/^\/\/\?\//, "")
+      paths.add(process.platform === "win32" ? slashed.toLowerCase() : slashed)
+    }
+    try {
+      add(resolve(value))
+    } catch {
+      return paths
+    }
+    for (const resolver of [realpathSync.native, realpathSync]) {
+      try {
+        add(resolver(value))
+      } catch {
+        // A virtual/synthetic argv entry has no realpath; it is not safe evidence of main-ness.
+      }
+    }
+    return paths
+  }
+  const targetPaths = canonical(target)
+  for (const entry of entries) {
+    if (entry !== "" && [...canonical(entry)].some((path) => targetPaths.has(path))) return true
+  }
+  return false
+}
+
+/**
+ * Bun 1.4 on Windows can omit the script path from both argv vectors when a TS file is launched by
+ * `Bun.spawn`. The command token is a safe last-resort discriminator: a test importing this module
+ * sees test-file paths and runner flags, not an exact Nifra command, while a direct CLI invocation
+ * has one of the manual or catalogued command names below.
+ */
+function isCliCommandToken(value: string): boolean {
+  return (
+    value === "dev" ||
+    value === "build" ||
+    value === "start" ||
+    value === "mcp" ||
+    value === "init-agents" ||
+    value === "upgrade" ||
+    value === "help" ||
+    value === "--help" ||
+    value === "-h" ||
+    value === "--version" ||
+    value === "-v" ||
+    findCommandSpec(value) !== undefined
+  )
+}
+
+function findCliCommand(values: readonly string[]): number {
+  // Most Bun/Node argv vectors reserve index 0 for the runtime and index 1 for the script. Bun 1.4
+  // on Windows can omit the script for a directly spawned TS entry, leaving the command at index 0.
+  // Accept that one exact-token shape while keeping arbitrary imported-module argv inert.
+  return values.findIndex((value) => isCliCommandToken(value))
+}
+
+function cliArgv(): readonly string[] {
+  const reexec = reexecCliArgv()
+  if (reexec !== undefined) return reexec
+  for (const values of [Bun.argv, process.argv]) {
+    const commandIndex = findCliCommand(values)
+    if (commandIndex >= 0) return values.slice(commandIndex)
+  }
+  return Bun.argv.slice(2)
+}
+
+/**
+ * Recover the original command vector when Bun's Windows `--config` launch drops it from both public
+ * argv arrays. This is deliberately narrow: only a positive re-exec marker can enable the channel, the
+ * first item must be a real Nifra command, and malformed/oversized data is ignored so an inherited
+ * environment can never turn an imported CLI module into an arbitrary command runner.
+ */
+function reexecCliArgv(): readonly string[] | undefined {
+  if (!isBunDevReexecChild()) return undefined
+  const encoded = process.env.NIFRA_BUN_DEV_ARGS
+  if (encoded === undefined || encoded.length > 64 * 1024) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(encoded)
+  } catch {
+    return undefined
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > 128) return undefined
+  if (
+    !parsed.every(
+      (value) => typeof value === "string" && value.length <= 16 * 1024 && !value.includes("\0"),
+    )
+  ) {
+    return undefined
+  }
+  const command = parsed[0]
+  if (typeof command !== "string") return undefined
+  return isCliCommandToken(command) ? (parsed as string[]) : undefined
+}
+
+function hasCliCommandToken(): boolean {
+  return findCliCommand(Bun.argv) >= 0 || findCliCommand(process.argv) >= 0
+}
+
+/**
+ * Bun 1.4/Windows can load the explicit script after a `--config` re-exec while reporting neither a
+ * usable `import.meta.main` nor the script in its public argv vectors. The child still carries the
+ * parent-generated launch proof and a positive depth; accepting that narrow marker lets it enter
+ * `main()`, where `consumeLaunchToken()` remains the fail-closed gate before the configured server can
+ * run. A forged marker only causes the normal token-mismatch relaunch/error path - it cannot bypass the
+ * boundary plugin proof.
+ */
+function isBunDevReexecChild(): boolean {
+  const depth = Number(process.env.NIFRA_BUN_DEV_DEPTH)
+  return (
+    process.env.NIFRA_BUN_DEV_TOKEN !== undefined &&
+    process.env.NIFRA_BUN_DEV_TOKEN !== "" &&
+    Number.isSafeInteger(depth) &&
+    depth > 0
+  )
+}
+
 // Only run the CLI when invoked as the entry (`bun cli.ts …`), not when a test imports it for the
-// exported `parseFlags`. `import.meta.main` is true only for the process's entry module.
-if (import.meta.main) {
-  main().catch((err) => {
+// exported `parseFlags`.
+if (isMainModule() || isBunDevReexecChild() || hasCliCommandToken()) {
+  // Keep the entry module alive until the async CLI has completed. Bun 1.4 on Windows can otherwise
+  // terminate a process created by Bun.spawn while its first dynamic import is pending, leaving an
+  // exit-0 child with no output. Imported test modules never enter this branch, so the CLI's top-level
+  // await cannot start a server merely because a test imports a helper from this file.
+  try {
+    await main()
+  } catch (err) {
     console.error(formatCliError(err))
     process.exitCode = 1
-  })
+  }
 }

package/src/command-catalog.ts

@@ -21,6 +21,7 @@ import type { LoadedApp } from "./load.ts"
 import type { ManifestEmitCommandResult } from "./manifest-tool.ts"
 import { collectPortResult, type PortResult, renderReport } from "./port.ts"
 import type { ReplayResult } from "./replay.ts"
+import type { StylexMigrationResult } from "./stylex-migrate.ts"
 import {
   collectProjectWorkGraph,
   type ProjectWorkGraphResult,
@@ -298,6 +299,12 @@ interface ContextInput {
   readonly dir?: string | undefined
 }
 
+interface OpenApiInput {
+  readonly format?: "json" | "yaml" | undefined
+  readonly path?: string | undefined
+  readonly dir?: string | undefined
+}
+
 interface DoctorInput {
   readonly json?: boolean | undefined
   readonly autoFix?: boolean | undefined
@@ -312,6 +319,14 @@ interface FixInput {
   readonly dir?: string | undefined
 }
 
+interface MigrateInput {
+  readonly from: "tailwind"
+  readonly to: "stylex"
+  readonly write?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface SnapshotInput {
   readonly out?: string | undefined
   readonly json?: boolean | undefined
@@ -373,11 +388,20 @@ interface ContextCommandOutput {
   readonly ok: true
   readonly text: string
 }
+interface OpenApiCommandOutput {
+  readonly ok: true
+  readonly format: "json" | "yaml"
+  readonly text: string
+}
 interface FixCommandOutput {
   readonly ok: boolean
   readonly changed: readonly string[]
+  /** Recipes that refused, with the reason. A recipe that cannot act says so here instead of
+   * aborting the run or - worse - reporting nothing at all. */
+  readonly failed: readonly { readonly code: string; readonly reason: string }[]
   readonly diagnostics: readonly unknown[]
 }
+interface MigrateCommandOutput extends StylexMigrationResult {}
 interface SnapshotCommandOutput {
   readonly ok: true
   readonly file: string
@@ -569,6 +593,24 @@ const CONTEXT_SCHEMA = input<ContextInput>(
   },
 )
 
+const OPENAPI_SCHEMA = input<OpenApiInput>(
+  objectSchema({
+    format: { type: "string", enum: ["json", "yaml"] },
+    path: { type: "string" },
+    dir: { type: "string" },
+  }),
+  (value) => {
+    const raw = withDir(record(value))
+    if (raw.format !== undefined && raw.format !== "json" && raw.format !== "yaml")
+      throw new TypeError("format must be json or yaml")
+    return {
+      format: (raw.format ?? "json") as "json" | "yaml",
+      path: optionalString(raw.path, "path"),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 const DOCTOR_SCHEMA = input<DoctorInput>(
   objectSchema({
     json: { type: "boolean" },
@@ -599,6 +641,32 @@ const FIX_SCHEMA = input<FixInput>(
   },
 )
 
+const MIGRATE_SCHEMA = input<MigrateInput>(
+  objectSchema(
+    {
+      from: { type: "string", enum: ["tailwind"] },
+      to: { type: "string", enum: ["stylex"] },
+      write: { type: "boolean" },
+      json: { type: "boolean" },
+      dir: { type: "string" },
+    },
+    ["from", "to"],
+  ),
+  (value) => {
+    const raw = withDir(record(value))
+    const from = optionalString(raw.from, "from")
+    const to = optionalString(raw.to, "to")
+    if (from !== "tailwind") throw new TypeError("from must be tailwind")
+    if (to !== "stylex") throw new TypeError("to must be stylex")
+    return {
+      from,
+      to,
+      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 const SNAPSHOT_SCHEMA = input<SnapshotInput>(
   objectSchema({ out: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }),
   (value) => {
@@ -1024,6 +1092,38 @@ const contextSpec: CommandSpec<ContextInput, ContextCommandOutput> = {
   render: (out) => [out.text],
 }
 
+const openApiSpec: CommandSpec<OpenApiInput, OpenApiCommandOutput> = {
+  name: "openapi",
+  summary:
+    "Generate the backend OpenAPI document, including supported build-time response inference.",
+  input: OPENAPI_SCHEMA,
+  output: output({
+    type: "object",
+    properties: { ok: { type: "boolean" }, format: { type: "string" }, text: { type: "string" } },
+    required: ["ok", "format", "text"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "format", field: "format", type: "string" },
+      { name: "path", field: "path", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const app = await loadAppFor(ctx)
+    const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
+    const format = value.format ?? "json"
+    return {
+      ok: true,
+      format,
+      text: await renderOpenApiWithTypes(app, format, value.path),
+    }
+  },
+  render: (out) => [out.text],
+  json: (out) => (out.format === "json" ? JSON.parse(out.text) : out.text),
+}
+
 const doctorSpec: CommandSpec<DoctorInput, DoctorResult> = {
   name: "doctor",
   summary: "Find undeclared imports, duplicate identity installs, and pipeline readiness drift.",
@@ -1071,6 +1171,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
     properties: {
       ok: { type: "boolean" },
       changed: { type: "array" },
+      failed: { type: "array" },
       diagnostics: { type: "array" },
     },
     required: ["ok", "diagnostics"],
@@ -1091,23 +1192,95 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
     const changed: string[] = []
+    const failed: { code: string; reason: string }[] = []
     for (const diagnostic of result.structuredDiagnostics ?? [])
       if (value.code === undefined || diagnostic.code === value.code)
-        changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+        // One recipe that cannot act must not cancel the others, and must not pass silently either:
+        // record why and keep going, so a run over many diagnostics still reports every outcome.
+        try {
+          changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+        } catch (error) {
+          failed.push({
+            code: diagnostic.code,
+            reason: error instanceof Error ? error.message : String(error),
+          })
+        }
     const final = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
-    return { ok: final.ok, changed, diagnostics: final.structuredDiagnostics ?? final.diagnostics }
+    return {
+      ok: final.ok,
+      changed,
+      failed,
+      diagnostics: final.structuredDiagnostics ?? final.diagnostics,
+    }
   },
   render: (out) => [
     out.ok ? "✓ fixes applied" : "✖ unresolved diagnostics remain",
     ...out.changed.map((file) => `  changed ${file}`),
+    ...out.failed.map((f) => `  could not fix ${f.code}: ${f.reason}`),
     ...out.diagnostics.map((d) => `  ${String((d as { code?: unknown }).code ?? "diagnostic")}`),
   ],
   success: (out) => out.ok,
 }
 
+const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
+  name: "migrate",
+  summary: "Migrate safe static Tailwind className utilities to native StyleX props.",
+  input: MIGRATE_SCHEMA,
+  output: output({
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      from: { type: "string" },
+      to: { type: "string" },
+      write: { type: "boolean" },
+      scanned: { type: "integer" },
+      changed: { type: "array" },
+      written: { type: "array" },
+      issues: { type: "array" },
+      files: { type: "array" },
+    },
+    required: ["ok", "from", "to", "write", "scanned", "changed", "written", "issues", "files"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "from", field: "from", type: "string" },
+      { name: "to", field: "to", type: "string" },
+      { name: "write", field: "write", type: "boolean" },
+      { name: "json", field: "json", type: "boolean" },
+      { name: "dir", field: "dir", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const { migrateTailwindToStylex } = await import("./stylex-migrate.ts")
+    return migrateTailwindToStylex(resolve(ctx.cwd, value.dir ?? "."), {
+      ...(value.write === undefined ? {} : { write: value.write }),
+    })
+  },
+  render: (out) => [
+    out.ok
+      ? `✓ migrated ${out.changed.length} file${out.changed.length === 1 ? "" : "s"}`
+      : `⚠ migrated ${out.changed.length} safe file${out.changed.length === 1 ? "" : "s"}; ${out.issues.length} manual issue${out.issues.length === 1 ? "" : "s"} remain`,
+    `  scanned ${out.scanned} source file${out.scanned === 1 ? "" : "s"}`,
+    ...(out.write
+      ? [`  wrote ${out.written.length} file${out.written.length === 1 ? "" : "s"}`]
+      : out.changed.length > 0
+        ? ["  dry run: pass --write to apply the safe changes"]
+        : []),
+    ...out.issues
+      .slice(0, 30)
+      .map((issue) => `  ${issue.file}:${issue.line} ${issue.token} — ${issue.reason}`),
+    ...(out.issues.length > 30
+      ? [`  … ${out.issues.length - 30} more issue${out.issues.length - 30 === 1 ? "" : "s"}`]
+      : []),
+  ],
+  success: (out) => out.ok,
+}
+
 const snapshotSpec: CommandSpec<SnapshotInput, SnapshotCommandOutput> = {
   name: "snapshot",
   summary: "Write the backend API contract as a versioned JSON baseline.",
@@ -1345,8 +1518,10 @@ export const commandSpecs = Object.freeze([
   manifestSpec,
   routesSpec,
   contextSpec,
+  openApiSpec,
   doctorSpec,
   fixSpec,
+  migrateSpec,
   snapshotSpec,
   diffSpec,
   contractsSpec,