@nifrajs/cli 2.2.0 → 2.3.0

package/dist/docs-search.js

@@ -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;
@@ -56,7 +56,7 @@ export function searchSections(sections, query, limit) {
     }
     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;
 /** Render the tool result: matched sections, or the index when no query was given. */
@@ -64,7 +64,7 @@ export function renderDocsResult(markdown, query, limit) {
     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) {
@@ -73,14 +73,14 @@ export function renderDocsResult(markdown, query, limit) {
     return matches
         .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}`;
     })
         .join("\n\n---\n\n");
 }
 /** 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() {
     const url = new URL("../docs/llms-full.txt", import.meta.url);
     try {

package/dist/doctor.d.ts

@@ -6,7 +6,7 @@ import { type SourceFinding } from "./check.js";
  */
 export declare 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 declare function aliasMatcher(paths: Readonly<Record<string, unknown>> | undefined): (spec: string) => boolean;
 /**
  * Scan one file for bare imports whose resolved package is neither `declared` nor a path `alias`. Pure +
@@ -16,12 +16,12 @@ export declare function scanUndeclaredImports(file: string, content: string, dec
 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. */

package/dist/doctor.js

@@ -1,14 +1,14 @@
 /**
- * `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, stat } from "node:fs/promises";
 import { builtinModules } from "node:module";
@@ -23,7 +23,7 @@ const BUILTINS = new Set([
 ]);
 // 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 = [
     /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
@@ -53,7 +53,7 @@ export function packageOf(spec) {
     if (spec.startsWith("@")) {
         const [scope, name] = spec.split("/");
         if (!scope || scope === "@" || !name)
-            return undefined; // `@/alias`, `@foo` — not a real package
+            return undefined; // `@/alias`, `@foo` - not a real package
         const pkg = `${scope}/${name}`;
         return isNpmPackageName(pkg) ? pkg : undefined;
     }
@@ -63,7 +63,7 @@ export function packageOf(spec) {
     return BUILTINS.has(name) ? undefined : name;
 }
 /** 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) {
     const prefixes = Object.keys(paths ?? {})
         .map((k) => k.replace(/\/?\*$/, ""))
@@ -504,7 +504,7 @@ export async function runDoctor(cwd, opts = {}) {
     }
     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) {
@@ -517,7 +517,7 @@ export async function runDoctor(cwd, opts = {}) {
     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/dist/examples.d.ts

@@ -1,17 +1,17 @@
 /**
- * `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).
  */
 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;
 }
@@ -25,6 +25,6 @@ export declare function searchExamples(examples: readonly Example[], query: stri
 /** Render the tool result: matched examples as fenced code blocks, or the grouped index when no query. */
 export declare function renderExamplesResult(examples: readonly Example[], query: string | undefined, limit: number): string;
 /** 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 declare function loadExamplesCorpus(): Promise<Example[] | undefined>;
 //# sourceMappingURL=examples.d.ts.map

package/dist/examples.js

@@ -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).
@@ -42,18 +42,18 @@ export function renderExamplesResult(examples, query, limit) {
         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() {
     const url = new URL("../docs/examples.json", import.meta.url);
     try {

package/dist/init-agents.d.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).
@@ -21,10 +21,10 @@
 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;
 }
 export interface InitAgentsResult {
@@ -36,19 +36,19 @@ export interface InitAgentsOptions {
     readonly force?: boolean;
 }
 /** 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 declare function safeJoin(cwd: string, rel: string): string;
 /**
  * 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 declare function initAgents(cwd: string, opts?: InitAgentsOptions): Promise<InitAgentsResult>;
 /** Format the retrofit result for the terminal. */
 export declare function renderInitAgents(result: InitAgentsResult): string;
 /**
  * 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 declare function runInitAgents(cwd: string, opts?: {

package/dist/init-agents.js

@@ -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).
@@ -21,7 +21,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import { AGENTS_MD_PATH, agentsMcpSection, CLAUDE_MD_PATH, CURSOR_MCP_JSON_PATH, claudeMd, MCP_JSON_PATH, mcpJson, } from "create-nifra/agent-files";
 /** 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, rel) {
     const abs = resolve(cwd, rel);
@@ -41,7 +41,7 @@ const fileExists = (path) => readFile(path)
 async function writeOwned(cwd, rel, content, force) {
     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 });
@@ -51,7 +51,7 @@ async function writeOwned(cwd, rel, content, force) {
 /**
  * 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) {
@@ -78,7 +78,7 @@ async function ensureAgentsMd(cwd) {
 }
 /**
  * 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, opts = {}) {
     const force = opts.force ?? false;
@@ -105,12 +105,12 @@ export function renderInitAgents(result) {
     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(cwd, opts = {}) {

package/dist/internal/typescript-import.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function importTypeScript(): Promise<TypeScriptApi | undefined>;
+//# sourceMappingURL=typescript-import.d.ts.map

package/dist/internal/typescript-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-import.d.ts","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,cAAc,YAAY,CAAC,CAAA;AAEvD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAQ3E"}

package/dist/internal/typescript-import.js

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * 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() {
+    try {
+        return (await import("typescript"));
+    }
+    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;
+    }
+}
+//# sourceMappingURL=typescript-import.js.map

package/dist/internal/typescript-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-import.js","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAkB,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,IAAI,sDAAsD,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,SAAS,CAAA;QAC1F,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/introspect.d.ts

@@ -1,6 +1,6 @@
 /**
- * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
- * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * Introspect a loaded nifra project into a Markdown brief - the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary - for piping into an AI coding agent's
  * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
  * *this* project's actual surface, not just generic docs.
  */
@@ -10,31 +10,31 @@ import type { LoadedApp } from "./load.js";
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
 export declare function backendRoutes(backend: unknown): ReflectedRoute[];
 /**
- * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) - the
  * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
  * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
  * is always faithful, just not always minimal.
  */
 export declare function tsTypeOf(schema: unknown, depth?: number): string;
 /**
- * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
- * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  */
 export declare function clientCall(method: string, path: string, schema: unknown): string;
 /** Markdown section listing the backend's API routes with their request + response field shapes. */
 export declare function apiRoutesSection(routes: readonly ReflectedRoute[]): string;
-/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+/** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
 export declare function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string;
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export declare function pageRoutesSection(manifest: Manifest | undefined): string;
-/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+/** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
  * brief omits the conventions block (the agent already has it from its first full call), so
  * follow-up calls cost a fraction of the tokens. */
 export interface ContextFilter {
@@ -42,9 +42,9 @@ export interface ContextFilter {
     readonly kind?: "api" | "pages";
 }
 /**
- * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** - the route list (API
  * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
- * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * contracts via the slice - so learning a big project is cheap, not a full-surface schema dump. Passing a
  * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
@@ -61,7 +61,7 @@ export interface RouteJson {
     readonly response?: string;
 }
 /**
- * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * The backend's API routes as structured JSON - what the `nifra_routes` MCP tool returns, so an agent
  * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
@@ -76,7 +76,7 @@ export interface RouteTableEntry {
     readonly path: string;
     /** Methods this route serves, sorted (page: `GET`, plus `POST` when it has an `action`). */
     readonly methods: readonly string[];
-    /** Source file (page only — the route module path relative to `routes/`). */
+    /** Source file (page only - the route module path relative to `routes/`). */
     readonly file?: string;
     /** True when this API route is auto-mounted under the page router's `apiPrefix` (so it's reachable
      * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
@@ -98,7 +98,7 @@ export interface RouteTableInput {
     readonly apiPrefix?: string;
 }
 /**
- * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * Build the unified, sorted route table from page routes + backend API routes. Pure - the caller
  * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
  * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
  * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the