@nifrajs/cli 2.1.0 → 2.3.0

package/src/port.ts

@@ -1,12 +1,12 @@
 /**
- * `nifra port` — a portability linter. It scans an app's source for features whose runtime guarantees
+ * `nifra port` - a portability linter. It scans an app's source for features whose runtime guarantees
  * differ across deploy targets, prints a feature × target capability matrix, and (in CI mode) fails
  * when a *detected* feature is unsupported on the app's resolved deploy target.
  *
  * The premise: nifra runs the same app on five targets (Bun, Node, Deno, Cloudflare Pages, Vercel), but
  * a per-instance in-memory store, a long-lived in-process cron loop, or a `Bun.*` global is portable
  * across some and a silent footgun on others. The framework's stores already *runtime*-guard this (e.g.
- * `MemorySessionStore` throws under `NODE_ENV=production`); `port` is the *build-time* counterpart — it
+ * `MemorySessionStore` throws under `NODE_ENV=production`); `port` is the *build-time* counterpart - it
  * tells you before you deploy, and gates CI so the regression can't ship.
  *
  * Detection works on reliable import/symbol signals only (a real `@nifrajs/*` import paired with the
@@ -24,7 +24,7 @@ export type Target = (typeof TARGETS)[number]
 
 const isTarget = (value: string): value is Target => (TARGETS as readonly string[]).includes(value)
 
-/** The portability hazards `port` detects. Stable ids — they're part of the `--json` contract. */
+/** The portability hazards `port` detects. Stable ids - they're part of the `--json` contract. */
 export const FEATURE_IDS = [
   "in-memory-session-store",
   "in-memory-isr-cache",
@@ -46,12 +46,12 @@ interface FeatureSpec {
   /** Short explanation of WHY this feature is a portability hazard at all (printed in the legend/report). */
   readonly summary: string
   readonly verdicts: Readonly<Record<Target, Verdict>>
-  /** Per-target reason — why this verdict, and (for caveat/unsupported) the fix. */
+  /** Per-target reason - why this verdict, and (for caveat/unsupported) the fix. */
   readonly reasons: Readonly<Record<Target, string>>
 }
 
 // In-memory stores (session/ISR/rate-limit) share a verdict shape: fine single-instance on a long-lived
-// runtime (caveat — lost on restart, not shared across instances), unsupported on the distributed edge.
+// runtime (caveat - lost on restart, not shared across instances), unsupported on the distributed edge.
 const inMemoryVerdicts: Readonly<Record<Target, Verdict>> = {
   bun: "caveat",
   node: "caveat",
@@ -79,7 +79,7 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
     summary: "MemorySessionStore keeps sessions per-instance (@nifrajs/auth)",
     verdicts: inMemoryVerdicts,
     reasons: inMemoryReasons(
-      "distributed edge has no shared per-instance memory — use KVSessionStore (Workers KV) or another shared store",
+      "distributed edge has no shared per-instance memory - use KVSessionStore (Workers KV) or another shared store",
     ),
   },
   "in-memory-isr-cache": {
@@ -87,7 +87,7 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
     summary: "MemoryCacheStore caches rendered pages per-instance (@nifrajs/web)",
     verdicts: inMemoryVerdicts,
     reasons: inMemoryReasons(
-      "each edge instance caches separately and revalidation won't propagate — use KVCacheStore (Workers KV) or the platform Cache API",
+      "each edge instance caches separately and revalidation won't propagate - use KVCacheStore (Workers KV) or the platform Cache API",
     ),
   },
   "in-memory-rate-limit": {
@@ -95,7 +95,7 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
     summary: "MemoryStore counts hits per-instance (@nifrajs/middleware)",
     verdicts: inMemoryVerdicts,
     reasons: inMemoryReasons(
-      "a per-instance limiter doesn't hold across edge instances — use a shared store (Redis / Durable Object)",
+      "a per-instance limiter doesn't hold across edge instances - use a shared store (Redis / Durable Object)",
     ),
   },
   "in-process-cron": {
@@ -113,8 +113,8 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
       node: "long-lived process runs the scheduler loop",
       deno: "long-lived process runs the scheduler loop",
       "cf-pages":
-        "no long-lived loop on Workers — use the platform `scheduled` trigger via toFetchHandler(app, { scheduled }) and a wrangler [triggers] cron",
-      vercel: "no long-lived process — use a Vercel Cron Job hitting an endpoint",
+        "no long-lived loop on Workers - use the platform `scheduled` trigger via toFetchHandler(app, { scheduled }) and a wrangler [triggers] cron",
+      vercel: "no long-lived process - use a Vercel Cron Job hitting an endpoint",
     },
   },
   "in-process-websocket": {
@@ -132,7 +132,7 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
       node: "all sockets live in one process; app.publish broadcasts to every client",
       deno: "all sockets live in one process; app.publish broadcasts to every client",
       "cf-pages":
-        "a stateless fetch can't broadcast across isolates — wrap the app in createWebSocketHub (a Durable Object) from @nifrajs/workers",
+        "a stateless fetch can't broadcast across isolates - wrap the app in createWebSocketHub (a Durable Object) from @nifrajs/workers",
       vercel: "Vercel's serverless functions don't hold long-lived WebSocket connections",
     },
   },
@@ -148,8 +148,8 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
     },
     reasons: {
       bun: "the Bun runtime provides the Bun global",
-      node: "no Bun global on Node — use the node: / Web equivalents",
-      deno: "no Bun global on Deno — use the Deno / Web equivalents",
+      node: "no Bun global on Node - use the node: / Web equivalents",
+      deno: "no Bun global on Deno - use the Deno / Web equivalents",
       "cf-pages": "no Bun global in the Workers runtime",
       vercel: "no Bun global in the Vercel runtime",
     },
@@ -165,8 +165,8 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
       vercel: "unsupported",
     },
     reasons: {
-      bun: "no Deno global on Bun — use the Bun / Web equivalents",
-      node: "no Deno global on Node — use the node: / Web equivalents",
+      bun: "no Deno global on Bun - use the Bun / Web equivalents",
+      node: "no Deno global on Node - use the node: / Web equivalents",
       deno: "the Deno runtime provides the Deno global",
       "cf-pages": "no Deno global in the Workers runtime",
       vercel: "no Deno global in the Vercel runtime",
@@ -197,7 +197,7 @@ export const FEATURES: Readonly<Record<FeatureId, FeatureSpec>> = {
 export interface Evidence {
   readonly file: string
   readonly line: number
-  /** The trimmed source line — the signal in context, for the human report. */
+  /** The trimmed source line - the signal in context, for the human report. */
   readonly snippet: string
 }
 
@@ -233,9 +233,9 @@ const ISR_CACHE = /(?<![.\w$])MemoryCacheStore\b/g
 const RATE_LIMIT = /(?<![.\w$])MemoryStore\b/g
 // In-process cron: the scheduler factory. Paired with the @nifrajs/cron import.
 const CRON_SCHEDULER = /(?<![.\w$])createScheduler\s*\(/g
-// `.ws(` method call — a WebSocket route registration on a nifra app. `(?<![.\w$])` keeps it from
+// `.ws(` method call - a WebSocket route registration on a nifra app. `(?<![.\w$])` keeps it from
 // matching identifiers that merely END in `ws` (e.g. `rows(`, `views(`). It DOES match `app.ws(`,
-// `server().ws(`, `x.ws(` — all the chained forms — because the dot is consumed by the call, and the
+// `server().ws(`, `x.ws(` - all the chained forms - because the dot is consumed by the call, and the
 // negative lookbehind only guards the char BEFORE `ws`, which is the dot here. We exclude the dot from
 // the lookbehind set on purpose: a method call is exactly what we want.
 const WS_ROUTE = /\.ws\s*\(/g
@@ -268,7 +268,7 @@ const pushHits = (
  */
 interface ScanState {
   readonly evidence: Map<FeatureId, Evidence[]>
-  /** True once any file references `createWebSocketHub` — suppresses the in-process-websocket finding. */
+  /** True once any file references `createWebSocketHub` - suppresses the in-process-websocket finding. */
   hasWebSocketHub: boolean
 }
 
@@ -303,7 +303,7 @@ export function scanFileForFeatures(file: string, content: string, state: ScanSt
 }
 
 // Mirror nifra check/doctor's ignore set: deps, build output, generated/per-runtime dist dirs, VCS.
-// PLUS *.config.* and obvious build scripts (build*.ts) — `port` scans request/app source, not tooling.
+// PLUS *.config.* and obvious build scripts (build*.ts) - `port` scans request/app source, not tooling.
 const IGNORED =
   /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)[^/]*\.config\.[cm]?[jt]sx?$|(^|\/)build[^/]*\.[cm]?[jt]sx?$/
 
@@ -334,7 +334,7 @@ export async function detectFeatures(cwd: string): Promise<DetectedFeature[]> {
     const evidence = state.evidence.get(id)
     if (evidence === undefined || evidence.length === 0) continue
     // in-process WebSocket is only a portability hazard when the app does NOT use createWebSocketHub
-    // (the Workers Durable Object hub) — its presence means the WS routes are already edge-ready.
+    // (the Workers Durable Object hub) - its presence means the WS routes are already edge-ready.
     if (id === "in-process-websocket" && state.hasWebSocketHub) continue
     const spec = FEATURES[id]
     detected.push({
@@ -351,7 +351,7 @@ export async function detectFeatures(cwd: string): Promise<DetectedFeature[]> {
 
 export interface ResolvedTarget {
   readonly target: Target
-  /** How the target was determined — surfaced so the report explains itself. */
+  /** How the target was determined - surfaced so the report explains itself. */
   readonly source: "flag" | "package-json-build" | "package-json-deploy" | "wrangler" | "vercel"
 }
 
@@ -466,7 +466,7 @@ export interface PortResult {
 
 /**
  * Compute the full `port` result: detect features, resolve the target, and derive the blocking findings.
- * A finding blocks when the detected feature is `unsupported` on the resolved target — always — and
+ * A finding blocks when the detected feature is `unsupported` on the resolved target - always - and
  * (with `strict`) also when it's a `caveat`. With no resolved target there's nothing to gate against,
  * so `blocked` is empty and `ok` reflects "are there hazards at all" only when the caller asks.
  */
@@ -523,19 +523,19 @@ const padCell = (s: string, width: number): string => {
 /** Render the feature × target matrix + evidence + summary as a readable report. */
 export function renderReport(result: PortResult, opts: { readonly strict?: boolean }): string {
   const { detected, resolved, json } = result
-  const out: string[] = ["nifra port — portability matrix", ""]
+  const out: string[] = ["nifra port - portability matrix", ""]
 
   if (resolved !== undefined) {
     out.push(`target: ${resolved.target} (detected from ${describeSource(resolved.source)})`)
   } else {
     out.push(
-      "target: not detected — pass --target <bun|node|deno|cf-pages|vercel> to gate against one",
+      "target: not detected - pass --target <bun|node|deno|cf-pages|vercel> to gate against one",
     )
   }
   out.push("")
 
   if (detected.length === 0) {
-    out.push("✓ no portability hazards detected — this app is portable across all targets.")
+    out.push("✓ no portability hazards detected - this app is portable across all targets.")
     return out.join("\n")
   }
 
@@ -583,9 +583,9 @@ export function renderReport(result: PortResult, opts: { readonly strict?: boole
         `✓ no blockers for ${resolved.target}, but ${caveatHere.length} feature(s) need a change there:`,
       )
       for (const f of caveatHere) {
-        out.push(`  ⚠ ${f.label} — ${FEATURES[f.id].reasons[resolved.target]}`)
+        out.push(`  ⚠ ${f.label} - ${FEATURES[f.id].reasons[resolved.target]}`)
       }
-      out.push("\n(caveats don't fail the gate — run with --strict to treat them as blockers)")
+      out.push("\n(caveats don't fail the gate - run with --strict to treat them as blockers)")
     }
     return out.join("\n")
   }
@@ -595,12 +595,12 @@ export function renderReport(result: PortResult, opts: { readonly strict?: boole
   out.push(`✗ ${json.blocked.length} feature(s) block deploying to ${resolved.target}:`)
   for (const b of [...unsupported, ...caveats]) {
     const mark = b.verdict === "unsupported" ? "✗" : "⚠"
-    out.push(`  ${mark} ${FEATURES[b.feature].label} — ${b.verdict} on ${resolved.target}`)
+    out.push(`  ${mark} ${FEATURES[b.feature].label} - ${b.verdict} on ${resolved.target}`)
     out.push(`      fix: ${b.reason}`)
     out.push(`      at:  ${b.evidence.join(", ")}`)
   }
   if (!opts.strict && unsupported.length === 0) {
-    out.push("\n(only caveats — run with --strict to fail on these)")
+    out.push("\n(only caveats - run with --strict to fail on these)")
   }
   return out.join("\n")
 }
@@ -630,7 +630,7 @@ export interface RunPortOptions {
 }
 
 /**
- * Run `nifra port`: detect, resolve, render. Returns `true` when the run "passes" — meaning either the
+ * Run `nifra port`: detect, resolve, render. Returns `true` when the run "passes" - meaning either the
  * gate is off, or the gate is on and nothing blocks. The caller maps `false` → exit 1.
  *
  * The gate fires when `--ci` is passed OR a `--target` is set (an explicit target signals intent to

package/src/recipes/1.8.0.ts

@@ -5,8 +5,8 @@ import type { UpgradeRecipe } from "./index.ts"
  *
  * 1.8.0 is a fixed-group bump: every `@nifrajs/*` package moves in lockstep. The pin sweep sets them
  * all to 1.8.0 (preserving each spec's `^`/`~`/exact style). 1.8.0 introduced no breaking import moves
- * in the public packages — the new surfaces (route assurance, adversarial testing, `@nifrajs/events`)
- * are additive — so `importMoves` is empty. The notes flag the additive follow-ups a bump can't do for
+ * in the public packages - the new surfaces (route assurance, adversarial testing, `@nifrajs/events`)
+ * are additive - so `importMoves` is empty. The notes flag the additive follow-ups a bump can't do for
  * you (wiring the new assurance config), keeping the runner honest about what it did and didn't touch.
  */
 export const recipe: UpgradeRecipe = {
@@ -14,8 +14,8 @@ export const recipe: UpgradeRecipe = {
   pins: [{ match: "@nifrajs/", to: "1.8.0" }],
   importMoves: [],
   notes: [
-    "1.8.0 adds route assurance (@nifrajs/core + middleware) — optional. To enforce it in CI, add a `nifra.assurance.ts` policy and run `nifra assure`.",
-    "New package @nifrajs/events (portable versioned event contracts) — add it to package.json only if you adopt it; the pin sweep won't introduce a dependency you don't already declare.",
-    "@nifrajs/testing gained the adversarial contract lab — no migration needed; existing tests are unchanged.",
+    "1.8.0 adds route assurance (@nifrajs/core + middleware) - optional. To enforce it in CI, add a `nifra.assurance.ts` policy and run `nifra assure`.",
+    "New package @nifrajs/events (portable versioned event contracts) - add it to package.json only if you adopt it; the pin sweep won't introduce a dependency you don't already declare.",
+    "@nifrajs/testing gained the adversarial contract lab - no migration needed; existing tests are unchanged.",
   ],
 }

package/src/recipes/index.ts

@@ -1,6 +1,6 @@
 /**
  * Per-release upgrade recipes, as data. Each recipe declares the mechanical edits a target version
- * needs — dependency pins and exact import-specifier moves — so `nifra upgrade <version>` can apply
+ * needs - dependency pins and exact import-specifier moves - so `nifra upgrade <version>` can apply
  * them deterministically. Recipes are static imports (they bundle) and keyed by target version.
  */
 
@@ -33,7 +33,7 @@ export interface UpgradeRecipe {
   readonly pins: readonly PinRule[]
   readonly dependencyMoves?: readonly DependencyMove[]
   readonly importMoves: readonly ImportMove[]
-  /** Human notes printed after the plan — e.g. structural changes the runner deliberately can't do. */
+  /** Human notes printed after the plan - e.g. structural changes the runner deliberately can't do. */
   readonly notes?: readonly string[]
 }
 

package/src/scaffold.ts

@@ -1,10 +1,10 @@
 /**
- * `nifra_scaffold` — turn a URL path into the correct `routes/` file (the convention an agent most often
+ * `nifra_scaffold` - turn a URL path into the correct `routes/` file (the convention an agent most often
  * gets wrong) + a minimal, contract-correct stub. The mapping is the inverse of @nifrajs/web's
  * `filePathToPatterns`: `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional,
  * `/` → `index`. The framework (→ file extension) comes from the project's `clientModule`.
  *
- * Page stubs are emitted only for the JSX family (react/preact/solid — one shared, verified shape);
+ * Page stubs are emitted only for the JSX family (react/preact/solid - one shared, verified shape);
  * for vue/svelte/vanilla we return the correct PATH + the route-module contract and point at
  * `nifra_example` for the body, rather than hand-writing an SFC we can't typecheck here.
  */
@@ -53,10 +53,10 @@ export function routePathToFile(urlPath: string, ext: string): string {
 }
 
 const ROUTE_CONTRACT = `A route module may export:
-- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` — the page component.
-- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` — server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
-- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` — server-only; handles the form POST.
-- \`export const meta = { title, meta:[…] }\` — head tags.
+- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` - the page component.
+- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` - server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
+- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` - server-only; handles the form POST.
+- \`export const meta = { title, meta:[…] }\` - head tags.
 Path params are typed on \`params\`.`
 
 function jsxStub(file: string, params: string[]): string {
@@ -66,7 +66,7 @@ function jsxStub(file: string, params: string[]): string {
     params.length > 0
       ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* fetch by ${params[0]} */ } }`
       : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`
-  return `// ${file} — server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
+  return `// ${file} - server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
 // Available here: ${paramsNote}. Fetch data in a loader via the typed \`api\`; see nifra_example("loader").
 ${loaderLine}
 export default function Page() {
@@ -151,7 +151,7 @@ export async function writeScaffoldRoute(
   return { ...result, written: true }
 }
 
-/** Render the tool result as markdown — the file path, the stub (if any), and the contract note. */
+/** Render the tool result as markdown - the file path, the stub (if any), and the contract note. */
 export function renderScaffold(urlPath: string, framework: Framework): string {
   let r: ScaffoldResult
   try {

package/src/sync-routes.ts

@@ -0,0 +1,69 @@
+/**
+ * `nifra sync-routes` - regenerate the route-search types (`nifra-routes.d.ts`) from the current `routes/`
+ * tree, so `navigate({ to, search })` is typed against each static route's `searchSchema`. It runs
+ * `@nifrajs/web`'s `generateRouteSearchTypes` over the discovered routes and writes the `.d.ts` at the
+ * project root; include it in your tsconfig's `include`. Because it is regenerated from the route files, a
+ * stale navigate search shape becomes a `tsc` error - run it after adding/renaming a route or changing a
+ * `searchSchema` (a pure file write, no build). A dynamic route (`:param`/catch-all) is omitted, since its
+ * pattern is not a concrete `to`; those keep the loose object form.
+ */
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+/** The committed route-types file `sync-routes` writes, so `nifra check` can recognise + drift-check it. */
+export const ROUTE_TYPES_FILE = "nifra-routes.d.ts"
+
+export interface SyncRoutesResult {
+  /** The written `.d.ts` (relative to the project root). */
+  readonly file: string
+  /** True when the file's content changed and it was rewritten. */
+  readonly changed: boolean
+  /** How many static routes got a typed entry. */
+  readonly typedRoutes: number
+}
+
+/**
+ * Generate the route-search types `.d.ts` from `<cwd>/routes` (the nifra convention). Returns `null` when
+ * there is no `routes/` directory (an API-only project - nothing to type). Never loads `framework.ts`: it
+ * needs only the route tree, so it works before a build and on a broken framework config.
+ */
+export async function syncRouteTypes(cwd: string): Promise<SyncRoutesResult | null> {
+  const routesDir = join(cwd, "routes")
+  if (!existsSync(routesDir)) return null
+  const { discoverRoutes } = await import("@nifrajs/web/fs")
+  const { generateRouteSearchTypes } = await import("@nifrajs/web")
+  const manifest = discoverRoutes(routesDir)
+  const code = generateRouteSearchTypes(manifest, {
+    // A route file is relative to routesDir (`reports.tsx`, `users/index.tsx`); the `.d.ts` sits at the
+    // project root, so the `typeof import(...)` specifier is `./routes/<file без extension>`.
+    resolve: (file) => `./routes/${file.replace(/\.[^./]+$/, "")}`,
+  })
+  const outFile = join(cwd, ROUTE_TYPES_FILE)
+  const existing = await Bun.file(outFile)
+    .text()
+    .catch(() => "")
+  const changed = existing !== code
+  if (changed) await Bun.write(outFile, code)
+  return { file: ROUTE_TYPES_FILE, changed, typedRoutes: (code.match(/: SearchOf</g) ?? []).length }
+}
+
+/** CLI entry: write/refresh the route-types file and print a one-line summary + the tsconfig reminder. */
+export async function runSyncRoutes(cwd: string): Promise<boolean> {
+  const result = await syncRouteTypes(cwd)
+  if (result === null) {
+    console.log("nifra sync-routes: no routes/ directory found. Run from your project root.")
+    return true
+  }
+  const n = result.typedRoutes
+  const routes = `${n} typed route${n === 1 ? "" : "s"}`
+  console.log(
+    result.changed
+      ? `✓ wrote ${result.file} (${routes})`
+      : `• ${result.file} already in sync (${routes})`,
+  )
+  console.log(
+    "  Include it in your tsconfig's `include` so `navigate({ to, search })` is typed per route.",
+  )
+  return true
+}

package/src/types-search.ts

@@ -1,7 +1,7 @@
 /**
- * `nifra_types` — the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
+ * `nifra_types` - the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
  * (written into this package by `bun run gen:llms`): each entry's `signature` is the literal declaration
- * parsed from the package's BUILT `.d.ts` with the TS compiler — a clean signature, never prose, never
+ * parsed from the package's BUILT `.d.ts` with the TS compiler - a clean signature, never prose, never
  * truncated. So an agent that needs the precise shape of a type (`RateLimitStore`, `RouteSchema`, a
  * function signature) gets the authoritative source here and never has to read a `.d.ts` file.
  *
@@ -15,7 +15,7 @@ export interface TypeEntry {
   readonly name: string
   readonly kind: "interface" | "type" | "class" | "function" | "enum" | "const"
   readonly package: string
-  /** The literal declaration text from the `.d.ts` — a clean signature, no implementation. */
+  /** The literal declaration text from the `.d.ts` - a clean signature, no implementation. */
   readonly signature: string
   /** The declaration's JSDoc block, if any. */
   readonly doc?: string
@@ -25,7 +25,7 @@ export interface ScoredType extends TypeEntry {
   readonly score: number
 }
 
-/** Exact (case-insensitive) name lookup — returns every declaration with that name (a name can exist in
+/** Exact (case-insensitive) name lookup - returns every declaration with that name (a name can exist in
  * more than one package). */
 export function lookupType(types: readonly TypeEntry[], name: string): TypeEntry[] {
   const wanted = name.trim().toLowerCase()
@@ -55,21 +55,69 @@ export function searchTypes(
 }
 
 function renderEntry(t: TypeEntry): string {
-  const head = `## ${t.name} — ${t.kind}, \`${t.package}\``
+  const head = `## ${t.name} - ${t.kind}, \`${t.package}\``
   const doc = t.doc ? `${t.doc}\n` : ""
   return `${head}\n\n\`\`\`ts\n${doc}${t.signature}\n\`\`\``
 }
 
+/**
+ * Longest signature rendered whole in a SEARCH result.
+ *
+ * Search is "which symbol did I mean?", not "show me everything about it" - and the corpus is wildly
+ * uneven: the median declaration is small, while `Server` alone is ~32,000 characters, five times the
+ * next largest. One broad query that happened to match it returned the entire class for near-zero
+ * value. Above this, a search result shows the head plus a member count and says how to get the rest;
+ * an exact `name` lookup is never collapsed, because there the caller asked for that symbol.
+ */
+const SEARCH_SIGNATURE_MAX = 600
+
+/** First sentence of the doc block, flattened to one line - enough to pick between candidates. */
+function summarize(doc: string | undefined): string {
+  if (doc === undefined) return ""
+  const text = doc
+    .replace(/\/\*\*|\*\/|^\s*\*/gm, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+  if (text === "") return ""
+  const end = text.search(/\.\s|\.$/)
+  const sentence = end === -1 ? text : text.slice(0, end + 1)
+  return sentence.length > 200 ? `${sentence.slice(0, 197)}...` : sentence
+}
+
+/** Keep the declaration head; replace a long body with a member count. */
+function collapseSignature(signature: string): string {
+  const open = signature.indexOf("{")
+  if (open === -1) return `${signature.slice(0, SEARCH_SIGNATURE_MAX)}…`
+  const body = signature.slice(open)
+  // Rough but honest: count top-level-looking member lines rather than parsing TypeScript here.
+  const members = body.split("\n").filter((line) => /^\s{2,4}\S/.test(line)).length
+  return `${signature.slice(0, open).trim()} { … ${members} members … }`
+}
+
+/** A search hit: enough to choose, not the whole declaration. */
+function renderSearchHit(t: TypeEntry): string {
+  const head = `## ${t.name} - ${t.kind}, \`${t.package}\``
+  const summary = summarize(t.doc)
+  const signature =
+    t.signature.length <= SEARCH_SIGNATURE_MAX ? t.signature : collapseSignature(t.signature)
+  const note =
+    t.signature.length <= SEARCH_SIGNATURE_MAX
+      ? ""
+      : `\n_Collapsed (${t.signature.length} chars). Call \`nifra_types({ name: "${t.name}" })\` for the full declaration._`
+  return `${head}\n${summary ? `\n${summary}\n` : ""}\n\`\`\`ts\n${signature}\n\`\`\`${note}`
+}
+
 /**
  * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
- * so this is the complete answer — there is no need to read a `.d.ts` file.
+ * so this is the complete answer - there is no need to read a `.d.ts` file.
  */
 export function renderTypesResult(
   types: readonly TypeEntry[],
   name: string | undefined,
   query: string | undefined,
   limit: number,
+  full = false,
 ): string {
   if (name !== undefined && name.trim() !== "") {
     const hits = lookupType(types, name)
@@ -83,7 +131,8 @@ export function renderTypesResult(
     if (matches.length === 0) {
       return `No types matched ${JSON.stringify(query)}. Try a broader term, pass an exact \`name\`, or call with no args for the index.`
     }
-    return matches.map(renderEntry).join("\n\n---\n\n")
+    // Search results are collapsed by default; `full` opts back into whole declarations.
+    return matches.map(full ? renderEntry : renderSearchHit).join("\n\n---\n\n")
   }
   const byPkg = new Map<string, string[]>()
   for (const t of types) {
@@ -95,7 +144,7 @@ export function renderTypesResult(
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([pkg, names]) => `- **${pkg}**: ${names.sort().join(", ")}`)
     .join("\n")
-  return `# nifra types — index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` — authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`
+  return `# nifra types - index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` - authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`
 }
 
 /** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from

package/src/upgrade.ts

@@ -1,20 +1,20 @@
 /**
- * `nifra upgrade <version>` — an executable, per-release upgrade runner. Framework and shared-package
+ * `nifra upgrade <version>` - an executable, per-release upgrade runner. Framework and shared-package
  * bumps otherwise spread the same mechanical edits across every consuming app by hand; a recipe turns
  * them into `detect → transform → verify`:
  *
- *   1. **pin sweep** — set every matching dependency to the target version across the workspace's
+ *   1. **pin sweep** - set every matching dependency to the target version across the workspace's
  *      package.json files, preserving the caret/tilde/exact style and skipping `workspace:`/`link:` specs.
- *   2. **dependency moves** — replace removed packages with their supported successor without
+ *   2. **dependency moves** - replace removed packages with their supported successor without
  *      reserializing package.json or leaving duplicate dependency keys.
- *   3. **import moves** — rewrite exact import specifiers to their updated module paths.
- *   4. **verify** — reuse the existing `nifra check` gate; no new verification surface.
+ *   3. **import moves** - rewrite exact import specifiers to their updated module paths.
+ *   4. **verify** - reuse the existing `nifra check` gate; no new verification surface.
  *
  * Dry-run by default (prints the plan, writes nothing); `--write` applies. Fail-closed on an unknown
  * target version or a missing package.json, and deterministic (same repo + target → same edits).
  *
  * Deliberately NOT a codemod engine: transforms are string/specifier-level only. Structural (AST)
- * transforms are a future addition — a recipe that needs one is the signal to add the engine, not before.
+ * transforms are a future addition - a recipe that needs one is the signal to add the engine, not before.
  */
 
 import { readFileSync, writeFileSync } from "node:fs"
@@ -75,8 +75,8 @@ const DEP_FIELDS = [
   "optionalDependencies",
 ] as const
 
-// Only a bare semver spec is rewritten. Anything else — workspace:*, link:/file:, npm: aliases, git
-// urls, "*", "latest", or a multi-part range — is intentionally left untouched (skipped, not guessed).
+// Only a bare semver spec is rewritten. Anything else - workspace:*, link:/file:, npm: aliases, git
+// urls, "*", "latest", or a multi-part range - is intentionally left untouched (skipped, not guessed).
 const SEMVER_SPEC =
   /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
 
@@ -95,7 +95,7 @@ export function rewriteVersionSpec(spec: string, toVersion: string): string | nu
 const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 /**
- * Apply pin rules to one package.json's TEXT (format-preserving — targeted string replaces, never a
+ * Apply pin rules to one package.json's TEXT (format-preserving - targeted string replaces, never a
  * JSON re-serialize that would reorder keys or drop comments-as-formatting). Returns the new text and
  * the changes made.
  */
@@ -336,7 +336,7 @@ function renderPlan(plan: UpgradePlan, write: boolean): string {
     plan.dependencyMoves.length === 0 &&
     plan.importMoves.length === 0
   ) {
-    lines.push("Already up to date — no changes.")
+    lines.push("Already up to date - no changes.")
     return lines.join("\n")
   }
   if (plan.dependencyMoves.length > 0) {
@@ -393,7 +393,7 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
     readFileSync(join(cwd, "package.json"), "utf8")
   } catch {
     console.error(
-      `[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} — run from a project root`,
+      `[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} - run from a project root`,
     )
     return false
   }
@@ -413,7 +413,7 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
     const ok = await runCheck(cwd, { json: false })
     if (!ok) {
       if (!options.json)
-        console.error("\n[nifra] upgrade applied but `nifra check` failed — review above.")
+        console.error("\n[nifra] upgrade applied but `nifra check` failed - review above.")
       return false
     }
   }