@nifrajs/cli 0.1.0-alpha.1

package/src/cli.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env bun
+import { inProcessClient } from "@nifrajs/client"
+import { createWebApp, type RenderAdapter } from "@nifrajs/web"
+import { discoverRoutes } from "@nifrajs/web/fs"
+/**
+ * `nifra` — the zero-config CLI for a nifra app. Reads `framework.ts` + `backend.ts` + `routes/` from
+ * the project root (see {@link loadApp}) and wires the right `@nifrajs/web` entrypoint:
+ *
+ *   nifra dev      true-HMR dev server (Vite middleware + nifra SSR)        — @nifrajs/web/vite
+ *   nifra build    bundle the client (content-hashed) + write manifest.json — @nifrajs/web/build
+ *   nifra start    serve the built client + SSR on Bun.serve              — @nifrajs/web
+ *
+ * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
+ */
+import type { BunPlugin } from "bun"
+import { describeProject } from "./introspect.ts"
+import { type LoadedApp, loadApp, resolvePlugins } from "./load.ts"
+
+interface Flags {
+  readonly port: number
+  readonly out: string
+  readonly poll: boolean
+}
+
+const HELP = `nifra — zero-config dev/build/start for a nifra app
+
+Usage:
+  nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Vite).
+  nifra build   [--out <dir>]            Bundle the client + write manifest.json.
+  nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun.
+  nifra context                          Print this project's API + page routes + conventions
+                                         (for piping into an AI coding agent's prompt).
+  nifra mcp                              Start an MCP server (stdio) exposing this project to a coding
+                                         agent: nifra_context, nifra_routes (routes+schemas as JSON),
+                                         nifra_run (backend), nifra_render (SSR a page), nifra_docs,
+                                         nifra_example (verified snippets), nifra_scaffold (route→file),
+                                         nifra_check (drift gate + fixes), nifra_doctor (undeclared deps).
+  nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) —
+                                         self-host on a VPS so any remote agent can learn nifra. Default :8787.
+  nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
+                                         server-only imports in routes/). Run as "done"; --json for agents;
+                                         --lints-only skips tsc for a near-instant inner-loop pass.
+  nifra doctor  [--json] [--auto-fix]    Flag packages imported in source but missing from package.json
+                                         (resolve at Bun runtime, break tsc + standalone install);
+                                         --auto-fix writes safe local-version dependency fixes.
+
+Reads nifra.config.ts (adapter + clientModule + plugins; or framework.ts), backend.ts (optional), and
+routes/ from the current directory. Run from your project root.`
+
+const CLI_VERSION = "0.1.0-alpha.1"
+
+// 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
+const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
+const apiOf = (backend: unknown): { api?: unknown } =>
+  backend === undefined ? {} : { api: inProcessClient(backend as never) }
+
+async function dev(app: LoadedApp, flags: Flags): Promise<void> {
+  const { plugin } = await import("bun")
+  const { createViteDevServer } = await import("@nifrajs/web/vite")
+  const { framework: fw, routesDir, cwd, backend } = app
+  // nifra SSRs each request by importing the route modules through Bun (not Vite's ssrLoadModule), so
+  // `.vue`/`.svelte`/Solid routes need their SSR compile plugin registered on Bun's runtime first —
+  // the dev analog of `nifra start`. React/Preact JSX is Bun-native → no server plugins → no-op.
+  for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
+  const server = await createViteDevServer({
+    root: cwd,
+    routesDir,
+    clientModule: fw.clientModule,
+    plugins: await resolvePlugins(fw.vitePlugins),
+    poll: flags.poll,
+    port: flags.port,
+    ...(fw.conditions ? { conditions: fw.conditions } : {}),
+    ...(fw.define ? { define: fw.define } : {}),
+    createApp: (clientEntry, importQuery) =>
+      createWebApp({
+        adapter: asAdapter(fw.adapter),
+        manifest: discoverRoutes(routesDir, { importQuery }),
+        clientEntry,
+        ...apiOf(backend),
+      }),
+  })
+  console.log(`nifra dev → http://localhost:${server.port}`)
+}
+
+async function build(app: LoadedApp): Promise<void> {
+  const { buildClient } = await import("@nifrajs/web/build")
+  const { framework: fw, routesDir, outDir } = app
+  const manifest = await buildClient({
+    routesDir,
+    outDir,
+    clientModule: fw.clientModule,
+    plugins: asBunPlugins(await resolvePlugins(fw.clientPlugins)),
+    define: { "process.env.NODE_ENV": '"production"', ...(fw.define ?? {}) },
+    ...(fw.conditions ? { conditions: fw.conditions } : {}),
+  })
+  console.log(`nifra build → ${outDir} (entry ${manifest.entry}${manifest.css ? ", + css" : ""})`)
+}
+
+interface BuiltManifest {
+  readonly entry: string
+  readonly routes?: Readonly<Record<string, readonly string[]>>
+  readonly css?: readonly string[]
+  readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+}
+
+async function start(app: LoadedApp, flags: Flags): Promise<void> {
+  const { plugin } = await import("bun")
+  const { framework: fw, routesDir, outDir, backend } = app
+  // Register the framework's SSR Bun plugins so `.vue`/`.svelte`/Solid route files compile on the
+  // server's runtime import (React/Preact JSX is Bun-native → none).
+  for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
+
+  const manifestFile = Bun.file(`${outDir}/manifest.json`)
+  if (!(await manifestFile.exists())) {
+    throw new Error(`[nifra] no ${outDir}/manifest.json — run \`nifra build\` first.`)
+  }
+  const manifest = JSON.parse(await manifestFile.text()) as BuiltManifest
+
+  const server = createWebApp({
+    adapter: asAdapter(fw.adapter),
+    manifest: discoverRoutes(routesDir),
+    clientEntry: manifest.entry,
+    ...(manifest.routes ? { routePreload: manifest.routes } : {}),
+    ...(manifest.css ? { styles: manifest.css } : {}),
+    ...(manifest.routeStyles ? { routeStyles: manifest.routeStyles } : {}),
+    ...apiOf(backend),
+  })
+  // Serve the content-hashed bundle (immutable). `.css` → text/css, else JS. Name is path-validated.
+  server.get("/assets/*", async (c) => {
+    const name = new URL(c.req.url).pathname.slice("/assets/".length)
+    if (!/^[A-Za-z0-9._-]+$/.test(name)) return new Response("bad request", { status: 400 })
+    const file = Bun.file(`${outDir}/${name}`)
+    if (!(await file.exists())) return new Response("Not Found", { status: 404 })
+    const type = name.endsWith(".css") ? "text/css" : "text/javascript"
+    return new Response(file, {
+      headers: {
+        "content-type": `${type}; charset=utf-8`,
+        "cache-control": "public, max-age=31536000, immutable",
+      },
+    })
+  })
+  const running = server.listen(flags.port)
+  console.log(`nifra start → http://localhost:${running.port}`)
+}
+
+function parseFlags(args: readonly string[]): Flags {
+  let port = Number(Bun.env.PORT ?? 3000)
+  let out = "dist"
+  let poll = Bun.env.CHOKIDAR_USEPOLLING === "1"
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if ((a === "--port" || a === "-p") && args[i + 1]) port = Number(args[++i])
+    else if (a === "--out" && args[i + 1]) out = args[++i] as string
+    else if (a === "--poll") poll = true
+  }
+  if (!Number.isFinite(port) || port < 0 || port > 65535) {
+    throw new Error(`[nifra] invalid --port: ${port}`)
+  }
+  return { port, out, poll }
+}
+
+async function main(): Promise<void> {
+  const argv = Bun.argv.slice(2)
+  const command = argv[0]
+  if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+    console.log(HELP)
+    return
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(`nifra (@nifrajs/cli) ${CLI_VERSION}`)
+    return
+  }
+  // `mcp` runs a long-lived stdio server and loads the project lazily per-tool — it must not go through
+  // the eager `loadApp` below (which would fail fast on a project that's API-only / not yet built).
+  if (command === "mcp") {
+    const { runMcpServer } = await import("./mcp.ts")
+    await runMcpServer(process.cwd(), CLI_VERSION)
+    return
+  }
+  // `docs-mcp` runs the PUBLIC docs MCP over HTTP — project-independent (serves the bundled corpus), so
+  // it self-hosts anywhere Bun runs (a VPS behind a reverse proxy, a container). Long-lived; no loadApp.
+  if (command === "docs-mcp") {
+    const { handleMcpHttp } = await import("./mcp-http.ts")
+    const portArg = argv[argv.indexOf("--port") + 1]
+    const port = Number(portArg && argv.includes("--port") ? portArg : (Bun.env.PORT ?? 8787))
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      throw new Error(`[nifra] invalid --port: ${port}`)
+    }
+    const server = Bun.serve({ port, fetch: handleMcpHttp })
+    console.log(`nifra docs MCP (HTTP) → ${server.url}`)
+    return
+  }
+  // `check` is a pure cwd-based gate (typecheck + lint) — it must run even when the project doesn't
+  // load (API-only, not built yet), so it dispatches before the eager `loadApp` below.
+  if (command === "check") {
+    const { runCheck } = await import("./check.ts")
+    if (
+      !(await runCheck(process.cwd(), {
+        json: argv.includes("--json"),
+        lintsOnly: argv.includes("--lints-only"),
+      }))
+    )
+      process.exitCode = 1
+    return
+  }
+  // `doctor` is a pure cwd check (imports vs declared deps) — like `check`, dispatch before `loadApp`
+  // so it runs on an API-only / not-yet-built project.
+  if (command === "doctor") {
+    const { runDoctor } = await import("./doctor.ts")
+    if (
+      !(await runDoctor(process.cwd(), {
+        json: argv.includes("--json"),
+        autoFix: argv.includes("--auto-fix") || argv.includes("--fix"),
+      }))
+    )
+      process.exitCode = 1
+    return
+  }
+  if (command !== "dev" && command !== "build" && command !== "start" && command !== "context") {
+    console.error(`[nifra] unknown command: ${command}\n`)
+    console.error(HELP)
+    process.exitCode = 1
+    return
+  }
+  const flags = parseFlags(argv.slice(1))
+  const app = await loadApp(process.cwd(), flags.out)
+  if (command === "dev") await dev(app, flags)
+  else if (command === "build") await build(app)
+  else if (command === "context") console.log(describeProject(app))
+  else await start(app, flags)
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exitCode = 1
+})

package/src/docs-search.ts

@@ -0,0 +1,111 @@
+/**
+ * `nifra_docs` — searchable framework documentation for agents. The corpus is the generated
+ * `llms-full.txt` (written into this package by `bun run gen:llms`, so it can't drift from the
+ * source it's generated from). Instead of dumping the whole ~150 KB into an agent's context, the
+ * tool keyword-scores the document's `##` sections and returns only the top matches — or, with no
+ * query, just the section index (the cheap discovery call).
+ *
+ * Deliberately NOT a vector search: the corpus is one curated document with descriptive headings;
+ * weighted keyword scoring over sections is deterministic, dependency-free, and good enough that
+ * embedding infra would be complexity without a payoff.
+ */
+
+import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.ts"
+
+export interface DocSection {
+  readonly heading: string
+  readonly body: string
+}
+
+/** Split the generated doc into its `##` sections (the `# title` intro becomes "Overview"). */
+export function splitSections(markdown: string): DocSection[] {
+  const out: DocSection[] = []
+  const lines = markdown.split("\n")
+  let heading = "Overview"
+  let buf: string[] = []
+  const flush = (): void => {
+    const body = buf.join("\n").trim()
+    if (body.length > 0) out.push({ heading, body })
+    buf = []
+  }
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      flush()
+      heading = line.slice(3).trim()
+    } else {
+      buf.push(line)
+    }
+  }
+  flush()
+  return out
+}
+
+export interface ScoredSection extends DocSection {
+  readonly score: number
+}
+
+/** Score sections against the query: a term in the HEADING is worth far more than body mentions
+ * (headings are curated names for exactly these lookups); body occurrences cap per term so one
+ * spammy section can't drown a precisely-titled one. */
+export function searchSections(
+  sections: readonly DocSection[],
+  query: string,
+  limit: number,
+): ScoredSection[] {
+  const terms = queryTermGroups(query)
+  if (terms.length === 0) return []
+  const scored: ScoredSection[] = []
+  for (const section of sections) {
+    const headingTokens = new Set(tokenize(section.heading))
+    const bodyLower = section.body.toLowerCase()
+    let score = 0
+    for (const term of terms) {
+      if (tokenSetHas(headingTokens, term)) score += 8
+      score += countBodyHits(bodyLower, term, 5)
+    }
+    if (score > 0) scored.push({ ...section, score })
+  }
+  return scored.sort((a, b) => b.score - a.score).slice(0, limit)
+}
+
+/** Cap a section body for the tool result — whole sections can be pages long; the agent can ask
+ * again with a narrower query if the trim cuts what it needed. */
+const MAX_SECTION_CHARS = 2800
+
+/** Render the tool result: matched sections, or the index when no query was given. */
+export function renderDocsResult(
+  markdown: string,
+  query: string | undefined,
+  limit: number,
+): string {
+  const sections = splitSections(markdown)
+  if (query === undefined || query.trim() === "") {
+    const index = sections.map((s) => `- ${s.heading}`).join("\n")
+    return `# nifra docs — section index (pass \`query\` to fetch matching sections)\n\n${index}`
+  }
+  const matches = searchSections(sections, query, limit)
+  if (matches.length === 0) {
+    return `No docs sections matched ${JSON.stringify(query)}. Call without a query for the section index.`
+  }
+  return matches
+    .map((m) => {
+      const body =
+        m.body.length > MAX_SECTION_CHARS
+          ? `${m.body.slice(0, MAX_SECTION_CHARS)}\n…(trimmed — narrow the query for the rest)`
+          : m.body
+      return `## ${m.heading}\n\n${body}`
+    })
+    .join("\n\n---\n\n")
+}
+
+/** Load the bundled corpus. Resolves relative to this module so it works from `src/` (repo dev)
+ * and `dist/` (published) alike — `docs/llms-full.txt` sits at the package root next to both. */
+export async function loadDocsCorpus(): Promise<string | undefined> {
+  const url = new URL("../docs/llms-full.txt", import.meta.url)
+  try {
+    const text = await Bun.file(url).text()
+    return text.length > 0 ? text : undefined
+  } catch {
+    return undefined
+  }
+}