@nifrajs/cli 2.1.0 → 2.3.0

package/src/diff-tool.ts

@@ -1,5 +1,5 @@
 /**
- * `nifra snapshot` / `nifra diff` — the API breaking-change gate.
+ * `nifra snapshot` / `nifra diff` - the API breaking-change gate.
  *
  *   nifra snapshot [--out api-snapshot.json]   Write the backend's route contract as plain JSON.
  *   nifra diff <baseline.json> [--json]        Re-snapshot and compare against the committed
@@ -10,7 +10,7 @@
  * before it ships. Classification lives in `@nifrajs/core/diff` (direction-aware, fails closed);
  * this module only loads `backend.ts` and renders the result.
  *
- * Loads ONLY `backend.ts` — the API contract — so it works on an API-only project with no
+ * Loads ONLY `backend.ts` - the API contract - so it works on an API-only project with no
  * framework config or routes/ directory (unlike the eager `loadApp`).
  */
 
@@ -24,7 +24,7 @@ import {
   snapshotRoutes,
 } from "@nifrajs/core/diff"
 
-/** Snapshot file envelope — versioned so a future format change can migrate instead of misparse. */
+/** Snapshot file envelope - versioned so a future format change can migrate instead of misparse. */
 export interface SnapshotFile {
   readonly nifraSnapshot: 1
   readonly routes: readonly RouteSnapshot[]
@@ -39,7 +39,7 @@ export function parseSnapshotFile(content: string, sourcePath: string): Snapshot
     parsed = JSON.parse(content)
   } catch {
     throw new Error(
-      `[nifra] ${sourcePath} is not valid JSON — regenerate it with \`nifra snapshot\`.`,
+      `[nifra] ${sourcePath} is not valid JSON - regenerate it with \`nifra snapshot\`.`,
     )
   }
   const record = parsed as Partial<SnapshotFile> | null
@@ -50,7 +50,7 @@ export function parseSnapshotFile(content: string, sourcePath: string): Snapshot
     !Array.isArray(record.routes)
   ) {
     throw new Error(
-      `[nifra] ${sourcePath} is not a nifra API snapshot — expected { "nifraSnapshot": 1, "routes": [...] }.`,
+      `[nifra] ${sourcePath} is not a nifra API snapshot - expected { "nifraSnapshot": 1, "routes": [...] }.`,
     )
   }
   return record as SnapshotFile
@@ -76,7 +76,7 @@ export function formatDiff(diff: RoutesDiff): string {
     .map(describeChange)
   const breaking = diff.changes.filter((change) => change.severity === "breaking").length
   const summary = diff.hasBreaking
-    ? `${breaking} breaking change${breaking === 1 ? "" : "s"} — existing clients will fail.`
+    ? `${breaking} breaking change${breaking === 1 ? "" : "s"} - existing clients will fail.`
     : "No breaking changes."
   return `${lines.join("\n")}\n\n${summary}`
 }
@@ -86,7 +86,7 @@ async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
   const backendPath = resolve(cwd, "backend.ts")
   if (!existsSync(backendPath)) {
     throw new Error(
-      `[nifra] no backend.ts in ${cwd} — \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend.ts.`,
+      `[nifra] no backend.ts in ${cwd} - \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend.ts.`,
     )
   }
   const backend = ((await import(backendPath)) as { backend?: unknown }).backend
@@ -115,7 +115,7 @@ export async function runDiff(
   const baselineFile = Bun.file(resolved)
   if (!(await baselineFile.exists())) {
     throw new Error(
-      `[nifra] baseline not found: ${resolved} — create it on your main branch with \`nifra snapshot\`.`,
+      `[nifra] baseline not found: ${resolved} - create it on your main branch with \`nifra snapshot\`.`,
     )
   }
   const baseline = parseSnapshotFile(await baselineFile.text(), baselinePath)

package/src/docs-search.ts

@@ -1,8 +1,8 @@
 /**
- * `nifra_docs` — searchable framework documentation for agents. The corpus is the generated
+ * `nifra_docs` - searchable framework documentation for agents. The corpus is the generated
  * `llms-full.txt` (written into this package by `bun run gen:llms`, so it can't drift from the
  * source it's generated from). Instead of dumping the whole ~150 KB into an agent's context, the
- * tool keyword-scores the document's `##` sections and returns only the top matches — or, with no
+ * tool keyword-scores the document's `##` sections and returns only the top matches - or, with no
  * query, just the section index (the cheap discovery call).
  *
  * Deliberately NOT a vector search: the corpus is one curated document with descriptive headings;
@@ -68,7 +68,7 @@ export function searchSections(
   return scored.sort((a, b) => b.score - a.score).slice(0, limit)
 }
 
-/** Cap a section body for the tool result — whole sections can be pages long; the agent can ask
+/** Cap a section body for the tool result - whole sections can be pages long; the agent can ask
  * again with a narrower query if the trim cuts what it needed. */
 const MAX_SECTION_CHARS = 2800
 
@@ -81,7 +81,7 @@ export function renderDocsResult(
   const sections = splitSections(markdown)
   if (query === undefined || query.trim() === "") {
     const index = sections.map((s) => `- ${s.heading}`).join("\n")
-    return `# nifra docs — section index (pass \`query\` to fetch matching sections)\n\n${index}`
+    return `# nifra docs - section index (pass \`query\` to fetch matching sections)\n\n${index}`
   }
   const matches = searchSections(sections, query, limit)
   if (matches.length === 0) {
@@ -91,7 +91,7 @@ export function renderDocsResult(
     .map((m) => {
       const body =
         m.body.length > MAX_SECTION_CHARS
-          ? `${m.body.slice(0, MAX_SECTION_CHARS)}\n…(trimmed — narrow the query for the rest)`
+          ? `${m.body.slice(0, MAX_SECTION_CHARS)}\n…(trimmed - narrow the query for the rest)`
           : m.body
       return `## ${m.heading}\n\n${body}`
     })
@@ -99,7 +99,7 @@ export function renderDocsResult(
 }
 
 /** Load the bundled corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/llms-full.txt` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/llms-full.txt` sits at the package root next to both. */
 export async function loadDocsCorpus(): Promise<string | undefined> {
   const url = new URL("../docs/llms-full.txt", import.meta.url)
   try {

package/src/doctor.ts

@@ -1,16 +1,16 @@
 /**
- * `nifra doctor` — catches the Bun-workspace footgun the typed-client lint can't: a package that's
+ * `nifra doctor` - catches the Bun-workspace footgun the typed-client lint can't: a package that's
  * IMPORTED in source but NOT declared in `package.json`. Bun resolves it at runtime (via hoisting or a
- * workspace), so tests pass and `bun install` reports "no changes" — false confidence — yet `tsc` fails
+ * workspace), so tests pass and `bun install` reports "no changes" - false confidence - yet `tsc` fails
  * and a fresh or standalone install can't resolve it. doctor diffs every bare import specifier against
  * the package's declared dependencies and flags the gap, with a stable `--json` shape for agents/CI.
  *
  * Scope is intentionally per-package: it checks the `package.json` at `cwd`, because a dependency must be
  * declared by the package that imports it (for `tsc` and for that package to install on its own) even
  * when a monorepo would hoist it. Relative paths, runtime builtins (node core, `node:`/`bun:`, `bun`),
- * the package's own name, and tsconfig `paths` aliases are excluded — none of them are npm deps.
+ * the package's own name, and tsconfig `paths` aliases are excluded - none of them are npm deps.
  */
-import { realpath } from "node:fs/promises"
+import { realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
@@ -25,7 +25,7 @@ const BUILTINS: ReadonlySet<string> = new Set<string>([
 
 // The four specifier-bearing forms: static import/re-export with a source, side-effect import, dynamic
 // import, and CJS require. Anchored with `(?<![.\w$])` so `myimport`/`.import`/`foorequire` never match.
-// Comments are stripped before these run (see stripComments) — else a doc-comment usage example would be
+// Comments are stripped before these run (see stripComments) - else a doc-comment usage example would be
 // flagged as a real import.
 const IMPORT_PATTERNS: readonly RegExp[] = [
   /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
@@ -56,7 +56,7 @@ export function packageOf(spec: string): string | undefined {
   if (spec.startsWith("node:") || spec.startsWith("bun:")) return undefined
   if (spec.startsWith("@")) {
     const [scope, name] = spec.split("/")
-    if (!scope || scope === "@" || !name) return undefined // `@/alias`, `@foo` — not a real package
+    if (!scope || scope === "@" || !name) return undefined // `@/alias`, `@foo` - not a real package
     const pkg = `${scope}/${name}`
     return isNpmPackageName(pkg) ? pkg : undefined
   }
@@ -66,7 +66,7 @@ export function packageOf(spec: string): string | undefined {
 }
 
 /** Build a predicate matching tsconfig `paths` aliases (e.g. `@/*`, `~/utils`), which resolve to local
- * source, not npm packages — so doctor must not flag them. */
+ * source, not npm packages - so doctor must not flag them. */
 export function aliasMatcher(
   paths: Readonly<Record<string, unknown>> | undefined,
 ): (spec: string) => boolean {
@@ -113,13 +113,13 @@ export function scanUndeclaredImports(
 export interface DoctorFinding {
   readonly file: string
   readonly line: number
-  /** The undeclared package name — add it to `package.json` dependencies. */
+  /** The undeclared package name - add it to `package.json` dependencies. */
   readonly package: string
 }
 
 export interface DoctorResult {
   readonly ok: boolean
-  /** `false` when no `package.json` was found at cwd — doctor can't run (reported, not a crash). */
+  /** `false` when no `package.json` was found at cwd - doctor can't run (reported, not a crash). */
   readonly ran: boolean
   readonly findings: readonly DoctorFinding[]
   /** Packages that resolve to more than one physical install across this workspace. */
@@ -336,13 +336,75 @@ const displayPath = (cwd: string, path: string): string => {
   return rel === "" ? "." : rel
 }
 
+/**
+ * Resolve the workspace root that actually governs `cwd`, or `undefined` when there is none.
+ *
+ * Everything below is anchored to a package that declares `workspaces`. In a monorepo you run
+ * `nifra check` from the app - `apps/web` - and THAT manifest declares nothing, so the scan collapses
+ * to the app itself and the sibling package holding the second copy is never probed. Running from an
+ * app subdirectory is the normal case, which made this the configuration the check was blind in.
+ *
+ * An ancestor is adopted only when its `workspaces` patterns genuinely match `cwd`. A parent
+ * directory that happens to contain a manifest is not automatically this project's root, and adopting
+ * one would silently widen the scan to an unrelated tree. The walk also stops at a `.git` boundary
+ * (checked after the manifest, so a repo root that IS the workspace root still counts) and at the
+ * filesystem root.
+ */
+/** Whether `path` exists at all. `stat`, not a file read: a `.git` is a directory in a normal
+ * checkout and a FILE in a worktree or submodule, and both mark the same boundary. */
+const pathExists = (path: string): Promise<boolean> =>
+  stat(path).then(
+    () => true,
+    () => false,
+  )
+
+async function findWorkspaceRoot(
+  cwd: string,
+): Promise<{ root: string; package: Record<string, unknown> } | undefined> {
+  let dir = dirname(cwd)
+  for (;;) {
+    const manifestPath = join(dir, "package.json")
+    const manifest = await readJson(manifestPath)
+    if (manifest !== undefined) {
+      const patterns = workspacePatterns(manifest)
+      if (patterns.length > 0 && (await patternsCover(dir, patterns, cwd))) {
+        return { root: dir, package: manifest }
+      }
+    }
+    // A `.git` here means we have reached this project's boundary; anything above belongs to a
+    // different repo (or a parent checkout) and must not be adopted.
+    if (await pathExists(join(dir, ".git"))) return undefined
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** Whether any of `root`'s workspace patterns resolves to a manifest inside `target`'s package. */
+async function patternsCover(root: string, patterns: string[], target: string): Promise<boolean> {
+  for (const pattern of patterns) {
+    const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
+    for await (const rel of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
+      if (rel.split(/[\\/]/).includes("node_modules")) continue
+      if (dirname(join(root, rel)) === target) return true
+    }
+  }
+  return false
+}
+
 /** Find identity-sensitive dependencies that resolve to multiple physical directories. Two copies at
- * the same version still fail: module identity (React hooks, Nifra symbols/registries) is path-based. */
+ * the same version still fail: module identity (React hooks, Nifra symbols/registries) is path-based.
+ *
+ * `cwd` is where the user ran the check; the scan is anchored at the workspace root above it (see
+ * {@link findWorkspaceRoot}) so sibling packages are probed, while paths are still REPORTED relative
+ * to `cwd` so the findings read the way the user's terminal does. */
 export async function collectDuplicateInstalls(
   cwd: string,
   rootPackage: Record<string, unknown>,
 ): Promise<DuplicateInstallFinding[]> {
-  const importers = await workspaceImporters(cwd, rootPackage)
+  const workspace = await findWorkspaceRoot(cwd)
+  const scanRoot = workspace?.root ?? cwd
+  const importers = await workspaceImporters(scanRoot, workspace?.package ?? rootPackage)
   const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
   const record = (
     name: string,
@@ -364,7 +426,10 @@ export async function collectDuplicateInstalls(
     for (const name of duplicateTargets(importer.package)) {
       if (importer.package.name === name) continue
       targets.add(name)
-      const copy = await resolvedInstalledCopy(importer.root, cwd, name)
+      // Boundary is the SCAN root, not `cwd`: an importer can now sit beside or above the directory
+      // the user ran from, and stopping the upward walk at `cwd` would abandon it before reaching the
+      // hoisted copy it actually resolves.
+      const copy = await resolvedInstalledCopy(importer.root, scanRoot, name)
       if (copy !== undefined) record(name, copy, displayPath(cwd, importer.root))
     }
   }
@@ -374,8 +439,8 @@ export async function collectDuplicateInstalls(
   // out hides the very split it should catch: every declaring package nested onto one copy while the
   // root resolved a different one, which reads as a single copy when only declarers are consulted.
   for (const name of targets) {
-    const copy = await resolvedInstalledCopy(cwd, cwd, name)
-    if (copy !== undefined) record(name, copy, ".")
+    const copy = await resolvedInstalledCopy(scanRoot, scanRoot, name)
+    if (copy !== undefined) record(name, copy, displayPath(cwd, scanRoot))
   }
 
   const findings: DuplicateInstallFinding[] = []
@@ -557,7 +622,7 @@ export async function runDoctor(
   }
   console.log("nifra doctor\n")
   if (!result.ran) {
-    console.log("• no package.json at this directory — nothing to check")
+    console.log("• no package.json at this directory - nothing to check")
     return true
   }
   if (result.fixed && result.fixed.length > 0) {
@@ -570,7 +635,7 @@ export async function runDoctor(
   if (result.skippedFixes && result.skippedFixes.length > 0) {
     console.log("• not auto-fixed:")
     for (const f of result.skippedFixes) {
-      console.log(`  ${f.package} — ${f.reason}; run \`${f.command.join(" ")}\``)
+      console.log(`  ${f.package} - ${f.reason}; run \`${f.command.join(" ")}\``)
     }
     console.log("")
   }

package/src/examples.ts

@@ -1,8 +1,8 @@
 /**
- * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`
  * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
  * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
- * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ * installed version - the antidote to an agent hallucinating a framework API from stale training.
  *
  * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
  * code body. No query → a grouped index of what's available (the cheap discovery call).
@@ -12,9 +12,9 @@ import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-
 
 export interface Example {
   readonly name: string
-  /** The doc page's title, e.g. "Nifra — Auth & sessions". */
+  /** The doc page's title, e.g. "Nifra - Auth & sessions". */
   readonly topic: string
-  /** The doc page slug, e.g. "auth" — a short, matchable tag. */
+  /** The doc page slug, e.g. "auth" - a short, matchable tag. */
   readonly slug: string
   readonly code: string
 }
@@ -63,19 +63,19 @@ export function renderExamplesResult(
     const index = [...byTopic.entries()]
       .map(([topic, names]) => `- **${topic}**: ${names.join(", ")}`)
       .join("\n")
-    return `# nifra examples — index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version — prefer these over recalling an API.\n\n${index}`
+    return `# nifra examples - index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version - prefer these over recalling an API.\n\n${index}`
   }
   const matches = searchExamples(examples, query, limit)
   if (matches.length === 0) {
     return `No examples matched ${JSON.stringify(query)}. Call without a query for the index, or try a broader term (e.g. "auth", "upload", "isr", "client").`
   }
   return matches
-    .map((m) => `## ${m.name} — ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
+    .map((m) => `## ${m.name} - ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
     .join("\n\n---\n\n")
 }
 
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
 export async function loadExamplesCorpus(): Promise<Example[] | undefined> {
   const url = new URL("../docs/examples.json", import.meta.url)
   try {

package/src/init-agents.ts

@@ -1,18 +1,18 @@
 /**
- * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * `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)
+ *   .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.
+ * 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
+ * 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).
@@ -34,10 +34,10 @@ import {
 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. */
+  /** `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"). */
+  /** Why it was skipped/left, for the notice (e.g. "exists - pass --force to overwrite"). */
   readonly note?: string
 }
 
@@ -52,7 +52,7 @@ export interface InitAgentsOptions {
 }
 
 /** 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
+ * 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)
@@ -80,7 +80,7 @@ async function writeOwned(
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
   if (!force && (await fileExists(abs))) {
-    return { path: rel, action: "skipped", note: "exists — pass --force to overwrite" }
+    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 })
@@ -91,7 +91,7 @@ async function writeOwned(
 /**
  * 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
+ * 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> {
@@ -121,7 +121,7 @@ async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
 
 /**
  * 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.
+ * no console) - the CLI wrapper handles printing + the exit code.
  */
 export async function initAgents(
   cwd: string,
@@ -153,13 +153,13 @@ export function renderInitAgents(result: InitAgentsResult): string {
   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)."
+    : "\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`
+ * 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(

package/src/internal/typescript-import.ts

@@ -0,0 +1,33 @@
+/**
+ * The one place the CLI imports TypeScript from.
+ *
+ * The interpolated-SQL rule parses source with the TypeScript compiler, because the regex it replaced
+ * could not tell `sql\`… ${id} …\`` (bound) from a plain template (injectable) without guessing at
+ * string and comment boundaries. That is the right tool, but it is a ~25 MB dependency, and the CLI's
+ * own typecheck step already treats `tsc` as something the PROJECT provides rather than something the
+ * CLI ships. Making it a hard dependency would have contradicted that for every install.
+ *
+ * So it is an optional peer, resolved at the moment the rule runs. Every Nifra project has TypeScript
+ * - the templates all ship a `typecheck` script - so this resolves in practice; the point is that an
+ * install does not pay for it.
+ */
+
+/** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
+export type TypeScriptApi = typeof import("typescript")
+
+/**
+ * Import the project's TypeScript, or `undefined` when it is not installed.
+ *
+ * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
+ * broken install, not a missing one, and telling that user to install what they already have sends
+ * them the wrong way - so that error is rethrown for the caller to report.
+ */
+export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
+  try {
+    return (await import("typescript")) as TypeScriptApi
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)) return undefined
+    throw cause
+  }
+}