@nifrajs/cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/cli.ts

@@ -1,7 +1,4 @@
 #!/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:
@@ -12,24 +9,52 @@ import { discoverRoutes } from "@nifrajs/web/fs"
  *
  * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
  */
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { inProcessClient } from "@nifrajs/client"
+import { createWebApp, DEFAULT_DEV_PORT, type RenderAdapter } from "@nifrajs/web"
+import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
-import { describeProject } from "./introspect.ts"
+import { describeProject, describeRoutes } from "./introspect.ts"
 import { type LoadedApp, loadApp, resolvePlugins } from "./load.ts"
 
-interface Flags {
+export interface Flags {
   readonly port: number
   readonly out: string
   readonly poll: boolean
+  /** `nifra build --target <t>`: emit a full deploy dir for a target (bun/node/deno/cf-pages/vercel/
+   * static) instead of just the client bundle. Undefined ⇒ the legacy client-only build. */
+  readonly target?: string
+  /** `nifra build --report`: print a per-chunk size + gzip table after the build. */
+  readonly report: 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 dev     [--port <n>] [--poll]    Start the true-HMR dev server (Vite). Default port ${DEFAULT_DEV_PORT}.
   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).
+                [--target <t>] [--report]  With --target, emit a FULL deploy dir for <t>:
+                                         bun | node | deno | cf-pages | vercel | static. Packages
+                                         buildClient + buildServer (+ prerender for static) so an app
+                                         no longer hand-writes build-<target>.ts + _worker.ts +
+                                         _routes.json. The server entry is generated from your
+                                         framework.ts (adapter) + backend.ts + routes/. --report prints
+                                         a per-chunk size + gzip table (biggest first).
+  nifra start   [--port <n>] [--out <dir>]  Serve the built app (client + SSR) on Bun. Default port ${DEFAULT_DEV_PORT}.
+  nifra context                          Print this project's route INDEX (API + page routes) + conventions
+                                         for an AI agent's prompt. Per-route schemas: nifra mcp's
+                                         nifra_context (path/kind slice) or nifra routes --json.
+  nifra routes  [--json]                 List every route the app serves with its method(s): page
+                                         routes (routes/) + the in-process backend's API routes,
+                                         marking which API routes are auto-mounted under apiPrefix.
+                                         --json for agents (see POST /api/x is/isn't served, not via 405).
+  nifra init-agents [--force] [--json]   Retrofit an EXISTING app with the agent-discovery files a new
+                                         app ships: .mcp.json + .cursor/mcp.json (register this project's
+                                         nifra MCP), CLAUDE.md (MCP-first preamble + @AGENTS.md import),
+                                         and a "## MCP server" section in AGENTS.md. No-clobber by
+                                         default (skips a file you've customized); --force overwrites the
+                                         owned files. AGENTS.md is only appended to, never overwritten.
   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,
@@ -43,9 +68,18 @@ Usage:
   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.
+  nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
+                [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
+                                         globals, node: builtins) with file:line evidence. --target auto-
+                                         detected from build/deploy scripts, wrangler.toml, or vercel config;
+                                         --ci (or any --target) exits non-zero when a used feature is
+                                         unsupported on the target; --strict also fails on caveats.
 
 Reads nifra.config.ts (adapter + clientModule + plugins; or framework.ts), backend.ts (optional), and
-routes/ from the current directory. Run from your project root.`
+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).`
 
 const CLI_VERSION = "0.1.0-alpha.1"
 
@@ -97,6 +131,68 @@ async function build(app: LoadedApp): Promise<void> {
   console.log(`nifra build → ${outDir} (entry ${manifest.entry}${manifest.css ? ", + css" : ""})`)
 }
 
+/**
+ * `nifra build --target <t>` — package the engine (buildClient + buildServer + prerender) into one
+ * command that emits a full deploy dir, so an app no longer hand-writes build-bun.ts + _worker.ts +
+ * _routes.json per target. The adapter is imported from `framework.ts` (the edge-bundlable file — never
+ * `nifra.config.ts`, which pulls in Vite plugins), and the backend from `backend.ts` when present;
+ * `buildTarget` generates the per-target server entry from those + the app's `routes/`.
+ */
+async function buildForTarget(app: LoadedApp, target: string, report: boolean): Promise<void> {
+  const { buildTarget, isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import(
+    "@nifrajs/web/build"
+  )
+  if (!isBuildTarget(target)) {
+    throw new Error(`[nifra] unknown --target "${target}". Valid: ${BUILD_TARGETS.join(", ")}.`)
+  }
+  const { framework: fw, routesDir, outDir, cwd, backend } = app
+  // The server entry must import the adapter from `framework.ts` (edge-safe), not the loaded config.
+  // `loadApp` guarantees one of them exists; prefer framework.ts so a multi-target app's Vite-plugin
+  // config never reaches the edge bundle (see load.ts module header).
+  const frameworkFile = existsSync(resolve(cwd, "framework.ts"))
+    ? resolve(cwd, "framework.ts")
+    : existsSync(resolve(cwd, "nifra.config.ts"))
+      ? resolve(cwd, "nifra.config.ts")
+      : resolve(cwd, "framework.ts")
+  const backendFile = resolve(cwd, "backend.ts")
+  const result = await buildTarget(target, {
+    routesDir,
+    outDir,
+    workDir: resolve(cwd, ".nifra-build"),
+    clientModule: fw.clientModule,
+    adapterImport: frameworkFile,
+    ...(backend !== undefined && existsSync(backendFile) ? { backendImport: backendFile } : {}),
+    clientPlugins: asBunPlugins(await resolvePlugins(fw.clientPlugins)),
+    serverPlugins: asBunPlugins(await resolvePlugins(fw.serverPlugins)),
+    ...(fw.conditions ? { conditions: fw.conditions } : {}),
+    ...(fw.define ? { define: fw.define } : {}),
+    // The static target needs a built app to drive prerendering — only build it when targeting static.
+    ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
+  })
+  console.log(`nifra build (${target}) → ${result.run}`)
+  if (report) console.log(`\n${renderSizeReport(result.size)}`)
+}
+
+/** Build a fetch-capable app instance for the `static` target's prerender pass. Mirrors `nifra start`:
+ * register the framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import), discover routes,
+ * and wire the in-process backend so build-time loaders can read data. The returned `Server` already
+ * satisfies `buildTarget`'s `PrerenderAppLike` (a `fetch(req)` yielding a `Response`). */
+async function buildPrerenderApp(
+  app: LoadedApp,
+): Promise<{ fetch(req: Request): Response | Promise<Response> }> {
+  const { plugin } = await import("bun")
+  const { framework: fw, routesDir, backend } = app
+  for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
+  return createWebApp({
+    adapter: asAdapter(fw.adapter),
+    manifest: discoverRoutes(routesDir),
+    // The client entry is irrelevant to the static HTML (it's a hydration script tag) — a placeholder
+    // is fine; the real hashed bundle is emitted to /assets by buildTarget's client build.
+    clientEntry: "/assets/_nifra-entry.js",
+    ...apiOf(backend),
+  })
+}
+
 interface BuiltManifest {
   readonly entry: string
   readonly routes?: Readonly<Record<string, readonly string[]>>
@@ -144,20 +240,27 @@ async function start(app: LoadedApp, flags: Flags): Promise<void> {
   console.log(`nifra start → http://localhost:${running.port}`)
 }
 
-function parseFlags(args: readonly string[]): Flags {
-  let port = Number(Bun.env.PORT ?? 3000)
+export function parseFlags(args: readonly string[]): Flags {
+  // Port precedence: `--port`/`-p` (most specific) > `PORT` env > the framework default. The default is
+  // the SAME uncommon port for `nifra dev` and `nifra start` (DEFAULT_DEV_PORT) so a project's URL is
+  // stable across commands and doesn't collide with the usual 3000/5173/8080 crowd.
+  let port = Number(Bun.env.PORT ?? DEFAULT_DEV_PORT)
   let out = "dist"
   let poll = Bun.env.CHOKIDAR_USEPOLLING === "1"
+  let target: string | undefined
+  let report = false
   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
+    else if (a === "--target" && args[i + 1]) target = args[++i]
+    else if (a === "--report") report = true
   }
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     throw new Error(`[nifra] invalid --port: ${port}`)
   }
-  return { port, out, poll }
+  return { port, out, poll, report, ...(target !== undefined ? { target } : {}) }
 }
 
 async function main(): Promise<void> {
@@ -204,6 +307,17 @@ async function main(): Promise<void> {
       process.exitCode = 1
     return
   }
+  // `init-agents` retrofits the agent-discovery files (.mcp.json, CLAUDE.md, …) into the cwd. It's a
+  // pure file-writing command independent of the app loading, so dispatch it before the eager `loadApp`
+  // (an existing app might be API-only or not yet built). It always succeeds unless a write throws.
+  if (command === "init-agents") {
+    const { runInitAgents } = await import("./init-agents.ts")
+    await runInitAgents(process.cwd(), {
+      json: argv.includes("--json"),
+      force: argv.includes("--force"),
+    })
+    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") {
@@ -217,7 +331,38 @@ async function main(): Promise<void> {
       process.exitCode = 1
     return
   }
-  if (command !== "dev" && command !== "build" && command !== "start" && command !== "context") {
+  // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) — like `check`/
+  // `doctor`, dispatch before the eager `loadApp` so it runs on an API-only / not-yet-built project.
+  if (command === "port") {
+    const { runPort } = await import("./port.ts")
+    const targetIdx = argv.indexOf("--target")
+    const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined
+    if (targetIdx !== -1 && (target === undefined || target.startsWith("-"))) {
+      console.error("[nifra] --target needs a value: bun | node | deno | cf-pages | vercel")
+      process.exitCode = 1
+      return
+    }
+    try {
+      const passed = await runPort(process.cwd(), {
+        ...(target !== undefined ? { target } : {}),
+        json: argv.includes("--json"),
+        ci: argv.includes("--ci"),
+        strict: argv.includes("--strict"),
+      })
+      if (!passed) process.exitCode = 1
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (
+    command !== "dev" &&
+    command !== "build" &&
+    command !== "start" &&
+    command !== "context" &&
+    command !== "routes"
+  ) {
     console.error(`[nifra] unknown command: ${command}\n`)
     console.error(HELP)
     process.exitCode = 1
@@ -226,12 +371,22 @@ async function main(): Promise<void> {
   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)
+  else if (command === "build") {
+    // `--target` (or `--report`) → the full per-target deploy build; otherwise the legacy client build.
+    if (flags.target !== undefined || flags.report) {
+      await buildForTarget(app, flags.target ?? "cf-pages", flags.report)
+    } else await build(app)
+  } else if (command === "context") console.log(describeProject(app))
+  else if (command === "routes") {
+    console.log(await describeRoutes(app, { json: argv.includes("--json") }))
+  } else await start(app, flags)
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err))
-  process.exitCode = 1
-})
+// 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) => {
+    console.error(err instanceof Error ? err.message : String(err))
+    process.exitCode = 1
+  })
+}

package/src/init-agents.ts

@@ -0,0 +1,176 @@
+/**
+ * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * app ships, so an already-built project adopts the nifra MCP in one command:
+ *
+ *   .mcp.json          — Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
+ *   .cursor/mcp.json   — Cursor's MCP registry (same server config)
+ *   CLAUDE.md          — Claude's MCP-first preamble + `@AGENTS.md` import
+ *   AGENTS.md          — a `## MCP server` section appended (or a minimal file if none exists)
+ *
+ * The generators are imported from `create-nifra/agent-files` — the SAME source of truth `create-nifra`
+ * uses at scaffold time — so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ *
+ * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
+ * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
+ * notice; `--force` overwrites. `AGENTS.md` is special-cased — if it already has the MCP section it's
+ * left alone, otherwise the section is APPENDED (never overwriting the user's conventions), and `--force`
+ * is not needed for that append since it's additive. Every write path is resolved + confined under the
+ * cwd (no `..` traversal escaping the project root).
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { isAbsolute, relative, resolve } from "node:path"
+import {
+  AGENTS_MD_PATH,
+  agentsMcpSection,
+  CLAUDE_MD_PATH,
+  CURSOR_MCP_JSON_PATH,
+  claudeMd,
+  MCP_JSON_PATH,
+  mcpJson,
+} from "create-nifra/agent-files"
+
+/** What happened to one file during the retrofit, for the printed report + the `--json` shape. */
+export interface InitAgentsFileResult {
+  /** Project-root-relative POSIX path. */
+  readonly path: string
+  /** `wrote` — created or (with --force) overwrote; `appended` — added the MCP section to an existing
+   * AGENTS.md; `skipped` — already present and not forced; `present` — MCP section already there. */
+  readonly action: "wrote" | "appended" | "skipped" | "present"
+  /** Why it was skipped/left, for the notice (e.g. "exists — pass --force to overwrite"). */
+  readonly note?: string
+}
+
+export interface InitAgentsResult {
+  readonly cwd: string
+  readonly files: readonly InitAgentsFileResult[]
+}
+
+export interface InitAgentsOptions {
+  /** Overwrite an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` instead of skipping it. */
+  readonly force?: boolean
+}
+
+/** Confine a project-relative path under `cwd` and return the absolute path. Rejects a spec that escapes
+ * the root (defense-in-depth — these specs are constants, but the cwd-confinement invariant is enforced
+ * at the seam, not assumed). Exported so the invariant is directly testable. */
+export function safeJoin(cwd: string, rel: string): string {
+  const abs = resolve(cwd, rel)
+  const within = relative(cwd, abs)
+  if (within.startsWith("..") || isAbsolute(within)) {
+    throw new Error(`[nifra] refusing to write outside the project root: ${rel}`)
+  }
+  return abs
+}
+
+const fileExists = (path: string): Promise<boolean> =>
+  readFile(path)
+    .then(() => true)
+    .catch(() => false)
+
+/**
+ * Write a whole-file generator's output to `path` unless it already exists and `force` is false.
+ * Returns the per-file result for the report.
+ */
+async function writeOwned(
+  cwd: string,
+  rel: string,
+  content: string,
+  force: boolean,
+): Promise<InitAgentsFileResult> {
+  const abs = safeJoin(cwd, rel)
+  if (!force && (await fileExists(abs))) {
+    return { path: rel, action: "skipped", note: "exists — pass --force to overwrite" }
+  }
+  // `.cursor/mcp.json` needs its parent dir; `recursive` is a no-op for the root-level files.
+  await mkdir(resolve(abs, ".."), { recursive: true })
+  await writeFile(abs, content)
+  return { path: rel, action: "wrote" }
+}
+
+/**
+ * AGENTS.md is additive, not owned: if it exists and already has the MCP section, leave it; if it exists
+ * without the section, append the section (preserving the user's conventions); if it's absent, write a
+ * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here — we never
+ * overwrite the user's existing guidance.
+ */
+async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
+  const abs = safeJoin(cwd, AGENTS_MD_PATH)
+  const section = agentsMcpSection()
+  let existing: string | undefined
+  try {
+    existing = await readFile(abs, "utf8")
+  } catch {
+    existing = undefined // no AGENTS.md yet
+  }
+  if (existing === undefined) {
+    await writeFile(
+      abs,
+      `# AGENTS.md\n\nGuidance for AI coding agents working in this repo.\n\n${section}\n`,
+    )
+    return { path: AGENTS_MD_PATH, action: "wrote" }
+  }
+  // Match on the section heading, not the full body, so a reformatted-but-present section still counts.
+  if (existing.includes("## MCP server")) {
+    return { path: AGENTS_MD_PATH, action: "present", note: "already has an MCP section" }
+  }
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n"
+  await writeFile(abs, `${existing}${sep}${section}\n`)
+  return { path: AGENTS_MD_PATH, action: "appended" }
+}
+
+/**
+ * Retrofit `cwd` with the four agent-discovery files. Pure enough to unit-test (no argv, no process.exit,
+ * no console) — the CLI wrapper handles printing + the exit code.
+ */
+export async function initAgents(
+  cwd: string,
+  opts: InitAgentsOptions = {},
+): Promise<InitAgentsResult> {
+  const force = opts.force ?? false
+  // Order: the two MCP registries + CLAUDE.md (owned, no-clobber), then AGENTS.md (additive).
+  const files: InitAgentsFileResult[] = []
+  files.push(await writeOwned(cwd, MCP_JSON_PATH, mcpJson(), force))
+  files.push(await writeOwned(cwd, CURSOR_MCP_JSON_PATH, mcpJson(), force))
+  files.push(await writeOwned(cwd, CLAUDE_MD_PATH, claudeMd(), force))
+  files.push(await ensureAgentsMd(cwd))
+  return { cwd, files }
+}
+
+const ACTION_GLYPH: Readonly<Record<InitAgentsFileResult["action"], string>> = {
+  wrote: "✓ wrote",
+  appended: "✓ appended MCP section to",
+  skipped: "• skipped",
+  present: "• kept",
+}
+
+/** Format the retrofit result for the terminal. */
+export function renderInitAgents(result: InitAgentsResult): string {
+  const lines = result.files.map((f) => {
+    const tail = f.note ? `  (${f.note})` : ""
+    return `  ${ACTION_GLYPH[f.action]} ${f.path}${tail}`
+  })
+  const wroteAny = result.files.some((f) => f.action === "wrote" || f.action === "appended")
+  const footer = wroteAny
+    ? "\nThe nifra MCP is now registered. Restart your agent so it picks up .mcp.json, then prefer nifra_docs / nifra_example and gate on nifra check."
+    : "\nNothing to do — every file was already present (use --force to overwrite the owned ones)."
+  return `nifra init-agents\n\n${lines.join("\n")}\n${footer}`
+}
+
+/**
+ * CLI entry: run the retrofit at `cwd` and print the result. Returns `true` (the command always succeeds
+ * unless a write throws — which propagates as a non-zero exit via the dispatcher's catch). `--json`
+ * emits the structured result for agents/CI.
+ */
+export async function runInitAgents(
+  cwd: string,
+  opts: { readonly json?: boolean; readonly force?: boolean } = {},
+): Promise<boolean> {
+  const result = await initAgents(cwd, { force: opts.force ?? false })
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    console.log(renderInitAgents(result))
+  }
+  return true
+}