@nifrajs/cli 4.0.0 → 5.0.0

package/src/hooks-report.ts

@@ -0,0 +1,135 @@
+/**
+ * `nifra routes --hooks`: which hooks run for each route and for each prefix's unmatched paths, and the
+ * diff between two such reports (`--since <file>`, and `nifra upgrade`, which captures one before it
+ * writes). The report itself is `reflectHooks` from `@nifrajs/core/reflection`.
+ */
+import type { ReflectedHook, ReflectedHookReport } from "@nifrajs/core/reflection"
+
+/** Where `nifra upgrade --write` keeps the report it captured before editing anything. */
+export const HOOKS_BEFORE_UPGRADE_FILE = ".nifra/hooks-before-upgrade.json"
+
+export async function collectHookReport(backend: unknown): Promise<ReflectedHookReport> {
+  const { reflectHooks } = await import("@nifrajs/core/reflection")
+  return reflectHooks(backend)
+}
+
+const entryText = (hook: ReflectedHook): string =>
+  `${hook.kind} ${hook.name}${hook.headers === undefined ? "" : ` [${hook.headers.join(", ")}]`} (${hook.site})`
+
+/** One line per hook, keyed by `METHOD /path` for routes and `unmatched /prefix` for the rest. */
+export function hookReportTargets(report: ReflectedHookReport): Map<string, readonly string[]> {
+  const targets = new Map<string, readonly string[]>()
+  for (const route of report.routes) {
+    targets.set(`${route.method} ${route.path}`, route.hooks.map(entryText))
+  }
+  for (const entry of report.unmatched) {
+    targets.set(`unmatched ${entry.prefix}`, entry.hooks.map(entryText))
+  }
+  return targets
+}
+
+export function renderHookReport(report: ReflectedHookReport): string {
+  const targets = hookReportTargets(report)
+  if (targets.size === 0) return "no backend routes to report hooks for"
+  const lines: string[] = []
+  for (const [target, hooks] of targets) {
+    lines.push(target)
+    if (hooks.length === 0) lines.push("  (no hooks)")
+    for (const hook of hooks) lines.push(`  ${hook}`)
+  }
+  if (!report.complete) {
+    lines.push(
+      "",
+      "Some hooks have no recorded origin (site `unknown`): origins are recorded only outside production builds.",
+    )
+  }
+  return lines.join("\n")
+}
+
+export interface HookReportChange {
+  readonly target: string
+  readonly added: readonly string[]
+  readonly removed: readonly string[]
+}
+
+/** What runs differently: per route or unmatched prefix, the hooks it gained and lost. */
+export function diffHookReports(
+  before: ReflectedHookReport,
+  after: ReflectedHookReport,
+): readonly HookReportChange[] {
+  const old = hookReportTargets(before)
+  const now = hookReportTargets(after)
+  const changes: HookReportChange[] = []
+  const minus = (from: readonly string[], take: readonly string[]): string[] => {
+    const left = [...take]
+    return from.filter((entry) => {
+      const index = left.indexOf(entry)
+      if (index === -1) return true
+      left.splice(index, 1)
+      return false
+    })
+  }
+  const targets = [...new Set([...old.keys(), ...now.keys()])].sort()
+  for (const target of targets) {
+    const was = old.get(target) ?? []
+    const is = now.get(target) ?? []
+    const added = minus(is, was)
+    const removed = minus(was, is)
+    if (added.length > 0 || removed.length > 0) changes.push({ target, added, removed })
+  }
+  return changes
+}
+
+export function renderHookDiff(changes: readonly HookReportChange[]): string {
+  if (changes.length === 0) return "hook scope unchanged"
+  const lines: string[] = []
+  for (const change of changes) {
+    lines.push(change.target)
+    for (const entry of change.added) lines.push(`  + ${entry}`)
+    for (const entry of change.removed) lines.push(`  - ${entry}`)
+  }
+  return lines.join("\n")
+}
+
+const field = (value: unknown, key: string): unknown =>
+  typeof value === "object" && value !== null ? Reflect.get(value, key) : undefined
+
+const hooksValid = (row: unknown): boolean => {
+  const hooks = field(row, "hooks")
+  return (
+    Array.isArray(hooks) &&
+    hooks.every(
+      (hook) =>
+        typeof field(hook, "kind") === "string" &&
+        typeof field(hook, "name") === "string" &&
+        typeof field(hook, "site") === "string",
+    )
+  )
+}
+
+function isHookReport(value: unknown): value is ReflectedHookReport {
+  const routes = field(value, "routes")
+  const unmatched = field(value, "unmatched")
+  return (
+    typeof field(value, "complete") === "boolean" &&
+    Array.isArray(routes) &&
+    Array.isArray(unmatched) &&
+    routes.every(
+      (row) =>
+        typeof field(row, "method") === "string" &&
+        typeof field(row, "path") === "string" &&
+        hooksValid(row),
+    ) &&
+    unmatched.every((row) => typeof field(row, "prefix") === "string" && hooksValid(row))
+  )
+}
+
+/** A saved report, parsed; `undefined` when the text is not one. */
+export function parseHookReport(text: string): ReflectedHookReport | undefined {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isHookReport(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/init-agents.ts

@@ -9,8 +9,8 @@
  *                                   `## Project structure` section, appended when missing (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.
+ * The generators come from `./agent-files.ts`, a byte-identical copy of the module `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
@@ -44,7 +44,7 @@ import {
   MCP_SERVER_COMMAND,
   mcpJson,
   STRUCTURE_HEADING,
-} from "create-nifra/agent-files"
+} from "./agent-files.ts"
 import { installedNifraVersion, resolveRootState } from "./mcp-root.ts"
 
 /** What happened to one file during the retrofit, for the printed report + the `--json` shape. */
@@ -121,13 +121,17 @@ async function assertSafeParents(cwd: string, abs: string): Promise<void> {
   }
 }
 
-/** Refuse to write anything that is not a plain absent-or-regular file: a symlink here would
- * redirect the write, and a directory or device node would make it fail in a confusing way. */
-async function assertRegularTarget(abs: string, rel: string): Promise<void> {
+/** Never write anything that is not a plain absent-or-regular file: a symlink here would redirect
+ * the write, and a directory or device node would make it fail in a confusing way. Such a file is
+ * reported and left alone rather than stopping the run - a symlinked CLAUDE.md is a common alias
+ * for AGENTS.md. */
+async function nonRegularTarget(
+  abs: string,
+  rel: string,
+): Promise<InitAgentsFileResult | undefined> {
   const stat = await lstatOrMissing(abs)
-  if (stat !== undefined && (stat.isSymbolicLink() || !stat.isFile())) {
-    throw new Error(`[nifra] refusing to write non-regular file: ${rel}`)
-  }
+  if (stat === undefined || (stat.isFile() && !stat.isSymbolicLink())) return undefined
+  return { path: rel, action: "skipped", note: "not a regular file - left alone" }
 }
 
 /**
@@ -142,7 +146,8 @@ async function writeOwned(
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
   await assertSafeParents(cwd, abs)
-  await assertRegularTarget(abs, rel)
+  const irregular = await nonRegularTarget(abs, rel)
+  if (irregular !== undefined) return irregular
   if (!force && (await fileExists(abs))) {
     return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" }
   }
@@ -180,7 +185,8 @@ async function atomicWrite(
 async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, AGENTS_MD_PATH)
   await assertSafeParents(cwd, abs)
-  await assertRegularTarget(abs, AGENTS_MD_PATH)
+  const irregular = await nonRegularTarget(abs, AGENTS_MD_PATH)
+  if (irregular !== undefined) return irregular
   const sections = [{ heading: "## MCP server", text: agentsMcpSection() }]
   if (await isDirectory(safeJoin(cwd, "routes"))) {
     sections.push({ heading: STRUCTURE_HEADING, text: agentsStructureSection() })

package/src/internal/nifra-project.ts

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { CONFIG_FILE, FRAMEWORK_FILE } from "../app-files.ts"
+
+const NIFRA_PACKAGE = /^(?:@nifrajs\/|nifra$)/
+const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+]
+
+/** Whether a package.json text names `nifra` or a `@nifrajs/` package, or carries a `nifra` setting. */
+function declaresNifra(manifest: string): boolean {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(manifest)
+  } catch {
+    // A manifest nobody can read proves nothing either way, so the directory stays checked.
+    return true
+  }
+  if (typeof parsed !== "object" || parsed === null) return true
+  if ("nifra" in parsed) return true
+  return DEPENDENCY_FIELDS.some((field) => {
+    const deps: unknown = Reflect.get(parsed, field)
+    return (
+      typeof deps === "object" &&
+      deps !== null &&
+      Object.keys(deps).some((name) => NIFRA_PACKAGE.test(name))
+    )
+  })
+}
+
+/**
+ * Whether a project-relative directory ("" for the root) belongs to a nifra project, read statically.
+ * The checked root always does: running the check there says so. Below it, walking up, the first
+ * directory with a nifra config decides yes, and the first package.json decides by naming `nifra` or
+ * a `@nifrajs/` package, or carrying a `nifra` setting; a nested package that does none of that is
+ * another project, such as another framework's app kept beside this one.
+ */
+export function createNifraProjectProbe(root: string): (dir: string) => boolean {
+  const cache = new Map<string, boolean>()
+  const probe = (dir: string): boolean => {
+    const cached = cache.get(dir)
+    if (cached !== undefined) return cached
+    const at = join(root, dir)
+    let nifra: boolean
+    if (dir === "" || existsSync(join(at, CONFIG_FILE)) || existsSync(join(at, FRAMEWORK_FILE)))
+      nifra = true
+    else if (existsSync(join(at, "package.json"))) {
+      let manifest: string
+      try {
+        manifest = readFileSync(join(at, "package.json"), "utf8")
+      } catch {
+        manifest = ""
+      }
+      nifra = declaresNifra(manifest)
+    } else nifra = probe(dir.slice(0, Math.max(dir.lastIndexOf("/"), 0)))
+    cache.set(dir, nifra)
+    return nifra
+  }
+  return probe
+}
+
+export type ProjectKind = "api" | "web"
+
+export interface KindDeclaration {
+  /** `"api"` or `"web"` from `"nifra": { "kind" }`, or `undefined` when the package declares none. */
+  readonly kind: ProjectKind | undefined
+  /** The package.json that decides, relative to the checked root (`../package.json` above it). */
+  readonly manifest: string | undefined
+  /** The problem with a declared value that is neither `"api"` nor `"web"`. */
+  readonly invalid?: string
+}
+
+function readJson(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+const recordOf = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : undefined
+
+/**
+ * The `"nifra": { "kind" }` that governs a project-relative directory: read from the nearest
+ * package.json at or above it, the way the zone setting is read, with no app code run.
+ */
+export function createKindProbe(root: string): (dir: string) => KindDeclaration {
+  const cache = new Map<string, KindDeclaration>()
+  const probe = (absolute: string): KindDeclaration => {
+    const cached = cache.get(absolute)
+    if (cached !== undefined) return cached
+    let declaration: KindDeclaration
+    const manifestPath = join(absolute, "package.json")
+    if (existsSync(manifestPath)) {
+      const manifest = relative(root, manifestPath).replaceAll("\\", "/")
+      const kind = recordOf(recordOf(readJson(manifestPath))?.nifra)?.kind
+      if (kind === undefined) declaration = { kind: undefined, manifest }
+      else if (kind === "api" || kind === "web") declaration = { kind, manifest }
+      else
+        declaration = {
+          kind: undefined,
+          manifest,
+          invalid: `[nifra] ${manifest} "nifra.kind" must be "api" or "web", not ${JSON.stringify(kind)}`,
+        }
+    } else {
+      const parent = dirname(absolute)
+      declaration = parent === absolute ? { kind: undefined, manifest: undefined } : probe(parent)
+    }
+    cache.set(absolute, declaration)
+    return declaration
+  }
+  return (dir) => probe(join(root, dir))
+}
+
+/** Whether a project-relative directory holds web config: a `nifra.config.ts` exporting `adapter`, or
+ * `backend/framework.ts`. */
+export function hasWebConfig(root: string, dir: string): boolean {
+  if (existsSync(join(root, dir, FRAMEWORK_FILE))) return true
+  const config = join(root, dir, CONFIG_FILE)
+  if (!existsSync(config)) return false
+  let text: string
+  try {
+    text = readFileSync(config, "utf8")
+  } catch {
+    return true
+  }
+  return /\bexport\s+(?:const|let|var|function)\s+adapter\b|\bexport\s*\{[^}]*\badapter\b/.test(
+    text,
+  )
+}
+
+const WEB_PACKAGE = /^@nifrajs\/web(?:-[a-z0-9-]+)?$/
+
+/**
+ * Whether a project-relative directory ("" for the root) is inside a nifra web app. Walking up, the
+ * first directory with `nifra.config.ts` or `backend/framework.ts` makes it one; the first package.json
+ * decides instead: `"nifra": { "kind": "api" }` says no, otherwise naming `@nifrajs/web` or an adapter
+ * says yes. Nothing up to the root means no.
+ */
+export function createWebAppProbe(root: string): (dir: string) => boolean {
+  const cache = new Map<string, boolean>()
+  const probe = (dir: string): boolean => {
+    const cached = cache.get(dir)
+    if (cached !== undefined) return cached
+    const at = join(root, dir)
+    let web: boolean
+    if (existsSync(join(at, CONFIG_FILE)) || existsSync(join(at, FRAMEWORK_FILE))) web = true
+    else if (existsSync(join(at, "package.json"))) {
+      const manifest = recordOf(readJson(join(at, "package.json")))
+      web =
+        recordOf(manifest?.nifra)?.kind !== "api" &&
+        DEPENDENCY_FIELDS.some((field) => {
+          const deps = recordOf(manifest?.[field])
+          return deps !== undefined && Object.keys(deps).some((name) => WEB_PACKAGE.test(name))
+        })
+    } else web = dir !== "" && probe(dir.slice(0, Math.max(dir.lastIndexOf("/"), 0)))
+    cache.set(dir, web)
+    return web
+  }
+  return probe
+}
+
+/** A zone or server-only finding outside any web app, with the API-only setting named. */
+export const withApiKindHint = (message: string): string =>
+  `${message}${message.endsWith(".") ? "" : "."} If this project serves no pages, declare it in package.json: "nifra": { "kind": "api" }`
+
+/**
+ * Whether `"nifra": { "kind": "api" }` takes a project-relative directory out of the zone checks. It
+ * does only where no web config sits at or above the directory, up to the checked root: an app that
+ * serves pages keeps its zone checks whatever its package.json says (NF-C037 reports the clash).
+ */
+export function createApiOnlyProbe(root: string): (dir: string) => boolean {
+  const kindOf = createKindProbe(root)
+  const web = new Map<string, boolean>()
+  const webConfigUp = (dir: string): boolean => {
+    const cached = web.get(dir)
+    if (cached !== undefined) return cached
+    const found =
+      hasWebConfig(root, dir) ||
+      (dir !== "" && webConfigUp(dir.slice(0, Math.max(dir.lastIndexOf("/"), 0))))
+    web.set(dir, found)
+    return found
+  }
+  return (dir) => kindOf(dir).kind === "api" && !webConfigUp(dir)
+}