@nifrajs/cli 2.14.1 → 3.2.0

package/src/sync-manifest.ts

@@ -46,7 +46,8 @@ export async function syncServerManifests(cwd: string): Promise<SyncManifestResu
     "@nifrajs/web/build"
   )
   const results: SyncManifestResult[] = []
-  for await (const rel of new Glob("**/server-manifest.ts").scan({ cwd, dot: false })) {
+  for await (const rawRel of new Glob("**/server-manifest.ts").scan({ cwd, dot: false })) {
+    const rel = rawRel.replaceAll("\\", "/")
     if (IGNORED.test(rel)) continue
     const abs = join(cwd, rel)
     const source = await Bun.file(abs).text()

package/src/verification-plan.ts

@@ -0,0 +1,242 @@
+/**
+ * The repository verification plan.
+ *
+ * Gates are declared once and plans refer to them by stable id. Keeping composition separate from the
+ * gate registry is deliberate: adding a gate to one mode cannot silently re-point another mode through
+ * an array index. The release runner, its CLI/MCP projections, and the plan tests all consume this seam.
+ */
+
+export type VerificationPlanMode = "default" | "release"
+
+export interface VerificationGateSpec {
+  readonly id: string
+  readonly commands: readonly (readonly string[])[]
+  readonly remediation: string
+  /** Whether the gate must be represented by a command in `.github/workflows/ci.yml`. */
+  readonly workflowRequired: boolean
+}
+
+const gate = (
+  id: string,
+  commands: readonly (readonly string[])[],
+  remediation: string,
+  options: { readonly workflowRequired?: boolean } = {},
+): VerificationGateSpec =>
+  Object.freeze({
+    id,
+    commands: Object.freeze(commands.map((args) => Object.freeze([...args]))),
+    remediation,
+    workflowRequired: options.workflowRequired ?? true,
+  })
+
+const GATES = Object.freeze([
+  gate("lint", [["run", "lint"]], "Run `bun run lint` and fix the reported lint findings."),
+  gate(
+    "typecheck",
+    [["run", "typecheck"]],
+    "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(
+    "docs",
+    [["run", "check:docs"]],
+    "Run `bun run check:docs` and update the failing documentation example.",
+  ),
+  gate(
+    "api-corpus",
+    [["run", "check:api"]],
+    "Run `bun run gen:api` and review the generated API reference.",
+  ),
+  gate(
+    "cards-corpus",
+    [["run", "check:cards"]],
+    "Run `bun run gen:cards` and review the generated package cards.",
+  ),
+  gate(
+    "node-outcome-corpus",
+    [["run", "check:node-outcome"]],
+    "Run `bun run gen:node-outcome` and review the generated Node outcome contract.",
+  ),
+  gate(
+    "sitemap",
+    [["run", "check:sitemap"]],
+    "Run `bun run gen:sitemap` and review the generated sitemap.",
+  ),
+  gate(
+    "public-manifest",
+    [["run", "check:public-manifest"]],
+    "Run `bun run gen:public` and review the generated public product manifest.",
+  ),
+  gate(
+    "public-boundary",
+    [["run", "check:public-boundary"]],
+    "Run `bun run check:public-boundary` (which includes the agent-boundary scan) and remove the reported boundary violation.",
+  ),
+  gate(
+    "size",
+    [["run", "check:size"]],
+    "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
+  ),
+  gate(
+    "changesets",
+    [["run", "check:changesets"]],
+    "Run `bun run changeset` and name every package whose source changed, so the release documents it.",
+  ),
+  gate("build", [["run", "build"]], "Run `bun run build` and fix the first package build failure."),
+  gate(
+    "coverage",
+    [
+      ["run", "test:coverage"],
+      ["run", "check:coverage"],
+    ],
+    "Run `bun run test:coverage` first, then `bun run check:coverage`, and fix the reported coverage regression.",
+  ),
+  gate(
+    "corpus",
+    [["run", "check:corpus"]],
+    "Run `bun run gen:llms`, `bun run gen:api`, and `bun run gen:cards`, then rerun the corpus gate.",
+  ),
+  gate(
+    "core-performance",
+    [["run", "check:core-performance"]],
+    "Run `bun run check:core-performance` and investigate the measured performance regression.",
+    { workflowRequired: false },
+  ),
+  gate(
+    "publish",
+    [["run", "check:publish"]],
+    "Run `bun run check:publish` and fix the publish-consumer metadata or type-surface failure.",
+  ),
+  gate(
+    "consumer",
+    [["run", "check:consumers"]],
+    "Run `bun run check:consumers` and fix the isolated consumer failure.",
+  ),
+  gate(
+    "cold-start",
+    [["run", "check:cold-start"]],
+    "Run `bun run check:cold-start` and fix the fresh scaffold install or build failure.",
+  ),
+  gate(
+    "cross-runtime-deno",
+    [
+      ["run", "test:deno"],
+      ["run", "check:deno-tarball"],
+    ],
+    "Run `bun run test:deno` and `bun run check:deno-tarball`, then fix the first Deno compatibility failure.",
+  ),
+  gate(
+    "cross-runtime-node",
+    [["run", "test:node"]],
+    "Run `bun run test:node` and fix the Node runtime adapter failure.",
+  ),
+  gate(
+    "workerd",
+    [["run", "check:workerd"]],
+    "Run `bun run check:workerd` and fix the real Workers runtime contract failure.",
+  ),
+  gate(
+    "pipeline-parity",
+    [["run", "check:pipeline-parity"]],
+    "Run `bun run check:pipeline-parity` and fix the development and production manifest drift.",
+  ),
+  gate(
+    "cli-isolation",
+    [["run", "check:cli-isolation"]],
+    "Run `bun run check:cli-isolation` and fix the first order-dependent CLI test failure.",
+  ),
+  gate(
+    "plugin-manifest",
+    [["run", "check:plugin"]],
+    "Run `bun run check:plugin` and reconcile the skills package, plugin, and marketplace manifests.",
+  ),
+  gate(
+    "verification-parity",
+    [["run", "check:verification-parity"]],
+    "Run `bun run check:verification-parity` and reconcile the release plan with CI.",
+  ),
+])
+
+const DEFAULT_PLAN = Object.freeze([
+  "lint",
+  "typecheck",
+  "tests",
+  "docs",
+  "api-corpus",
+  "cards-corpus",
+  "node-outcome-corpus",
+  "sitemap",
+  "public-boundary",
+  "public-manifest",
+  "plugin-manifest",
+  "size",
+  "changesets",
+] as const)
+
+const RELEASE_PLAN = Object.freeze([
+  "build",
+  "lint",
+  "typecheck",
+  "tests",
+  "cli-isolation",
+  "coverage",
+  "corpus",
+  "docs",
+  "public-boundary",
+  "public-manifest",
+  "plugin-manifest",
+  "size",
+  "core-performance",
+  "publish",
+  "consumer",
+  "cold-start",
+  "cross-runtime-deno",
+  "cross-runtime-node",
+  "workerd",
+  "pipeline-parity",
+  "verification-parity",
+  "changesets",
+] as const)
+
+const gateById = new Map(GATES.map((entry) => [entry.id, entry]))
+
+const planIds = (mode: VerificationPlanMode): readonly string[] =>
+  mode === "release" ? RELEASE_PLAN : DEFAULT_PLAN
+
+/** Return the immutable, ordered gate plan for a verification mode. */
+export function verificationPlan(
+  mode: VerificationPlanMode = "default",
+): readonly VerificationGateSpec[] {
+  return Object.freeze(
+    planIds(mode).map((id) => {
+      const entry = gateById.get(id)
+      if (entry === undefined) throw new Error(`verification plan references unknown gate: ${id}`)
+      return entry
+    }),
+  )
+}
+
+/** Stable IDs are useful to CI and tests that need to compare plans without parsing prose. */
+export function verificationPlanIds(mode: VerificationPlanMode = "default"): readonly string[] {
+  return planIds(mode)
+}
+
+/** Stable IDs in the full plan that are not part of a shorter plan. */
+export function omittedVerificationGateIds(
+  mode: VerificationPlanMode = "default",
+  fullMode: VerificationPlanMode = "release",
+): readonly string[] {
+  const included = new Set(planIds(mode))
+  return Object.freeze(planIds(fullMode).filter((id) => !included.has(id)))
+}
+
+const commandLabel = (args: readonly string[]): string => `bun ${args.join(" ")}`
+
+/** Render the declarative plan without running any gate. */
+export function renderVerificationPlan(mode: VerificationPlanMode = "default"): string {
+  const lines = [`nifra verification plan --${mode}`, ""]
+  for (const [index, entry] of verificationPlan(mode).entries()) {
+    lines.push(`${index + 1}. ${entry.id}: ${entry.commands.map(commandLabel).join(" → ")}`)
+  }
+  return lines.join("\n")
+}

package/src/work-graph.ts

@@ -173,7 +173,8 @@ export async function inspectBuildFreshness(cwd: string): Promise<BuildFreshness
     const path = resolve(cwd, name)
     if (existsSync(path)) sourcePaths.push(path)
   }
-  for await (const path of SOURCE_GLOB.scan({ cwd, dot: false })) {
+  for await (const rawPath of SOURCE_GLOB.scan({ cwd, dot: false })) {
+    const path = rawPath.replaceAll("\\", "/")
     if (!IGNORED.test(path) && path.startsWith("routes/")) sourcePaths.push(resolve(cwd, path))
   }
   const sourceTimes = await fileTimes(sourcePaths)
@@ -181,7 +182,8 @@ export async function inspectBuildFreshness(cwd: string): Promise<BuildFreshness
     const buildDir = resolve(cwd, buildDirName)
     if (!existsSync(buildDir)) continue
     const artifacts: string[] = []
-    for await (const path of new Glob("**/*.{js,mjs,cjs}").scan({ cwd: buildDir, dot: false })) {
+    for await (const rawPath of new Glob("**/*.{js,mjs,cjs}").scan({ cwd: buildDir, dot: false })) {
+      const path = rawPath.replaceAll("\\", "/")
       artifacts.push(resolve(buildDir, path))
     }
     if (artifacts.length === 0) continue
@@ -515,7 +517,8 @@ export function renderWorkGraphText(result: ProjectWorkGraphResult): string {
 
 async function collectProjectFiles(cwd: string): Promise<WorkGraphSourceFile[]> {
   const files: WorkGraphSourceFile[] = []
-  for await (const path of SOURCE_GLOB.scan({ cwd, dot: false })) {
+  for await (const rawPath of SOURCE_GLOB.scan({ cwd, dot: false })) {
+    const path = rawPath.replaceAll("\\", "/")
     if (IGNORED.test(path)) continue
     const full = resolve(cwd, path)
     try {

package/src/workspace-link.ts

@@ -0,0 +1,80 @@
+/**
+ * Resolving a WORKSPACE-LINKED dependency back to the directory it really lives in.
+ *
+ * A workspace link is the one install whose realpath deliberately leaves the project: `link:` and
+ * `workspaces` entries point at a source checkout, routinely in a sibling repository. That is exactly
+ * what makes such a package able to go stale (its `dist/` is nobody's build step) and exactly what a
+ * project-contained path check rejects - so the rebuild has to resolve the escape on purpose, under
+ * its own rules, rather than reuse `resolveInsideProject`.
+ *
+ * The rules that keep it safe:
+ *   - the path is never taken from a diagnostic; it is re-derived from the package NAME by walking the
+ *     project's own `node_modules` chain, so only a symlink the package manager already created can be
+ *     reached, and only a package the project actually declares;
+ *   - a copy that resolves INSIDE `node_modules` is a registry tarball - immutable, never stale, and
+ *     never rebuilt;
+ *   - the package must declare the build script itself. nifra runs the project's own script, never a
+ *     command of its own composition, and never through a shell.
+ */
+
+import { sep } from "node:path"
+import { resolvedInstalledCopy } from "@nifrajs/web/internal/parity"
+
+/** The one script name a rebuild will run. Guessing among `prepare`/`compile`/`build:*` would risk
+ * running something that is not the build at all; a package that names it differently is reported as
+ * un-automatable instead. */
+const BUILD_SCRIPT = "build"
+
+/** A package name npm would accept, with no path segment that could climb out of `node_modules`. */
+const PACKAGE_NAME = /^@?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/
+
+export function isPackageName(value: string): boolean {
+  return PACKAGE_NAME.test(value) && !value.split("/").some((part) => part === "." || part === "..")
+}
+
+/** The package's own build script name, or `undefined` when it declares none. */
+export function buildScriptName(meta: Record<string, unknown> | undefined): string | undefined {
+  const scripts = meta?.scripts
+  if (typeof scripts !== "object" || scripts === null) return undefined
+  const script = (scripts as Record<string, unknown>)[BUILD_SCRIPT]
+  return typeof script === "string" && script.trim().length > 0 ? BUILD_SCRIPT : undefined
+}
+
+export type WorkspaceLinkResolution =
+  | { readonly ok: true; readonly dir: string; readonly buildScript: string }
+  | { readonly ok: false; readonly reason: string }
+
+/**
+ * Resolve `name` to the workspace-linked checkout the project loads it from, refusing with a stated
+ * reason rather than resolving to nothing. The upward walk is unbounded on purpose: it has to reach the
+ * same hoisted copy the staleness scan found, which in a monorepo sits above the package being checked.
+ * It only ever inspects `node_modules/<name>` directories, so it cannot wander into an arbitrary path.
+ */
+export async function resolveWorkspaceLinkedPackage(
+  cwd: string,
+  name: string,
+): Promise<WorkspaceLinkResolution> {
+  if (!isPackageName(name)) return { ok: false, reason: `not a package name: ${name}` }
+  // Boundary "" and the `node_modules` refusal below mirror `collectStaleWorkspaceDists` exactly, so
+  // the rebuild always lands on the same copy the staleness scan flagged.
+  const copy = await resolvedInstalledCopy(cwd, "", name)
+  if (copy === undefined) return { ok: false, reason: `${name} is not installed under ${cwd}` }
+  if (copy.path.includes(`${sep}node_modules${sep}`)) {
+    return {
+      ok: false,
+      reason: `${name} resolves to a registry install (${copy.path}), which cannot be stale or rebuilt`,
+    }
+  }
+  const meta = (await Bun.file(`${copy.path}${sep}package.json`)
+    .json()
+    .catch(() => undefined)) as Record<string, unknown> | undefined
+  if (meta === undefined) return { ok: false, reason: `${copy.path} has no readable package.json` }
+  const buildScript = buildScriptName(meta)
+  if (buildScript === undefined) {
+    return {
+      ok: false,
+      reason: `${name} declares no "${BUILD_SCRIPT}" script in ${copy.path}/package.json, so its artifact cannot be rebuilt automatically - build it the way that package expects`,
+    }
+  }
+  return { ok: true, dir: copy.path, buildScript }
+}