@nifrajs/cli 1.5.0 → 1.11.0

package/src/manifest-tool.ts

@@ -0,0 +1,103 @@
+/** `nifra manifest` — emit/sign/diff the deployable route trust artifact. */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
+import {
+  buildNifraManifest,
+  diffNifraManifests,
+  type NifraManifestDiff,
+  parseNifraManifest,
+  serializeNifraManifest,
+  serializeNifraManifestSignature,
+  signNifraManifest,
+} from "@nifrajs/core/manifest"
+import { loadAssuranceConfig } from "./assure.ts"
+import { collectCapabilityProjectReport } from "./capabilities-tool.ts"
+
+export const DEFAULT_MANIFEST_FILE = "nifra.manifest.json"
+
+export function formatManifestDiff(diff: NifraManifestDiff): string {
+  if (diff.changes.length === 0) return "No manifest changes."
+  const weight = { breaking: 0, compatible: 1, info: 2 } as const
+  const lines = [...diff.changes]
+    .sort(
+      (a, b) =>
+        weight[a.severity] - weight[b.severity] ||
+        a.path.localeCompare(b.path) ||
+        a.method.localeCompare(b.method),
+    )
+    .map(
+      (change) =>
+        `${change.severity === "breaking" ? "✖" : change.severity === "compatible" ? "✓" : "•"} ${change.method} ${change.path} [${change.section}] ${change.message}`,
+    )
+  const breaking = diff.changes.filter((change) => change.severity === "breaking").length
+  lines.push(
+    diff.hasBreaking
+      ? `${breaking} breaking manifest change${breaking === 1 ? "" : "s"}.`
+      : "No breaking manifest changes.",
+  )
+  return lines.join("\n")
+}
+
+/** Build only after both assurance layers pass, then optionally create an operator-signed sidecar. */
+export async function runManifestEmit(
+  cwd: string,
+  options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
+): Promise<boolean> {
+  const config = await loadAssuranceConfig(cwd, options.config)
+  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  const capabilityProject =
+    config.capabilities === undefined
+      ? undefined
+      : await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+  if (!assurance.ok || (capabilityProject !== undefined && !capabilityProject.report.ok)) {
+    console.error("[nifra] refusing to emit a manifest from failing assurance")
+    return false
+  }
+  const manifest = await buildNifraManifest({
+    source: config.source,
+    assurance,
+    ...(capabilityProject !== undefined ? { capabilities: capabilityProject.report } : {}),
+  })
+  const path = resolve(cwd, options.out ?? config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
+  await Bun.write(path, `${serializeNifraManifest(manifest)}\n`)
+
+  if (options.sign !== undefined) {
+    if (config.manifest?.signer === undefined) {
+      throw new Error(
+        "[nifra] --sign requires manifest.signer in nifra.assurance.ts; keep private keys behind that KMS/HSM callback.",
+      )
+    }
+    const signer = await config.manifest.signer(options.sign)
+    const signature = await signNifraManifest(manifest, signer)
+    await Bun.write(`${path}.sig`, `${serializeNifraManifestSignature(signature)}\n`)
+  }
+  console.log(
+    `[nifra] wrote manifest to ${path}${options.sign === undefined ? "" : ` and ${path}.sig`}`,
+  )
+  return true
+}
+
+/** Diff two already-emitted, hash-verified artifacts. Suitable for deploy promotion gates. */
+export async function runManifestDiff(
+  cwd: string,
+  beforePath: string,
+  afterPath: string,
+  options: { readonly json?: boolean } = {},
+): Promise<boolean> {
+  const before = resolve(cwd, beforePath)
+  const after = resolve(cwd, afterPath)
+  if (!existsSync(before)) throw new Error(`[nifra] manifest not found: ${before}`)
+  if (!existsSync(after)) throw new Error(`[nifra] manifest not found: ${after}`)
+  const diff = diffNifraManifests(
+    await parseNifraManifest(await Bun.file(before).text(), before),
+    await parseNifraManifest(await Bun.file(after).text(), after),
+  )
+  console.log(
+    options.json === true
+      ? JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2)
+      : formatManifestDiff(diff),
+  )
+  return !diff.hasBreaking
+}

package/src/mcp-http.ts

@@ -26,7 +26,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.5.0"
+const VERSION = "1.11.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."

package/src/mcp.ts

@@ -14,6 +14,7 @@
  *     so it can't hallucinate a drifted nifra API).
  *   - `nifra_scaffold`— map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   — the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
+ *   - `nifra_assure`  — route classification + enforcement-evidence gate.
  *   - `nifra_doctor`  — package.json dependency drift detector, with safe local-version auto-fix.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
@@ -951,6 +952,42 @@ export function projectTools(
         )
       },
     },
+    {
+      name: "nifra_assure",
+      description:
+        "Evaluate nifra.assurance.ts and return the complete route-assurance report: every reflected route's first matching policy rule, enforcement evidence, missing/forbidden evidence, and the fail-closed ok bit. Use after adding or changing routes/security middleware; fix every finding before finishing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          config: {
+            type: "string",
+            description:
+              "Config path relative to the selected project directory. Default: nifra.assurance.ts.",
+          },
+          dir: {
+            type: "string",
+            description:
+              'Evaluate this project subdirectory (relative to the MCP root), e.g. "apps/api". Default: the project root.',
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const opts = args as { config?: string; dir?: string }
+        const target = resolveProjectDir(cwd, opts.dir)
+        if (target === null) return dirError(opts.dir)
+        const config = opts.config === undefined ? undefined : resolve(target, opts.config)
+        if (config !== undefined && config !== target && !config.startsWith(target + sep)) {
+          return JSON.stringify(
+            { ok: false, error: "config must stay inside the selected project directory" },
+            null,
+            2,
+          )
+        }
+        const { collectAssuranceReport } = await import("./assure.ts")
+        return JSON.stringify(await collectAssuranceReport(target, config), null, 2)
+      },
+    },
     {
       name: "nifra_doctor",
       description:

package/src/recipes/1.8.0.ts

@@ -0,0 +1,21 @@
+import type { UpgradeRecipe } from "./index.ts"
+
+/**
+ * Upgrade recipe for nifra 1.8.0.
+ *
+ * 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
+ * you (wiring the new assurance config), keeping the runner honest about what it did and didn't touch.
+ */
+export const recipe: UpgradeRecipe = {
+  version: "1.8.0",
+  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.",
+  ],
+}

package/src/recipes/index.ts

@@ -0,0 +1,52 @@
+/**
+ * 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
+ * them deterministically. Recipes are static imports (they bundle) and keyed by target version.
+ */
+
+import { recipe as v1_8_0 } from "./1.8.0.ts"
+
+/** A pin rule: every dependency whose name starts with `match` is set to version `to`. */
+export interface PinRule {
+  /** Package-name prefix, e.g. `@nifrajs/`, or an exact package name. */
+  readonly match: string
+  /** Bare target version, e.g. `1.8.0`. The range operator (`^`/`~`/exact) is preserved per-spec. */
+  readonly to: string
+}
+
+/** An exact import-specifier rewrite (string-level, not AST): `from` → `to`. */
+export interface ImportMove {
+  readonly from: string
+  readonly to: string
+}
+
+export interface UpgradeRecipe {
+  readonly version: string
+  readonly pins: readonly PinRule[]
+  readonly importMoves: readonly ImportMove[]
+  /** Human notes printed after the plan — e.g. structural changes the runner deliberately can't do. */
+  readonly notes?: readonly string[]
+}
+
+const RECIPES: Record<string, UpgradeRecipe> = {
+  [v1_8_0.version]: v1_8_0,
+}
+
+export function getRecipe(version: string): UpgradeRecipe | undefined {
+  return RECIPES[version]
+}
+
+/** Available target versions, ascending. */
+export function listRecipeVersions(): string[] {
+  return Object.keys(RECIPES).sort((a, b) => compareVersions(a, b))
+}
+
+function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}

package/src/upgrade.ts

@@ -0,0 +1,269 @@
+/**
+ * `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
+ *      package.json files, preserving the caret/tilde/exact style and skipping `workspace:`/`link:` specs.
+ *   2. **import moves** — rewrite exact import specifiers to their updated module paths.
+ *   3. **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.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { Glob } from "bun"
+import { getRecipe, listRecipeVersions, type UpgradeRecipe } from "./recipes/index.ts"
+
+export interface UpgradeOptions {
+  /** Target version, e.g. "1.8.0". Required unless `list` is set. */
+  readonly version?: string
+  /** Apply the edits. Without it, the run is a dry-run that only prints the plan. */
+  readonly write?: boolean
+  /** Emit a machine-readable plan/result instead of the human report. */
+  readonly json?: boolean
+  /** Print the available target versions and return. */
+  readonly list?: boolean
+  /** After `--write`, run `nifra check` and fail the command if it fails. Default true. */
+  readonly verify?: boolean
+}
+
+export interface PinChange {
+  readonly file: string
+  readonly field: string
+  readonly name: string
+  readonly from: string
+  readonly to: string
+}
+
+export interface ImportChange {
+  readonly file: string
+  readonly from: string
+  readonly to: string
+  readonly count: number
+}
+
+export interface UpgradePlan {
+  readonly version: string
+  readonly pins: readonly PinChange[]
+  readonly importMoves: readonly ImportChange[]
+  readonly notes: readonly string[]
+}
+
+const DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "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).
+const SEMVER_SPEC =
+  /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/**
+ * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …).
+ * Returns null when the spec is not a plain semver spec (→ skip it) or already equals the target.
+ */
+export function rewriteVersionSpec(spec: string, toVersion: string): string | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  const operator = match[1] ?? ""
+  const next = `${operator}${toVersion}`
+  return next === spec ? null : next
+}
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/**
+ * 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.
+ */
+export function pinSweepText(
+  text: string,
+  rules: readonly { match: string; to: string }[],
+): { text: string; changes: Array<Omit<PinChange, "file">> } {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = JSON.parse(text) as Record<string, unknown>
+  } catch {
+    return { text, changes: [] }
+  }
+  let out = text
+  const changes: Array<Omit<PinChange, "file">> = []
+  for (const field of DEP_FIELDS) {
+    const deps = parsed[field]
+    if (typeof deps !== "object" || deps === null) continue
+    for (const [name, rawSpec] of Object.entries(deps as Record<string, unknown>)) {
+      if (typeof rawSpec !== "string") continue
+      const rule = rules.find((r) => name.startsWith(r.match))
+      if (!rule) continue
+      const next = rewriteVersionSpec(rawSpec, rule.to)
+      if (next === null) continue
+      // Replace exactly `"name"<ws>:<ws>"spec"`, preserving the surrounding whitespace.
+      const pattern = new RegExp(`("${escapeRegExp(name)}"\\s*:\\s*")${escapeRegExp(rawSpec)}(")`)
+      const replaced = out.replace(pattern, `$1${next}$2`)
+      if (replaced !== out) {
+        out = replaced
+        changes.push({ field, name, from: rawSpec, to: next })
+      }
+    }
+  }
+  return { text: out, changes }
+}
+
+const IMPORT_SPEC = (from: string): RegExp =>
+  new RegExp(
+    `(\\bfrom\\s*|\\bimport\\s*\\(\\s*|\\brequire\\s*\\(\\s*|\\bimport\\s+)(['"])${escapeRegExp(from)}(['"])`,
+    "g",
+  )
+
+/** Rewrite exact import/export/require/dynamic-import specifiers in one source file's text. */
+export function applyImportMoves(
+  text: string,
+  moves: readonly { from: string; to: string }[],
+): { text: string; changes: Array<{ from: string; to: string; count: number }> } {
+  let out = text
+  const changes: Array<{ from: string; to: string; count: number }> = []
+  for (const move of moves) {
+    if (move.from === move.to) continue
+    let count = 0
+    out = out.replace(IMPORT_SPEC(move.from), (_full, prefix: string, q1: string, q2: string) => {
+      count += 1
+      return `${prefix}${q1}${move.to}${q2}`
+    })
+    if (count > 0) changes.push({ from: move.from, to: move.to, count })
+  }
+  return { text: out, changes }
+}
+
+const SOURCE_GLOB = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+const IGNORE_SEGMENTS = ["node_modules/", "/dist/", "/build/", "/.git/", "/coverage/", "/.next/"]
+
+const isIgnored = (path: string): boolean =>
+  path.startsWith("node_modules/") || IGNORE_SEGMENTS.some((seg) => path.includes(seg))
+
+function scan(cwd: string, pattern: string): string[] {
+  const glob = new Glob(pattern)
+  const out: string[] = []
+  for (const path of glob.scanSync({ cwd, dot: false })) {
+    if (!isIgnored(path)) out.push(path)
+  }
+  return out.sort() // deterministic order
+}
+
+/** Compute the plan (and, when `write`, apply it) for a target recipe against `cwd`. */
+export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolean): UpgradePlan {
+  const pins: PinChange[] = []
+  const importMoves: ImportChange[] = []
+
+  if (recipe.pins.length > 0) {
+    for (const rel of scan(cwd, "**/package.json")) {
+      const abs = join(cwd, rel)
+      const text = readFileSync(abs, "utf8")
+      const result = pinSweepText(text, recipe.pins)
+      if (result.changes.length === 0) continue
+      for (const change of result.changes) pins.push({ file: rel, ...change })
+      if (write) writeFileSync(abs, result.text)
+    }
+  }
+
+  if (recipe.importMoves.length > 0) {
+    for (const rel of scan(cwd, SOURCE_GLOB)) {
+      const abs = join(cwd, rel)
+      const text = readFileSync(abs, "utf8")
+      const result = applyImportMoves(text, recipe.importMoves)
+      if (result.changes.length === 0) continue
+      for (const change of result.changes) importMoves.push({ file: rel, ...change })
+      if (write) writeFileSync(abs, result.text)
+    }
+  }
+
+  return { version: recipe.version, pins, importMoves, notes: recipe.notes ?? [] }
+}
+
+function renderPlan(plan: UpgradePlan, write: boolean): string {
+  const lines: string[] = []
+  const verb = write ? "Applied" : "Planned"
+  lines.push(`nifra upgrade → ${plan.version}  (${write ? "write" : "dry-run"})`)
+  lines.push("")
+  if (plan.pins.length === 0 && plan.importMoves.length === 0) {
+    lines.push("Already up to date — no changes.")
+    return lines.join("\n")
+  }
+  if (plan.pins.length > 0) {
+    lines.push(`${verb} ${plan.pins.length} dependency pin(s):`)
+    for (const p of plan.pins) lines.push(`  ${p.file}  ${p.name}: ${p.from} → ${p.to}`)
+    lines.push("")
+  }
+  if (plan.importMoves.length > 0) {
+    const total = plan.importMoves.reduce((n, m) => n + m.count, 0)
+    lines.push(`${verb} ${total} import move(s) across ${plan.importMoves.length} file(s):`)
+    for (const m of plan.importMoves) lines.push(`  ${m.file}  ${m.from} → ${m.to}  (${m.count})`)
+    lines.push("")
+  }
+  for (const note of plan.notes) lines.push(`note: ${note}`)
+  if (!write) lines.push("\nRe-run with --write to apply, then nifra check verifies.")
+  return lines.join("\n").trimEnd()
+}
+
+/** CLI entry. Returns false (→ non-zero exit) on an unknown version, no project, or a failed verify. */
+export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<boolean> {
+  if (options.list) {
+    const versions = listRecipeVersions()
+    if (options.json) console.log(JSON.stringify({ versions }, null, 2))
+    else console.log(`available upgrade targets:\n${versions.map((v) => `  ${v}`).join("\n")}`)
+    return true
+  }
+
+  const { version } = options
+  if (version === undefined) {
+    console.error("[nifra] upgrade needs a target version, e.g. `nifra upgrade 1.8.0` (or --list)")
+    return false
+  }
+  const recipe = getRecipe(version)
+  if (!recipe) {
+    console.error(
+      `[nifra] no upgrade recipe for ${version}. Available: ${listRecipeVersions().join(", ") || "(none)"}`,
+    )
+    return false
+  }
+
+  // Detect: the cwd must be a project (or workspace) root.
+  try {
+    readFileSync(join(cwd, "package.json"), "utf8")
+  } catch {
+    console.error(
+      `[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} — run from a project root`,
+    )
+    return false
+  }
+
+  const write = options.write === true
+  const plan = computeUpgrade(cwd, recipe, write)
+
+  if (options.json) {
+    console.log(JSON.stringify({ ...plan, write }, null, 2))
+  } else {
+    console.log(renderPlan(plan, write))
+  }
+
+  // Verify only makes sense once edits are on disk. Default on after --write; opt out with --no-verify.
+  if (write && options.verify !== false) {
+    const { runCheck } = await import("./check.ts")
+    const ok = await runCheck(cwd, { json: false })
+    if (!ok) {
+      if (!options.json)
+        console.error("\n[nifra] upgrade applied but `nifra check` failed — review above.")
+      return false
+    }
+  }
+  return true
+}