@nifrajs/cli 2.14.1 → 3.2.0

package/src/frontend-guidance.ts

@@ -0,0 +1,259 @@
+/**
+ * `nifra_frontend` - a symptom-indexed catalog of the mistakes an agent (or a human) hits on the client
+ * side of a nifra app, across every adapter. It is the FRONTEND companion to `nifra_check`: where the
+ * check statically flags the footguns nifra's own seam owns (server-only imports, the nano lane), this
+ * catalog covers the ones a static rule can't own cheaply - hydration nondeterminism, a duplicated
+ * framework runtime, and the per-framework reactivity-loss idioms that each ecosystem's own linter is
+ * the real authority on.
+ *
+ * Deliberately a compact reference, not an accumulated fault corpus: two kinds of entry only.
+ *   - Seam entries (`adapters: ["all"]`) - the boundary nifra defines: server/client split, the loader
+ *     data contract, hydration determinism, one framework copy. These point at a `nifra_*` tool to fix
+ *     and verify, because nifra owns that surface.
+ *   - Framework entries - the classic reactivity-loss shape for one adapter (Vue ref, Solid props,
+ *     Svelte runes, React/Preact deps). These point at that framework's own ESLint plugin, which is the
+ *     authority; nifra does not re-implement it, it routes you to it.
+ *
+ * One source, two heads: `nifra_frontend` (MCP) serves it to an agent; `nifra frontend` (CLI) prints it
+ * for a human. Both call {@link renderFrontendResult}, so they can never drift.
+ */
+
+import type { Framework } from "./scaffold.ts"
+
+/** An adapter an entry applies to, or `all` for a seam issue that is adapter-independent. */
+export type GuidanceAdapter = Framework | "all"
+
+export interface GuidanceEntry {
+  /** Stable slug, e.g. `server-import`. */
+  readonly id: string
+  /** Which adapters this applies to. `["all"]` is a seam issue every adapter shares. */
+  readonly adapters: readonly GuidanceAdapter[]
+  /** What you observe - the searchable symptom, phrased as the failure, not the cause. */
+  readonly symptom: string
+  /** Why it happens. */
+  readonly cause: string
+  /** The concrete change that fixes it. */
+  readonly fix: string
+  /** How to confirm it is fixed - a `nifra_*` tool for a seam issue, the framework's linter otherwise. */
+  readonly verify: string
+  /** Where to go deeper - a `nifra_docs`/`nifra_example` query, or the ecosystem linter that owns it. */
+  readonly seeAlso?: string | undefined
+}
+
+/**
+ * The catalog. Seam entries first (they are the nifra-specific value and apply everywhere), then the
+ * per-framework reactivity-loss entries. Keep it compact and high-signal - a curated fault corpus mined
+ * from real failures is operated depth and lives elsewhere, not in the public package.
+ */
+export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
+  {
+    id: "server-import",
+    adapters: ["all"],
+    symptom:
+      "A client component crashes at build or runtime with a missing Node built-in, a leaked secret, or 'module not found in the browser'.",
+    cause:
+      "A server-only module (the DB, a secret, `node:*`, the backend file) is imported at the top level of a component, so the bundler tries to ship it to the browser.",
+    fix: "Move the access into a server-only `loader`/`action` and read the result in the component. Reach the backend through the typed `api` argument, never a top-level server-only import.",
+    verify:
+      "nifra_check - its transitive server-import scan flags the exact import chain into a client module.",
+    seeAlso: "loader action server-only import boundary",
+  },
+  {
+    id: "hydration-mismatch",
+    adapters: ["all"],
+    symptom:
+      "A hydration warning, text that flips on load, or 'server HTML did not match client' the first time the page becomes interactive.",
+    cause:
+      "The first client render is not identical to the SSR HTML - usually a non-deterministic read during render: `Date.now()`, `Math.random()`, `window`/`localStorage`, or a locale/timezone the server did not have.",
+    fix: "Render deterministic markup, then apply anything client-only in an effect / `onMount` after the first paint. Pass anything the server knew (time, locale, flags) down through loader data so both renders agree.",
+    verify:
+      "nifra_render the route and diff its HTML against the first client render; nifra_check's hydration assurance reports nondeterminism it can see.",
+    seeAlso: "hydration ssr determinism loader data",
+  },
+  {
+    id: "duplicate-runtime",
+    adapters: ["react", "preact", "solid", "vue", "svelte"],
+    symptom:
+      "'Invalid hook call', a null context/provider, signals that never update, or a component that mounts twice.",
+    cause:
+      "Two copies of the framework are in the bundle - the app's own dependency and a second one resolved through the adapter - so the two runtimes do not share the same module-level state.",
+    fix: "Dedupe the framework to a single version across the workspace (one entry in the lockfile). The adapter must resolve the app's copy, not bundle its own.",
+    verify: "nifra_doctor - it detects a duplicated framework runtime (NF-H002).",
+    seeAlso: "duplicate framework runtime dedupe NF-H002",
+  },
+  {
+    id: "loader-typing",
+    adapters: ["all"],
+    symptom:
+      "Loader data is typed `any` in the page, or a hand-written interface silently drifts from what the loader actually returns.",
+    cause:
+      "The component types its props by hand instead of inferring them from the loader, so a change to the loader is not a type error at the use site.",
+    fix: "Type the page from the loader: `props: { data: LoaderData<typeof loader> }`. Call the backend through the typed `api` so the request/response shape is inferred, not restated.",
+    verify:
+      "nifra_context prints the exact loader shape and typed call form; nifra_check fails on drift.",
+    seeAlso: "LoaderData typed client loader inference",
+  },
+  {
+    id: "list-key",
+    adapters: ["all"],
+    symptom:
+      "List rows keep the wrong state on reorder/insert - a checked box, focus, or an input value jumps to a different row.",
+    cause:
+      "The list is keyed by the array index (or not keyed at all), so add/remove/reorder maps the wrong item to an existing node.",
+    fix: "Key each row by a stable, unique id from the item, never its position in the array.",
+    verify:
+      "The framework's own linter for JSX keys; on the vanilla nano lane, nifra_check flags an index key as NF-C022.",
+    seeAlso: "list key stable id reconcile nano",
+  },
+  {
+    id: "vue-lost-reactivity",
+    adapters: ["vue"],
+    symptom:
+      "A value stops updating the template after you pull it out of a ref, reactive object, or props.",
+    cause:
+      "Destructuring a `reactive()` object or `props` copies the current value and drops the reactive link; a `ref` read in script forgets `.value`.",
+    fix: "Keep the reactive source intact: use `toRefs`/`storeToRefs` when you must destructure, access `props.x` directly, and remember `.value` on a ref in script (templates unwrap it for you).",
+    verify:
+      "eslint-plugin-vue - it is the authority on Vue reactivity; nifra does not re-implement it.",
+    seeAlso: "eslint-plugin-vue toRefs reactivity",
+  },
+  {
+    id: "solid-lost-reactivity",
+    adapters: ["solid"],
+    symptom: "A prop or store value renders once and never tracks updates in a Solid component.",
+    cause:
+      "Solid props are getters, evaluated where you read them. Destructuring props (or reading them outside JSX/an effect) reads once and loses tracking.",
+    fix: "Access `props.x` at the point of use inside JSX, or `splitProps`/`mergeProps` when you need to pass a subset on. Never destructure props in the function signature.",
+    verify:
+      "eslint-plugin-solid - the authority on Solid reactivity; nifra routes you to it, not around it.",
+    seeAlso: "eslint-plugin-solid splitProps props getters",
+  },
+  {
+    id: "svelte-runes",
+    adapters: ["svelte"],
+    symptom:
+      "In a Svelte 5 component, `export let` props or a `$:` statement do not behave as expected, or the compiler rejects them in runes mode.",
+    cause:
+      "Runes mode replaces the Svelte 4 idioms: props come from `$props()`, derived values from `$derived`, side effects from `$effect`. Mixing the two models is the mismatch.",
+    fix: "In runes mode use `$props()` for inputs, `$state` for local state, `$derived` for computed values, and `$effect` for side effects - not `export let` or `$:`.",
+    verify:
+      "eslint-plugin-svelte and the Svelte compiler warnings own this; nifra points you at them.",
+    seeAlso: "eslint-plugin-svelte runes $props $derived",
+  },
+  {
+    id: "react-stale-deps",
+    adapters: ["react", "preact"],
+    symptom:
+      "An effect or callback uses a stale value, fires too often, or never re-runs when a value it reads changes.",
+    cause:
+      "The dependency array omits a value the effect/callback closes over (or the effect has no array), so the closure captures an old render's value.",
+    fix: "List every reactive value the effect reads in its deps, or hold the mutable value in a ref when it must not trigger a re-run. Do not silence the rule by emptying the array.",
+    verify:
+      "eslint-plugin-react-hooks (`exhaustive-deps`) is the authority on effect deps; nifra does not duplicate it.",
+    seeAlso: "eslint-plugin-react-hooks exhaustive-deps effect closure",
+  },
+  {
+    id: "prefer-nano-or-island",
+    adapters: ["vanilla"],
+    symptom:
+      "A vanilla page needs local state or a list a human edits, and hand-written DOM updates are getting fragile.",
+    cause:
+      "The islands lane is imperative and has no state primitive, so each update is hand-wired and a list means rebuilding the container.",
+    fix: "Use the nano lane: `signal` + `computed(fn, [deps])` for state, `bindList` for a keyed list, `resource` for async. Every reactive edge is a visible call, so its mistakes are static lints.",
+    verify:
+      "nifra_check runs NF-C021 (discarded disposer), NF-C022 (index key), NF-C023 (missing dep) over the nano code.",
+    seeAlso: "nano signal computed bindList resource islands",
+  },
+]
+
+const ADAPTER_ALIASES: Record<string, GuidanceAdapter> = {
+  all: "all",
+  react: "react",
+  preact: "preact",
+  solid: "solid",
+  vue: "vue",
+  svelte: "svelte",
+  vanilla: "vanilla",
+}
+
+/** Normalize a free-text adapter argument to a known adapter, or `undefined` if it is not one. */
+export function parseAdapter(value: string | undefined): GuidanceAdapter | undefined {
+  if (value === undefined) return undefined
+  return ADAPTER_ALIASES[value.trim().toLowerCase()]
+}
+
+const appliesTo = (entry: GuidanceEntry, adapter: GuidanceAdapter): boolean =>
+  adapter === "all" || entry.adapters.includes("all") || entry.adapters.includes(adapter)
+
+/** Keyword score of an entry against a query - counts distinct query words found in its text. */
+function score(entry: GuidanceEntry, words: readonly string[]): number {
+  const hay =
+    `${entry.id} ${entry.symptom} ${entry.cause} ${entry.fix} ${entry.seeAlso ?? ""}`.toLowerCase()
+  let hits = 0
+  for (const w of words) if (hay.includes(w)) hits++
+  return hits
+}
+
+function renderEntry(entry: GuidanceEntry): string {
+  const scope = entry.adapters.includes("all") ? "all adapters" : entry.adapters.join(", ")
+  const parts = [
+    `[${entry.id}]  (${scope})`,
+    `Symptom: ${entry.symptom}`,
+    `Cause:   ${entry.cause}`,
+    `Fix:     ${entry.fix}`,
+    `Verify:  ${entry.verify}`,
+  ]
+  if (entry.seeAlso !== undefined) parts.push(`See:     ${entry.seeAlso}`)
+  return parts.join("\n")
+}
+
+function renderIndex(
+  entries: readonly GuidanceEntry[],
+  adapter: GuidanceAdapter | undefined,
+): string {
+  const scope = adapter === undefined ? "all adapters" : `adapter: ${adapter}`
+  const lines = entries.map((e) => {
+    const s = e.adapters.includes("all") ? "all" : e.adapters.join("/")
+    return `- ${e.id} (${s}) - ${e.symptom}`
+  })
+  return [
+    `nifra frontend guidance (${entries.length} of ${FRONTEND_GUIDANCE.length}, ${scope}). Pass a symptom to get the cause + fix + how to verify; pass an adapter to filter.`,
+    "",
+    ...lines,
+  ].join("\n")
+}
+
+/**
+ * Render the catalog. Filters by `adapter` (when it names a known one), then by a `symptom` keyword
+ * query. With no query it returns the (filtered) index; with a query it returns the best-matching
+ * entries in full, or the index plus a "no match" note when nothing scores. Pure, so both heads agree.
+ */
+export function renderFrontendResult(args: {
+  adapter?: string | undefined
+  symptom?: string | undefined
+  limit?: number | undefined
+}): string {
+  const adapter = parseAdapter(args.adapter)
+  const scoped =
+    adapter === undefined
+      ? FRONTEND_GUIDANCE
+      : FRONTEND_GUIDANCE.filter((e) => appliesTo(e, adapter))
+  const query = args.symptom?.trim()
+  if (query === undefined || query.length === 0) return renderIndex(scoped, adapter)
+
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((w) => w.length > 1)
+  const limit = Math.min(Math.max(args.limit ?? 3, 1), 5)
+  const ranked = scoped
+    .map((entry) => ({ entry, s: score(entry, words) }))
+    .filter((r) => r.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+
+  if (ranked.length === 0) {
+    return `No frontend-guidance entry matched "${query}"${adapter ? ` for ${adapter}` : ""}.\n\n${renderIndex(scoped, adapter)}`
+  }
+  return ranked.map((r) => renderEntry(r.entry)).join("\n\n")
+}

package/src/internal/reserved-segment-codemod.ts

@@ -0,0 +1,150 @@
+/**
+ * Codemod for reserved-segment collisions in typed-client call sites.
+ *
+ * A route segment spelling a reserved proxy key (`get`…`options`, `subscribe`, `ws`, `index`, `then`)
+ * cannot be reached by property access - the proxy resolves the reserved behavior first - so the client
+ * type resolves that child to `ReservedSegmentCollision<"seg">` and every `api.foo.delete.post()` in the
+ * project stops compiling at once. The fix is mechanical and identical at every site: call the parent
+ * node with the segment instead, `api.foo("delete").post()`. Doing that by hand across a codebase is
+ * pure toil, and it is toil the framework caused.
+ *
+ * The compiler is the site index. `tsc` already reports every broken access, and its message names the
+ * segment (`Property 'post' does not exist on type 'ReservedSegmentCollision<"delete">'`), so the
+ * rewrite needs no type graph of its own and cannot invent a site the compiler did not reject. That
+ * also disambiguates the one case a textual search could not: `.delete` as a real DELETE verb call is
+ * valid and never appears in this list.
+ *
+ * A site the scan cannot rewrite CONFIDENTLY is left alone and reported, never guessed at. Bracket
+ * access, a collision node stored in a variable and used elsewhere, and any shape where the text before
+ * the failing property is not `.<segment>` all fall into that bucket.
+ */
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+/** `path/to/file.ts(12,16): error TS2339: … 'ReservedSegmentCollision<"delete">'.` */
+const TSC_POSITION = /^(.+?)\((\d+),(\d+)\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/
+const COLLISION_TYPE = /ReservedSegmentCollision<"([^"]+)">/
+
+export interface CollisionSite {
+  readonly file: string
+  /** 1-based, as `tsc` reports them. */
+  readonly line: number
+  readonly column: number
+  /** The colliding path segment, read out of the type the compiler named. */
+  readonly segment: string
+}
+
+/** Every reserved-segment collision `tsc` reported, in the order it reported them. */
+export function parseCollisionSites(tscOutput: string): readonly CollisionSite[] {
+  const sites: CollisionSite[] = []
+  for (const raw of tscOutput.split("\n")) {
+    const position = TSC_POSITION.exec(raw.trim())
+    if (position === null) continue
+    const segment = COLLISION_TYPE.exec(position[4] as string)
+    if (segment === null) continue
+    sites.push({
+      file: position[1] as string,
+      line: Number(position[2]),
+      column: Number(position[3]),
+      segment: segment[1] as string,
+    })
+  }
+  return sites
+}
+
+/** Byte offset of a 1-based (line, column) in `source`, or undefined when it is past the end. */
+const offsetOf = (source: string, line: number, column: number): number | undefined => {
+  let offset = 0
+  for (let current = 1; current < line; current += 1) {
+    const next = source.indexOf("\n", offset)
+    if (next === -1) return undefined
+    offset = next + 1
+  }
+  const target = offset + column - 1
+  return target <= source.length ? target : undefined
+}
+
+const skipSpaceBack = (source: string, from: number): number => {
+  let index = from
+  while (index >= 0 && /\s/.test(source[index] as string)) index -= 1
+  return index
+}
+
+/**
+ * The span to replace for one site: the `.segment` immediately preceding the failing property access,
+ * which becomes `("segment")`. Undefined when the text does not have that shape - the caller reports
+ * those rather than rewriting something it did not recognise.
+ *
+ * The scan runs backwards over the whole source rather than one line, so a chain broken across lines
+ * (`api.foo\n  .delete\n  .post()`) rewrites the same as a chain on one line.
+ */
+export function collisionSpan(
+  source: string,
+  site: CollisionSite,
+): { readonly start: number; readonly end: number } | undefined {
+  const offset = offsetOf(source, site.line, site.column)
+  if (offset === undefined) return undefined
+
+  // Back over the dot that introduces the FAILING property (`.post` in `…delete.post`).
+  let index = skipSpaceBack(source, offset - 1)
+  if (source[index] !== ".") return undefined
+
+  // Back over the colliding segment itself.
+  index = skipSpaceBack(source, index - 1)
+  const segmentEnd = index
+  const segmentStart = segmentEnd - site.segment.length + 1
+  if (segmentStart < 0) return undefined
+  if (source.slice(segmentStart, segmentEnd + 1) !== site.segment) return undefined
+
+  // Back over the dot that introduces the segment. Anything else (bracket access, a bare identifier
+  // holding the node) is a shape this rewrite does not understand.
+  const dot = skipSpaceBack(source, segmentStart - 1)
+  if (source[dot] !== ".") return undefined
+
+  // Take any whitespace before that dot into the span too, so a chain broken across lines closes up
+  // (`api.jobs\n  .subscribe` becomes `api.jobs("subscribe")`) instead of leaving the call argument
+  // dangling on its own line.
+  return { start: skipSpaceBack(source, dot - 1) + 1, end: segmentEnd }
+}
+
+export interface FileRewrite {
+  readonly source: string
+  /** Sites in this file the scan declined to rewrite, so the caller can report them. */
+  readonly skipped: readonly CollisionSite[]
+}
+
+/**
+ * Apply every site belonging to one file. Spans are applied back to front so an earlier rewrite never
+ * shifts the offsets of one not yet applied, and a duplicate span (two failing properties resolving
+ * through the same access) is applied once.
+ */
+export function rewriteFile(source: string, sites: readonly CollisionSite[]): FileRewrite {
+  const skipped: CollisionSite[] = []
+  const spans: { start: number; end: number; segment: string }[] = []
+  for (const site of sites) {
+    const span = collisionSpan(source, site)
+    if (span === undefined) {
+      skipped.push(site)
+      continue
+    }
+    if (spans.some((other) => other.start === span.start && other.end === span.end)) continue
+    spans.push({ ...span, segment: site.segment })
+  }
+  let out = source
+  for (const span of [...spans].sort((a, b) => b.start - a.start)) {
+    out = `${out.slice(0, span.start)}("${span.segment}")${out.slice(span.end + 1)}`
+  }
+  return { source: out, skipped }
+}
+
+/** The project's own `tsc` binary, found upward from `root`. Never installs one. */
+export function resolveTscBin(root: string): string | undefined {
+  let dir = root
+  while (true) {
+    const candidate = join(dir, "node_modules", "typescript", "bin", "tsc")
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}

package/src/internal/typescript-import.ts

@@ -12,11 +12,37 @@
  * install does not pay for it.
  */
 
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
 /** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
 export type TypeScriptApi = typeof import("typescript")
 
 /**
- * Import the project's TypeScript, or `undefined` when it is not installed.
+ * Is this module actually the compiler, rather than something else published under the same name?
+ *
+ * The `typescript` package name also carries small non-compiler entry points (a version stub, for
+ * one), and a resolver that falls back to a global download cache can hand one of those back. They
+ * import cleanly and then explode on first use - `undefined is not an object (evaluating
+ * 'ts.ScriptKind.TSX')` deep inside a scan - which reads as a Nifra bug rather than as "the compiler
+ * we loaded is not a compiler". Checking the two members every caller needs turns that into a
+ * resolution miss, which the fallbacks below already know how to handle.
+ */
+function isCompiler(module: unknown): module is TypeScriptApi {
+  if (typeof module !== "object" || module === null) return false
+  const api = module as Partial<TypeScriptApi>
+  return typeof api.createSourceFile === "function" && api.ScriptKind !== undefined
+}
+
+/** Unwrap the CJS default interop wrapper, so both `import * as ts` shapes look the same. */
+function compilerOf(module: unknown): TypeScriptApi | undefined {
+  if (isCompiler(module)) return module
+  const wrapped = (module as { default?: unknown } | undefined)?.default
+  return isCompiler(wrapped) ? wrapped : undefined
+}
+
+/**
+ * Import TypeScript from the CLI's own dependency tree, or `undefined` when it is not installed.
  *
  * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
  * broken install, not a missing one, and telling that user to install what they already have sends
@@ -24,7 +50,7 @@ export type TypeScriptApi = typeof import("typescript")
  */
 export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
   try {
-    return (await import("typescript")) as TypeScriptApi
+    return compilerOf(await import("typescript"))
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause)
     if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)) return undefined
@@ -32,6 +58,33 @@ export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
   }
 }
 
+/**
+ * Find the project's compiler the way module resolution would: `node_modules/typescript` in `root`,
+ * then each parent directory up to the filesystem root - the same walk the typecheck gate uses to
+ * find `tsc`, so both gates agree on which compiler the project has.
+ *
+ * The walk is deliberate, not a fallback for a missing resolver. `Bun.resolveSync` memoizes a
+ * specifier for the life of the process AND auto-installs from the global download cache when the
+ * project has none, so a long-lived process (the MCP server) that first resolved `typescript` before
+ * `bun install` kept handing back that cache entry afterwards - the typecheck went phantom until the
+ * server was restarted. A filesystem probe is re-answered every call, so an install that lands
+ * mid-session is picked up on the next scan.
+ */
+function resolveProjectTypeScript(root: string): string | undefined {
+  let dir = root
+  while (true) {
+    const pkg = join(dir, "node_modules", "typescript")
+    // `lib/typescript.js` is the compiler entry across every published major; probing it directly
+    // (rather than importing the directory) keeps a package whose main entry is a stub out of play.
+    const entry = join(pkg, "lib", "typescript.js")
+    if (existsSync(entry)) return entry
+    if (existsSync(join(pkg, "package.json"))) return pkg
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
 /**
  * Import TypeScript resolved from the PROJECT root first, falling back to the CLI's own dependency
  * tree. A bare `import("typescript")` resolves relative to this file - the CLI's install - so a
@@ -41,16 +94,13 @@ export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
  * the CLI was installed - the same cwd-invariance the typecheck gate's tsc resolution has.
  */
 export async function importProjectTypeScript(root: string): Promise<TypeScriptApi | undefined> {
-  let resolved: string
-  try {
-    resolved = Bun.resolveSync("typescript", root)
-  } catch {
-    // Unresolvable from the project (not installed there, or a non-Bun host without resolveSync):
-    // fall back to the CLI's own tree, which keeps the previous behavior as the floor.
-    return importTypeScript()
-  }
+  const resolved = resolveProjectTypeScript(root)
+  // Not installed in the project (or installed without a compiler entry): fall back to the CLI's own
+  // tree, which keeps the previous behavior as the floor.
+  if (resolved === undefined) return importTypeScript()
   try {
-    return (await import(resolved)) as TypeScriptApi
+    const compiler = compilerOf(await import(resolved))
+    return compiler ?? (await importTypeScript())
   } catch (cause) {
     // Same contract as importTypeScript: a compiler that RESOLVES and then fails evaluating is a
     // broken install, not a missing one - rethrow rather than silently checking with another copy.

package/src/introspect.ts

@@ -5,6 +5,7 @@
  * *this* project's actual surface, not just generic docs.
  */
 
+import { reservedKeyFor } from "@nifrajs/client"
 import {
   type ProjectEvidenceSchema,
   type ProjectEvidenceSchemaPart,
@@ -153,6 +154,24 @@ function schemaLines(schema: ReflectedRoute["schema"]): string[] {
 
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
+/**
+ * The typed-client proxy chain for a path, without the terminal verb call. Shared by `clientCall`
+ * and the `nifra routes` collision annotation so both teach exactly one spelling.
+ */
+function clientChain(path: string): string {
+  const segs = path.split("/").filter((seg) => seg !== "")
+  if (segs.length === 0) return "api.index"
+  let chain = "api"
+  for (const seg of segs) {
+    if (seg.startsWith(":") || seg.startsWith("*")) {
+      const name = seg.replace(/^[:*]/, "") || "value"
+      chain += `({ ${name} })`
+    } else if (reservedKeyFor(seg) !== undefined) chain += `(${JSON.stringify(seg)})`
+    else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
+  }
+  return chain
+}
+
 /**
  * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
@@ -160,20 +179,16 @@ const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
  * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
+ *
+ * A segment spelling a reserved proxy key (`delete`, `subscribe`, `then`, ...) is emitted as a call on
+ * the parent node instead - and NOT as bracket access, which does not help: the proxy intercepts the
+ * key however it is spelled. Emitting `.delete` here would hand an agent a chain that resolves the
+ * DELETE verb and silently requests the wrong path.
  */
 export function clientCall(method: string, path: string, schema: unknown): string {
   const s = schema as { body?: unknown; query?: unknown } | undefined
   const verb = method.toLowerCase()
-  const segs = path.split("/").filter((seg) => seg !== "")
-  let chain = "api"
-  if (segs.length === 0) chain += ".index"
-  else
-    for (const seg of segs) {
-      if (seg.startsWith(":") || seg.startsWith("*")) {
-        const name = seg.replace(/^[:*]/, "") || "value"
-        chain += `({ ${name} })`
-      } else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
-    }
+  const chain = clientChain(path)
   const isBodyVerb = verb === "post" || verb === "put" || verb === "patch"
   let call: string
   if (isBodyVerb) {
@@ -460,6 +475,27 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
   )
 }
 
+/**
+ * The typed-client spelling for a route path, and the reserved key it collides with when one of its
+ * static segments cannot be reached by property access.
+ *
+ * This is where a dev meets the reserved set EARLIEST: `nifra routes` is what you run while the
+ * route is being written, long before a typed client call site exists to break. The reserved names
+ * are deliberately unguessable from the outside (`then` and `index` especially - they exist so the
+ * proxy stays await-safe and can address `/`), so the route table names the collision and shows the
+ * spelling that reaches the route, rather than leaving it to be discovered by a failing build.
+ */
+export function clientSpellingFor(
+  path: string,
+): { readonly spelling: string; readonly reserved: string } | undefined {
+  for (const segment of path.split("/")) {
+    if (segment === "") continue
+    const reserved = reservedKeyFor(segment)
+    if (reserved !== undefined) return { spelling: clientChain(path), reserved }
+  }
+  return undefined
+}
+
 /** Render the route table as a terse aligned text table (the `nifra routes` default output). Pure. */
 export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
   if (rows.length === 0)
@@ -468,16 +504,29 @@ export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
     methods: r.methods.join(", "),
     kind: r.kind,
     path: r.kind === "api" && r.autoMounted ? `${r.path}  (auto-mounted)` : r.path,
+    client: clientSpellingFor(r.path),
   }))
   const methodW = Math.max("METHOD".length, ...display.map((d) => d.methods.length))
   const kindW = Math.max("KIND".length, ...display.map((d) => d.kind.length))
   const padEnd = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length))
   const line = (methods: string, kind: string, path: string): string =>
     `${padEnd(methods, methodW)}  ${padEnd(kind, kindW)}  ${path}`
-  return [
+  const table = [
     line("METHOD", "KIND", "PATH"),
-    ...display.map((d) => line(d.methods, d.kind, d.path)),
-  ].join("\n")
+    ...display.flatMap((d) =>
+      d.client === undefined
+        ? [line(d.methods, d.kind, d.path)]
+        : [
+            line(d.methods, d.kind, d.path),
+            line(
+              "",
+              "",
+              `  -> '${d.client.reserved}' is a reserved typed-client key; reach this route as \`${d.client.spelling}\``,
+            ),
+          ],
+    ),
+  ]
+  return table.join("\n")
 }
 
 /** One JSON row for `nifra routes --json` (the agent-facing, stable shape). */
@@ -487,21 +536,33 @@ export interface RouteJsonRow {
   readonly methods: readonly string[]
   readonly file?: string
   readonly autoMounted?: boolean
+  /** The reserved typed-client key a static segment of this path collides with, when one does. */
+  readonly reservedKey?: string
+  /** The typed-client call spelling that reaches this route, present only alongside `reservedKey`. */
+  readonly clientSpelling?: string
 }
 
 /** The route table as a JSON document for `--json` (agents). Stable keys; `file`/`autoMounted` present
- * only where meaningful (file on pages, autoMounted on API routes). */
+ * only where meaningful (file on pages, autoMounted on API routes). A colliding row additionally
+ * carries `reservedKey`/`clientSpelling` so an agent writing client code from this table never has to
+ * infer the closed set of reserved names - the one thing about it nobody can guess. */
 export function routeTableToJson(rows: readonly RouteTableEntry[]): {
   readonly routes: readonly RouteJsonRow[]
 } {
   return {
-    routes: rows.map((r) => ({
-      kind: r.kind,
-      path: r.path,
-      methods: r.methods,
-      ...(r.file !== undefined ? { file: r.file } : {}),
-      ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
-    })),
+    routes: rows.map((r) => {
+      const client = clientSpellingFor(r.path)
+      return {
+        kind: r.kind,
+        path: r.path,
+        methods: r.methods,
+        ...(r.file !== undefined ? { file: r.file } : {}),
+        ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
+        ...(client === undefined
+          ? {}
+          : { reservedKey: client.reserved, clientSpelling: client.spelling }),
+      }
+    }),
   }
 }