@nifrajs/cli 5.0.0 → 5.1.0

package/src/stylex-migrate.ts

@@ -1099,27 +1099,126 @@ const existingStylexImport = (source: string): string | undefined => {
   return match?.[1]
 }
 
-const insertionOffset = (source: string): number => {
-  let offset = source.startsWith("#!") ? source.indexOf("\n") + 1 || source.length : 0
-  const lines = source.slice(offset).split(/(?<=\n)/)
-  let consumed = 0
-  let inImport = false
-  for (const line of lines) {
-    const trimmed = line.trim()
-    const directive = /^(['"])(?:use client|use server)\1;?$/.test(trimmed)
-    if (inImport || trimmed.startsWith("import ") || trimmed.startsWith("import{")) {
-      inImport = !/(?:from\s+["'][^"']+["']|import\s+["'][^"']+["'])\s*;?$/.test(trimmed)
-      consumed += line.length
+const isIdentifierChar = (char: string | undefined): boolean =>
+  char !== undefined && /[\w$]/.test(char)
+
+/** Past the whitespace and comments at `index`. `inLine` stops at the end of the line. */
+function skipTrivia(source: string, index: number, inLine = false): number {
+  let at = index
+  while (at < source.length) {
+    const char = source[at]
+    if (char === " " || char === "\t" || char === "\r" || (char === "\n" && !inLine)) at++
+    else if (source.startsWith("//", at)) {
+      const end = source.indexOf("\n", at)
+      if (end === -1) return source.length
+      at = inLine ? end : end + 1
+    } else if (source.startsWith("/*", at)) {
+      const end = source.indexOf("*/", at + 2)
+      if (end === -1) return source.length
+      at = end + 2
+    } else break
+  }
+  return at
+}
+
+function skipString(source: string, index: number): number {
+  const quote = source[index]
+  let at = index + 1
+  while (at < source.length && source[at] !== quote && source[at] !== "\n")
+    at += source[at] === "\\" ? 2 : 1
+  return Math.min(at + 1, source.length)
+}
+
+/** Past an import's specifier: its `with { ... }` (or `assert`) attributes and a `;`. */
+function afterSpecifier(source: string, index: number): number {
+  let at = index
+  const next = skipTrivia(source, at, true)
+  for (const keyword of ["with", "assert"]) {
+    if (!source.startsWith(keyword, next) || isIdentifierChar(source[next + keyword.length]))
+      continue
+    const open = skipTrivia(source, next + keyword.length)
+    const close = source[open] === "{" ? source.indexOf("}", open) : -1
+    if (close !== -1) at = close + 1
+  }
+  const semicolon = skipTrivia(source, at, true)
+  return source[semicolon] === ";" ? semicolon + 1 : at
+}
+
+/** Where the import declaration whose `import` keyword is at `index` ends, or `undefined` for an
+ * `import(...)` / `import.meta` expression or a declaration this scan cannot read. */
+function importEnd(source: string, index: number): number | undefined {
+  let at = skipTrivia(source, index + "import".length)
+  if (source[at] === "(" || source[at] === ".") return undefined
+  if (source[at] === '"' || source[at] === "'")
+    return afterSpecifier(source, skipString(source, at))
+  let depth = 0
+  while (at < source.length) {
+    const char = source[at]
+    if (char === '"' || char === "'") {
+      at = skipString(source, at)
       continue
     }
-    if (directive || trimmed === "") {
-      consumed += line.length
+    if (source.startsWith("//", at) || source.startsWith("/*", at)) {
+      at = skipTrivia(source, at)
       continue
     }
-    break
+    if (char === "{") depth++
+    else if (char === "}") depth--
+    else if (depth === 0 && (char === ";" || char === "=")) return undefined
+    else if (
+      depth === 0 &&
+      source.startsWith("from", at) &&
+      !isIdentifierChar(source[at - 1]) &&
+      !isIdentifierChar(source[at + 4])
+    ) {
+      const specifier = skipTrivia(source, at + 4)
+      if (source[specifier] === '"' || source[specifier] === "'")
+        return afterSpecifier(source, skipString(source, specifier))
+    }
+    at++
+  }
+  return undefined
+}
+
+/** Past the rest of the line `index` is on when only trivia is left on it, then any blank lines. */
+function nextLine(source: string, index: number): number {
+  let at = skipTrivia(source, index, true)
+  if (at < source.length && source[at] !== "\n") return index
+  for (;;) {
+    if (source[at] !== "\n") return at
+    let next = at + 1
+    while (source[next] === " " || source[next] === "\t" || source[next] === "\r") next++
+    if (next < source.length && source[next] !== "\n") return at + 1
+    at = next
+  }
+}
+
+/**
+ * Where the generated block goes: after the directive prologue and the import declarations. Comments
+ * are read as comments, so one before `"use client"` keeps the directive first, and a trailing
+ * `// note` on the last import does not hide where it ends.
+ */
+const insertionOffset = (source: string): number => {
+  let end = source.startsWith("#!") ? source.indexOf("\n") + 1 || source.length : 0
+  let prologue = true
+  for (;;) {
+    const at = skipTrivia(source, end)
+    const char = source[at]
+    let statementEnd: number | undefined
+    if (prologue && (char === '"' || char === "'")) {
+      const literal = skipString(source, at)
+      const after = skipTrivia(source, literal, true)
+      // A string with more of an expression after it on its line is not a directive.
+      if (source[after] === ";") statementEnd = after + 1
+      else if (after === source.length || source[after] === "\n") statementEnd = literal
+    } else if (source.startsWith("import", at) && !isIdentifierChar(source[at + 6])) {
+      prologue = false
+      statementEnd = importEnd(source, at)
+    }
+    if (statementEnd === undefined) break
+    end = nextLine(source, statementEnd)
   }
-  offset += consumed
-  return offset
+  return end
 }
 
 /** Transform one source file. The returned source is unchanged when every match is unsupported. */
@@ -1196,7 +1295,8 @@ export function migrateTailwindSource(source: string, file: string): SourceMigra
   const needsImport = existingStylexImport(source) === undefined
   const generated = `${needsImport ? `import * as ${stylexName} from "${STYLEX_SPECIFIER}"\n\n` : ""}const ${stylesName} = ${stylexName}.create(${JSON.stringify(Object.fromEntries(styles), null, 2)})\n\n`
   const offset = insertionOffset(rewritten)
-  const withGenerated = `${rewritten.slice(0, offset)}${generated}${rewritten.slice(offset)}`
+  const separator = offset > 0 && rewritten[offset - 1] !== "\n" ? "\n" : ""
+  const withGenerated = `${rewritten.slice(0, offset)}${separator}${generated}${rewritten.slice(offset)}`
   return { source: withGenerated, changed: true, replacements: replacements.length, issues }
 }
 

package/src/test-tool.ts

@@ -1,4 +1,5 @@
 import {
+  escalatingStop,
   type HeadTailOutput,
   OWN_PROCESS_GROUP,
   readHeadTail,
@@ -63,8 +64,6 @@ function normalizeTimeout(value: unknown): number {
   return Math.min(Math.max(Math.trunc(value), 1_000), MAX_TIMEOUT_MS)
 }
 
-const KILL_GRACE_MS = 2_000
-
 const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g")
 
 // A UTF-8 character is at most four bytes, so these hold every character the result can show.
@@ -157,12 +156,7 @@ export async function collectTestResult(
   })
   let timedOut = false
   let cancelled = false
-  let escalation: ReturnType<typeof setTimeout> | undefined
-  // A test can ignore SIGTERM, so the group gets SIGKILL once the grace period runs out.
-  const stop = (): void => {
-    signalProcessGroup(proc, "SIGTERM")
-    escalation ??= setTimeout(() => signalProcessGroup(proc, "SIGKILL"), KILL_GRACE_MS)
-  }
+  const { stop, dispose } = escalatingStop((name) => signalProcessGroup(proc, name))
   const abort = (): void => {
     cancelled = true
     stop()
@@ -189,7 +183,7 @@ export async function collectTestResult(
     exitCode = result[2]
   } finally {
     clearTimeout(timer)
-    clearTimeout(escalation)
+    dispose()
     opts.signal?.removeEventListener("abort", abort)
   }
   const stdout = clean(stdoutRaw)

package/src/upgrade.ts

@@ -5,8 +5,10 @@
  *
  *   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.
- *      `overrides`, `resolutions` and `pnpm.overrides` are swept too, since they decide what installs;
- *      a version pinned anywhere else (an MCP config, a Dockerfile, another lockfile) is listed only.
+ *      `overrides`, `resolutions` and `pnpm.overrides` are swept too, since they decide what installs.
+ *      The MCP launch pin in `.mcp.json`, `.cursor/mcp.json`, CLAUDE.md and AGENTS.md moves too, the
+ *      edit `nifra init-agents --sync-mcp` makes; a version pinned anywhere else (a Dockerfile, a CI
+ *      workflow, another lockfile) is listed only.
  *   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.
@@ -26,6 +28,7 @@
 
 import {
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
@@ -45,6 +48,7 @@ import {
   parseHookReport,
   renderHookDiff,
 } from "./hooks-report.ts"
+import { PIN_SITES } from "./init-agents.ts"
 import { getRecipe, listRecipeVersions, type UpgradeRecipe } from "./recipes/index.ts"
 import { markerTarget } from "./rules/comment-markers.ts"
 
@@ -97,6 +101,14 @@ export interface DependencyMoveChange {
   readonly action: "renamed" | "removed"
 }
 
+/** An agent file whose MCP launch pins another `@nifrajs/cli`, re-pinned to the target. */
+export interface AgentPinChange {
+  readonly file: string
+  /** The versions it pinned, in order of appearance. */
+  readonly from: readonly string[]
+  readonly to: string
+}
+
 /** A retired comment in the project, and the line it applied to before the release retired it. */
 export interface RetiredMarkerSite {
   readonly file: string
@@ -110,6 +122,7 @@ export interface RetiredMarkerSite {
 export interface UpgradePlan {
   readonly version: string
   readonly pins: readonly PinChange[]
+  readonly agentPins: readonly AgentPinChange[]
   readonly dependencyMoves: readonly DependencyMoveChange[]
   readonly importMoves: readonly ImportChange[]
   /** Pins refused because the target is BELOW the installed version (a rollback). Empty when allowed. */
@@ -540,7 +553,7 @@ function scan(cwd: string, pattern: string, dot = false): string[] {
 }
 
 // The fixed version group: every package released together at one version.
-const isFixedGroup = (name: string): boolean =>
+export const isFixedGroup = (name: string): boolean =>
   name.startsWith("@nifrajs/") || name === "nifra" || name === "create-nifra"
 
 const groupPins = (version: string): UpgradeRecipe["pins"] => [
@@ -549,6 +562,20 @@ const groupPins = (version: string): UpgradeRecipe["pins"] => [
   { match: "nifra", to: version },
 ]
 
+/** Every fixed-group package a package.json under `cwd` names, whatever its spec. */
+export function groupDeclaredNames(cwd: string): ReadonlySet<string> {
+  const names = new Set<string>()
+  for (const rel of scan(cwd, "**/package.json")) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(cwd, rel), "utf8")) as Record<string, unknown>
+      for (const { target } of pinEntries(parsed)) if (isFixedGroup(target)) names.add(target)
+    } catch {
+      // Not JSON: it declares nothing.
+    }
+  }
+  return names
+}
+
 /**
  * Every fixed-group version the package.json files under `cwd` declare with a plain semver spec, each
  * with the files that declare it. An override counts: it decides what installs. `workspace:`, `link:`
@@ -589,6 +616,7 @@ export interface StrayPin {
 
 const STRAY_PIN_FILES = [
   "**/{.mcp.json,mcp.json}",
+  "**/{AGENTS.md,CLAUDE.md}",
   "**/{Dockerfile,Dockerfile.*,*.Dockerfile,*.dockerfile,Containerfile}",
   "**/{docker-compose,compose}*.{yml,yaml}",
   ".github/workflows/*.{yml,yaml}",
@@ -601,10 +629,16 @@ const GROUP_PIN =
   /(?<![\w.@/-])(@nifrajs\/[a-z0-9._-]+|create-nifra|nifra)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/g
 
 /**
- * Fixed-group versions other than `version` pinned where `nifra upgrade` does not edit: MCP configs,
- * container files, CI workflows, and lockfiles besides the workspace's own (which install rewrites).
+ * Fixed-group versions other than `version` pinned where `nifra upgrade` does not edit: MCP configs and
+ * agent guidance beyond the launch pin it moves, container files, CI workflows, and lockfiles besides
+ * the workspace's own (which install rewrites). `planned` holds a file's text after the upgrade's own
+ * edits, so a dry run lists what `--write` would leave.
  */
-export function strayPins(cwd: string, version: string): StrayPin[] {
+export function strayPins(
+  cwd: string,
+  version: string,
+  planned: ReadonlyMap<string, string> = new Map(),
+): StrayPin[] {
   const found: StrayPin[] = []
   const files = new Set(STRAY_PIN_FILES.flatMap((pattern) => scan(cwd, pattern, true)))
   for (const rel of [...files].sort()) {
@@ -613,7 +647,7 @@ export function strayPins(cwd: string, version: string): StrayPin[] {
     let text: string
     try {
       if (statSync(join(cwd, rel)).size > 8_000_000) continue
-      text = readFileSync(join(cwd, rel), "utf8")
+      text = planned.get(rel) ?? readFileSync(join(cwd, rel), "utf8")
     } catch {
       continue
     }
@@ -635,6 +669,43 @@ export function strayPins(cwd: string, version: string): StrayPin[] {
   return found
 }
 
+/** Whether `rel` is a regular file under `cwd` reached through no symlink: the upgrade's write boundary. */
+function plainFileAt(cwd: string, rel: string): boolean {
+  let path = cwd
+  const parts = rel.split("/")
+  for (const [index, part] of parts.entries()) {
+    path = join(path, part)
+    let stat: ReturnType<typeof lstatSync>
+    try {
+      stat = lstatSync(path)
+    } catch {
+      return false
+    }
+    if (stat.isSymbolicLink()) return false
+    if (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()) return false
+  }
+  return true
+}
+
+/**
+ * The MCP launch pin in each agent file at `cwd`, moved to `version`: the files and the edit of
+ * `nifra init-agents --sync-mcp`, so an agent launches the nifra the project installs once it does.
+ */
+function agentPinEdits(
+  cwd: string,
+  version: string,
+): Array<{ readonly change: AgentPinChange; readonly text: string }> {
+  const edits: Array<{ change: AgentPinChange; text: string }> = []
+  for (const site of PIN_SITES) {
+    if (!plainFileAt(cwd, site.path)) continue
+    // latin1 is one char per byte, so every byte outside a pin is written back as it was.
+    const scan = site.repin(readFileSync(join(cwd, site.path), "latin1"), version)
+    if (scan.stale.length === 0) continue
+    edits.push({ change: { file: site.path, from: scan.stale, to: version }, text: scan.text })
+  }
+  return edits
+}
+
 /** An installed fixed-group package, followed to its real location. */
 export interface LinkedGroupInstall {
   readonly package: string
@@ -752,6 +823,8 @@ export function computeUpgrade(
   exact = false,
 ): UpgradePlan {
   const pins: PinChange[] = []
+  const agentPins: AgentPinChange[] = []
+  const planned = new Map<string, string>()
   const dependencyMoves: DependencyMoveChange[] = []
   const importMoves: ImportChange[] = []
   const downgrades: PinChange[] = []
@@ -773,6 +846,12 @@ export function computeUpgrade(
     }
   }
 
+  for (const { change, text } of agentPinEdits(cwd, recipe.version)) {
+    agentPins.push(change)
+    planned.set(change.file, text)
+    if (write) writeFileSync(join(cwd, change.file), Buffer.from(text, "latin1"))
+  }
+
   if (recipe.importMoves.length > 0) {
     for (const rel of scan(cwd, SOURCE_GLOB)) {
       const abs = join(cwd, rel)
@@ -808,12 +887,13 @@ export function computeUpgrade(
   return {
     version: recipe.version,
     pins,
+    agentPins,
     dependencyMoves,
     importMoves,
     downgrades,
     retiredMarkers,
     linkedOutside,
-    strayPins: strayPins(cwd, recipe.version),
+    strayPins: strayPins(cwd, recipe.version, planned),
     notes: recipe.notes ?? [],
   }
 }
@@ -837,6 +917,7 @@ function renderPlan(
   lines.push("")
   if (
     plan.pins.length === 0 &&
+    plan.agentPins.length === 0 &&
     plan.dependencyMoves.length === 0 &&
     plan.importMoves.length === 0 &&
     plan.retiredMarkers.length === 0 &&
@@ -862,6 +943,13 @@ function renderPlan(
     for (const p of plan.pins) lines.push(`  ${p.file}  ${p.name}: ${p.from} → ${p.to}`)
     lines.push("")
   }
+  if (plan.agentPins.length > 0) {
+    lines.push(`${verb} ${plan.agentPins.length} MCP launch pin(s):`)
+    for (const p of plan.agentPins)
+      lines.push(`  ${p.file}  @nifrajs/cli: ${p.from.join(", ")} → ${p.to}`)
+    if (write) lines.push("  Restart your agent so it launches the new nifra MCP server.")
+    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):`)

package/src/verification-plan.ts

@@ -37,6 +37,11 @@ const GATES = Object.freeze([
     "Run `bun run typecheck` and fix the reported TypeScript errors.",
   ),
   gate("tests", [["run", "test"]], "Run `bun run test` and fix the first failing test."),
+  gate(
+    "rest-tests",
+    [["run", "test:rest"]],
+    "Run `bun run test:rest` and fix the first failing test.",
+  ),
   gate(
     "docs",
     [["run", "check:docs"]],
@@ -216,13 +221,15 @@ const DEFAULT_PLAN = Object.freeze([
   "changesets",
 ] as const)
 
+// `coverage` fails on any failing test, so it is the release plan's run of the library suites;
+// `rest-tests` runs the suites it leaves out, and `tests` would only repeat the two.
 const RELEASE_PLAN = Object.freeze([
   "build",
   "lint",
   "typecheck",
-  "tests",
-  "cli-isolation",
   "coverage",
+  "rest-tests",
+  "cli-isolation",
   "corpus",
   "sitemap",
   "docs",

package/src/version-drift.ts

@@ -1,10 +1,28 @@
+import { readFileSync } from "node:fs"
+import { join, sep } from "node:path"
 import {
   compareSemverSpec,
+  groupDeclaredNames,
   groupPinVersions,
   installedGroupPackages,
+  isFixedGroup,
   type LinkedGroupInstall,
 } from "./upgrade.ts"
 
+/** The fixed-group packages the package installed at `dir` depends on. */
+function groupDependenciesAt(dir: string): string[] {
+  try {
+    const manifest: unknown = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))
+    if (typeof manifest !== "object" || manifest === null) return []
+    return ["dependencies", "peerDependencies", "optionalDependencies"].flatMap((field) => {
+      const deps: unknown = Reflect.get(manifest, field)
+      return typeof deps === "object" && deps !== null ? Object.keys(deps).filter(isFixedGroup) : []
+    })
+  } catch {
+    return []
+  }
+}
+
 /** One version of the fixed release group, and where the workspace carries it. */
 export interface GroupVersion {
   readonly version: string
@@ -35,7 +53,13 @@ export function collectVersionDrift(cwd: string, cliVersion?: string): VersionDr
     for (const file of files) add(version, `pinned in ${file}`)
   }
   const linkedOutside: LinkedGroupInstall[] = []
-  for (const { package: name, path, version, inside } of installedGroupPackages(cwd)) {
+  const installs = installedGroupPackages(cwd)
+  // An install nothing declares, such as one an older install left behind, loads nowhere, and no
+  // upgrade re-pins it: counting it would report drift that never clears.
+  const declared = new Set(groupDeclaredNames(cwd))
+  for (const { path } of installs) for (const name of groupDependenciesAt(path)) declared.add(name)
+  for (const { package: name, path, version, inside } of installs) {
+    if (!declared.has(name)) continue
     add(version, `installed ${name}${inside ? "" : ` (linked from ${path})`}`)
     if (!inside) linkedOutside.push({ package: name, path, version })
   }
@@ -51,6 +75,33 @@ export function collectVersionDrift(cwd: string, cliVersion?: string): VersionDr
   }
 }
 
+/** The install a package belongs to: the folder above its last `node_modules`, or the package itself. */
+const installRoot = (path: string): string => {
+  const parts = path.split(sep)
+  const last = parts.lastIndexOf("node_modules")
+  return last <= 0 ? path : parts.slice(0, last).join(sep)
+}
+
+/** Linked installs, one phrase per install and version: a linked repository brings its whole group. */
+function linkedGroups(installs: readonly LinkedGroupInstall[]): string[] {
+  const groups = new Map<string, LinkedGroupInstall[]>()
+  for (const install of installs) {
+    const key = `${installRoot(install.path)}\0${install.version}`
+    groups.set(key, [...(groups.get(key) ?? []), install])
+  }
+  return [...groups.values()].map((group) => {
+    const [first] = group
+    if (first === undefined) return ""
+    if (group.length === 1) return `${first.package} ${first.version} at ${first.path}`
+    const names = group.map((install) => install.package).sort()
+    const listed =
+      names.length > 3
+        ? `${names.slice(0, 3).join(", ")} and ${names.length - 3} more`
+        : names.join(", ")
+    return `${group.length} packages at ${first.version} under ${installRoot(first.path)} (${listed})`
+  })
+}
+
 /** The advisory both `nifra doctor` and `nifra check` print. */
 export function versionDriftMessage(drift: VersionDrift): string {
   const listed = drift.versions
@@ -62,6 +113,6 @@ export function versionDriftMessage(drift: VersionDrift): string {
   const linked =
     drift.linkedOutside.length === 0
       ? ""
-      : ` It does not edit ${drift.linkedOutside.map((entry) => `${entry.package} ${entry.version} at ${entry.path}`).join(", ")}, linked from outside the workspace root; upgrade that repository on its own.`
+      : ` It does not edit ${linkedGroups(drift.linkedOutside).join(", ")}, linked from outside the workspace root; upgrade that repository on its own.`
   return `mixed nifra versions in this workspace: ${listed}. Run \`nifra upgrade ${drift.highest}\` (it runs each release's migration steps, then re-pins).${linked}`
 }