@nifrajs/cli 2.14.1 → 3.2.0

package/dist/frontend-guidance.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `nifra_frontend` - a symptom-indexed catalog of the mistakes an agent (or a human) hits on the client
+ * side of a nifra app, across every adapter. It is the FRONTEND companion to `nifra_check`: where the
+ * check statically flags the footguns nifra's own seam owns (server-only imports, the nano lane), this
+ * catalog covers the ones a static rule can't own cheaply - hydration nondeterminism, a duplicated
+ * framework runtime, and the per-framework reactivity-loss idioms that each ecosystem's own linter is
+ * the real authority on.
+ *
+ * Deliberately a compact reference, not an accumulated fault corpus: two kinds of entry only.
+ *   - Seam entries (`adapters: ["all"]`) - the boundary nifra defines: server/client split, the loader
+ *     data contract, hydration determinism, one framework copy. These point at a `nifra_*` tool to fix
+ *     and verify, because nifra owns that surface.
+ *   - Framework entries - the classic reactivity-loss shape for one adapter (Vue ref, Solid props,
+ *     Svelte runes, React/Preact deps). These point at that framework's own ESLint plugin, which is the
+ *     authority; nifra does not re-implement it, it routes you to it.
+ *
+ * One source, two heads: `nifra_frontend` (MCP) serves it to an agent; `nifra frontend` (CLI) prints it
+ * for a human. Both call {@link renderFrontendResult}, so they can never drift.
+ */
+import type { Framework } from "./scaffold.js";
+/** An adapter an entry applies to, or `all` for a seam issue that is adapter-independent. */
+export type GuidanceAdapter = Framework | "all";
+export interface GuidanceEntry {
+    /** Stable slug, e.g. `server-import`. */
+    readonly id: string;
+    /** Which adapters this applies to. `["all"]` is a seam issue every adapter shares. */
+    readonly adapters: readonly GuidanceAdapter[];
+    /** What you observe - the searchable symptom, phrased as the failure, not the cause. */
+    readonly symptom: string;
+    /** Why it happens. */
+    readonly cause: string;
+    /** The concrete change that fixes it. */
+    readonly fix: string;
+    /** How to confirm it is fixed - a `nifra_*` tool for a seam issue, the framework's linter otherwise. */
+    readonly verify: string;
+    /** Where to go deeper - a `nifra_docs`/`nifra_example` query, or the ecosystem linter that owns it. */
+    readonly seeAlso?: string | undefined;
+}
+/**
+ * The catalog. Seam entries first (they are the nifra-specific value and apply everywhere), then the
+ * per-framework reactivity-loss entries. Keep it compact and high-signal - a curated fault corpus mined
+ * from real failures is operated depth and lives elsewhere, not in the public package.
+ */
+export declare const FRONTEND_GUIDANCE: readonly GuidanceEntry[];
+/** Normalize a free-text adapter argument to a known adapter, or `undefined` if it is not one. */
+export declare function parseAdapter(value: string | undefined): GuidanceAdapter | undefined;
+/**
+ * Render the catalog. Filters by `adapter` (when it names a known one), then by a `symptom` keyword
+ * query. With no query it returns the (filtered) index; with a query it returns the best-matching
+ * entries in full, or the index plus a "no match" note when nothing scores. Pure, so both heads agree.
+ */
+export declare function renderFrontendResult(args: {
+    adapter?: string | undefined;
+    symptom?: string | undefined;
+    limit?: number | undefined;
+}): string;
+//# sourceMappingURL=frontend-guidance.d.ts.map

package/dist/frontend-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-guidance.d.ts","sourceRoot":"","sources":["../src/frontend-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,6FAA6F;AAC7F,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wGAAwG;IACxG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,aAAa,EAuHrD,CAAA;AAYD,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAGnF;AA2CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B,GAAG,MAAM,CAwBT"}

package/dist/frontend-guidance.js

@@ -0,0 +1,195 @@
+/**
+ * `nifra_frontend` - a symptom-indexed catalog of the mistakes an agent (or a human) hits on the client
+ * side of a nifra app, across every adapter. It is the FRONTEND companion to `nifra_check`: where the
+ * check statically flags the footguns nifra's own seam owns (server-only imports, the nano lane), this
+ * catalog covers the ones a static rule can't own cheaply - hydration nondeterminism, a duplicated
+ * framework runtime, and the per-framework reactivity-loss idioms that each ecosystem's own linter is
+ * the real authority on.
+ *
+ * Deliberately a compact reference, not an accumulated fault corpus: two kinds of entry only.
+ *   - Seam entries (`adapters: ["all"]`) - the boundary nifra defines: server/client split, the loader
+ *     data contract, hydration determinism, one framework copy. These point at a `nifra_*` tool to fix
+ *     and verify, because nifra owns that surface.
+ *   - Framework entries - the classic reactivity-loss shape for one adapter (Vue ref, Solid props,
+ *     Svelte runes, React/Preact deps). These point at that framework's own ESLint plugin, which is the
+ *     authority; nifra does not re-implement it, it routes you to it.
+ *
+ * One source, two heads: `nifra_frontend` (MCP) serves it to an agent; `nifra frontend` (CLI) prints it
+ * for a human. Both call {@link renderFrontendResult}, so they can never drift.
+ */
+/**
+ * The catalog. Seam entries first (they are the nifra-specific value and apply everywhere), then the
+ * per-framework reactivity-loss entries. Keep it compact and high-signal - a curated fault corpus mined
+ * from real failures is operated depth and lives elsewhere, not in the public package.
+ */
+export const FRONTEND_GUIDANCE = [
+    {
+        id: "server-import",
+        adapters: ["all"],
+        symptom: "A client component crashes at build or runtime with a missing Node built-in, a leaked secret, or 'module not found in the browser'.",
+        cause: "A server-only module (the DB, a secret, `node:*`, the backend file) is imported at the top level of a component, so the bundler tries to ship it to the browser.",
+        fix: "Move the access into a server-only `loader`/`action` and read the result in the component. Reach the backend through the typed `api` argument, never a top-level server-only import.",
+        verify: "nifra_check - its transitive server-import scan flags the exact import chain into a client module.",
+        seeAlso: "loader action server-only import boundary",
+    },
+    {
+        id: "hydration-mismatch",
+        adapters: ["all"],
+        symptom: "A hydration warning, text that flips on load, or 'server HTML did not match client' the first time the page becomes interactive.",
+        cause: "The first client render is not identical to the SSR HTML - usually a non-deterministic read during render: `Date.now()`, `Math.random()`, `window`/`localStorage`, or a locale/timezone the server did not have.",
+        fix: "Render deterministic markup, then apply anything client-only in an effect / `onMount` after the first paint. Pass anything the server knew (time, locale, flags) down through loader data so both renders agree.",
+        verify: "nifra_render the route and diff its HTML against the first client render; nifra_check's hydration assurance reports nondeterminism it can see.",
+        seeAlso: "hydration ssr determinism loader data",
+    },
+    {
+        id: "duplicate-runtime",
+        adapters: ["react", "preact", "solid", "vue", "svelte"],
+        symptom: "'Invalid hook call', a null context/provider, signals that never update, or a component that mounts twice.",
+        cause: "Two copies of the framework are in the bundle - the app's own dependency and a second one resolved through the adapter - so the two runtimes do not share the same module-level state.",
+        fix: "Dedupe the framework to a single version across the workspace (one entry in the lockfile). The adapter must resolve the app's copy, not bundle its own.",
+        verify: "nifra_doctor - it detects a duplicated framework runtime (NF-H002).",
+        seeAlso: "duplicate framework runtime dedupe NF-H002",
+    },
+    {
+        id: "loader-typing",
+        adapters: ["all"],
+        symptom: "Loader data is typed `any` in the page, or a hand-written interface silently drifts from what the loader actually returns.",
+        cause: "The component types its props by hand instead of inferring them from the loader, so a change to the loader is not a type error at the use site.",
+        fix: "Type the page from the loader: `props: { data: LoaderData<typeof loader> }`. Call the backend through the typed `api` so the request/response shape is inferred, not restated.",
+        verify: "nifra_context prints the exact loader shape and typed call form; nifra_check fails on drift.",
+        seeAlso: "LoaderData typed client loader inference",
+    },
+    {
+        id: "list-key",
+        adapters: ["all"],
+        symptom: "List rows keep the wrong state on reorder/insert - a checked box, focus, or an input value jumps to a different row.",
+        cause: "The list is keyed by the array index (or not keyed at all), so add/remove/reorder maps the wrong item to an existing node.",
+        fix: "Key each row by a stable, unique id from the item, never its position in the array.",
+        verify: "The framework's own linter for JSX keys; on the vanilla nano lane, nifra_check flags an index key as NF-C022.",
+        seeAlso: "list key stable id reconcile nano",
+    },
+    {
+        id: "vue-lost-reactivity",
+        adapters: ["vue"],
+        symptom: "A value stops updating the template after you pull it out of a ref, reactive object, or props.",
+        cause: "Destructuring a `reactive()` object or `props` copies the current value and drops the reactive link; a `ref` read in script forgets `.value`.",
+        fix: "Keep the reactive source intact: use `toRefs`/`storeToRefs` when you must destructure, access `props.x` directly, and remember `.value` on a ref in script (templates unwrap it for you).",
+        verify: "eslint-plugin-vue - it is the authority on Vue reactivity; nifra does not re-implement it.",
+        seeAlso: "eslint-plugin-vue toRefs reactivity",
+    },
+    {
+        id: "solid-lost-reactivity",
+        adapters: ["solid"],
+        symptom: "A prop or store value renders once and never tracks updates in a Solid component.",
+        cause: "Solid props are getters, evaluated where you read them. Destructuring props (or reading them outside JSX/an effect) reads once and loses tracking.",
+        fix: "Access `props.x` at the point of use inside JSX, or `splitProps`/`mergeProps` when you need to pass a subset on. Never destructure props in the function signature.",
+        verify: "eslint-plugin-solid - the authority on Solid reactivity; nifra routes you to it, not around it.",
+        seeAlso: "eslint-plugin-solid splitProps props getters",
+    },
+    {
+        id: "svelte-runes",
+        adapters: ["svelte"],
+        symptom: "In a Svelte 5 component, `export let` props or a `$:` statement do not behave as expected, or the compiler rejects them in runes mode.",
+        cause: "Runes mode replaces the Svelte 4 idioms: props come from `$props()`, derived values from `$derived`, side effects from `$effect`. Mixing the two models is the mismatch.",
+        fix: "In runes mode use `$props()` for inputs, `$state` for local state, `$derived` for computed values, and `$effect` for side effects - not `export let` or `$:`.",
+        verify: "eslint-plugin-svelte and the Svelte compiler warnings own this; nifra points you at them.",
+        seeAlso: "eslint-plugin-svelte runes $props $derived",
+    },
+    {
+        id: "react-stale-deps",
+        adapters: ["react", "preact"],
+        symptom: "An effect or callback uses a stale value, fires too often, or never re-runs when a value it reads changes.",
+        cause: "The dependency array omits a value the effect/callback closes over (or the effect has no array), so the closure captures an old render's value.",
+        fix: "List every reactive value the effect reads in its deps, or hold the mutable value in a ref when it must not trigger a re-run. Do not silence the rule by emptying the array.",
+        verify: "eslint-plugin-react-hooks (`exhaustive-deps`) is the authority on effect deps; nifra does not duplicate it.",
+        seeAlso: "eslint-plugin-react-hooks exhaustive-deps effect closure",
+    },
+    {
+        id: "prefer-nano-or-island",
+        adapters: ["vanilla"],
+        symptom: "A vanilla page needs local state or a list a human edits, and hand-written DOM updates are getting fragile.",
+        cause: "The islands lane is imperative and has no state primitive, so each update is hand-wired and a list means rebuilding the container.",
+        fix: "Use the nano lane: `signal` + `computed(fn, [deps])` for state, `bindList` for a keyed list, `resource` for async. Every reactive edge is a visible call, so its mistakes are static lints.",
+        verify: "nifra_check runs NF-C021 (discarded disposer), NF-C022 (index key), NF-C023 (missing dep) over the nano code.",
+        seeAlso: "nano signal computed bindList resource islands",
+    },
+];
+const ADAPTER_ALIASES = {
+    all: "all",
+    react: "react",
+    preact: "preact",
+    solid: "solid",
+    vue: "vue",
+    svelte: "svelte",
+    vanilla: "vanilla",
+};
+/** Normalize a free-text adapter argument to a known adapter, or `undefined` if it is not one. */
+export function parseAdapter(value) {
+    if (value === undefined)
+        return undefined;
+    return ADAPTER_ALIASES[value.trim().toLowerCase()];
+}
+const appliesTo = (entry, adapter) => adapter === "all" || entry.adapters.includes("all") || entry.adapters.includes(adapter);
+/** Keyword score of an entry against a query - counts distinct query words found in its text. */
+function score(entry, words) {
+    const hay = `${entry.id} ${entry.symptom} ${entry.cause} ${entry.fix} ${entry.seeAlso ?? ""}`.toLowerCase();
+    let hits = 0;
+    for (const w of words)
+        if (hay.includes(w))
+            hits++;
+    return hits;
+}
+function renderEntry(entry) {
+    const scope = entry.adapters.includes("all") ? "all adapters" : entry.adapters.join(", ");
+    const parts = [
+        `[${entry.id}]  (${scope})`,
+        `Symptom: ${entry.symptom}`,
+        `Cause:   ${entry.cause}`,
+        `Fix:     ${entry.fix}`,
+        `Verify:  ${entry.verify}`,
+    ];
+    if (entry.seeAlso !== undefined)
+        parts.push(`See:     ${entry.seeAlso}`);
+    return parts.join("\n");
+}
+function renderIndex(entries, adapter) {
+    const scope = adapter === undefined ? "all adapters" : `adapter: ${adapter}`;
+    const lines = entries.map((e) => {
+        const s = e.adapters.includes("all") ? "all" : e.adapters.join("/");
+        return `- ${e.id} (${s}) - ${e.symptom}`;
+    });
+    return [
+        `nifra frontend guidance (${entries.length} of ${FRONTEND_GUIDANCE.length}, ${scope}). Pass a symptom to get the cause + fix + how to verify; pass an adapter to filter.`,
+        "",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Render the catalog. Filters by `adapter` (when it names a known one), then by a `symptom` keyword
+ * query. With no query it returns the (filtered) index; with a query it returns the best-matching
+ * entries in full, or the index plus a "no match" note when nothing scores. Pure, so both heads agree.
+ */
+export function renderFrontendResult(args) {
+    const adapter = parseAdapter(args.adapter);
+    const scoped = adapter === undefined
+        ? FRONTEND_GUIDANCE
+        : FRONTEND_GUIDANCE.filter((e) => appliesTo(e, adapter));
+    const query = args.symptom?.trim();
+    if (query === undefined || query.length === 0)
+        return renderIndex(scoped, adapter);
+    const words = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 1);
+    const limit = Math.min(Math.max(args.limit ?? 3, 1), 5);
+    const ranked = scoped
+        .map((entry) => ({ entry, s: score(entry, words) }))
+        .filter((r) => r.s > 0)
+        .sort((a, b) => b.s - a.s)
+        .slice(0, limit);
+    if (ranked.length === 0) {
+        return `No frontend-guidance entry matched "${query}"${adapter ? ` for ${adapter}` : ""}.\n\n${renderIndex(scoped, adapter)}`;
+    }
+    return ranked.map((r) => renderEntry(r.entry)).join("\n\n");
+}
+//# sourceMappingURL=frontend-guidance.js.map

package/dist/frontend-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-guidance.js","sourceRoot":"","sources":["../src/frontend-guidance.ts"],"names":[],"mappings":"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"}

package/dist/internal/reserved-segment-codemod.d.ts

@@ -0,0 +1,36 @@
+export interface CollisionSite {
+    readonly file: string;
+    /** 1-based, as `tsc` reports them. */
+    readonly line: number;
+    readonly column: number;
+    /** The colliding path segment, read out of the type the compiler named. */
+    readonly segment: string;
+}
+/** Every reserved-segment collision `tsc` reported, in the order it reported them. */
+export declare function parseCollisionSites(tscOutput: string): readonly CollisionSite[];
+/**
+ * The span to replace for one site: the `.segment` immediately preceding the failing property access,
+ * which becomes `("segment")`. Undefined when the text does not have that shape - the caller reports
+ * those rather than rewriting something it did not recognise.
+ *
+ * The scan runs backwards over the whole source rather than one line, so a chain broken across lines
+ * (`api.foo\n  .delete\n  .post()`) rewrites the same as a chain on one line.
+ */
+export declare function collisionSpan(source: string, site: CollisionSite): {
+    readonly start: number;
+    readonly end: number;
+} | undefined;
+export interface FileRewrite {
+    readonly source: string;
+    /** Sites in this file the scan declined to rewrite, so the caller can report them. */
+    readonly skipped: readonly CollisionSite[];
+}
+/**
+ * Apply every site belonging to one file. Spans are applied back to front so an earlier rewrite never
+ * shifts the offsets of one not yet applied, and a duplicate span (two failing properties resolving
+ * through the same access) is applied once.
+ */
+export declare function rewriteFile(source: string, sites: readonly CollisionSite[]): FileRewrite;
+/** The project's own `tsc` binary, found upward from `root`. Never installs one. */
+export declare function resolveTscBin(root: string): string | undefined;
+//# sourceMappingURL=reserved-segment-codemod.d.ts.map

package/dist/internal/reserved-segment-codemod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-segment-codemod.d.ts","sourceRoot":"","sources":["../../src/internal/reserved-segment-codemod.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CAe/E;AAoBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAClB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAwB9D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,WAAW,CAiBxF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAS9D"}

package/dist/internal/reserved-segment-codemod.js

@@ -0,0 +1,134 @@
+/**
+ * Codemod for reserved-segment collisions in typed-client call sites.
+ *
+ * A route segment spelling a reserved proxy key (`get`…`options`, `subscribe`, `ws`, `index`, `then`)
+ * cannot be reached by property access - the proxy resolves the reserved behavior first - so the client
+ * type resolves that child to `ReservedSegmentCollision<"seg">` and every `api.foo.delete.post()` in the
+ * project stops compiling at once. The fix is mechanical and identical at every site: call the parent
+ * node with the segment instead, `api.foo("delete").post()`. Doing that by hand across a codebase is
+ * pure toil, and it is toil the framework caused.
+ *
+ * The compiler is the site index. `tsc` already reports every broken access, and its message names the
+ * segment (`Property 'post' does not exist on type 'ReservedSegmentCollision<"delete">'`), so the
+ * rewrite needs no type graph of its own and cannot invent a site the compiler did not reject. That
+ * also disambiguates the one case a textual search could not: `.delete` as a real DELETE verb call is
+ * valid and never appears in this list.
+ *
+ * A site the scan cannot rewrite CONFIDENTLY is left alone and reported, never guessed at. Bracket
+ * access, a collision node stored in a variable and used elsewhere, and any shape where the text before
+ * the failing property is not `.<segment>` all fall into that bucket.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** `path/to/file.ts(12,16): error TS2339: … 'ReservedSegmentCollision<"delete">'.` */
+const TSC_POSITION = /^(.+?)\((\d+),(\d+)\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/;
+const COLLISION_TYPE = /ReservedSegmentCollision<"([^"]+)">/;
+/** Every reserved-segment collision `tsc` reported, in the order it reported them. */
+export function parseCollisionSites(tscOutput) {
+    const sites = [];
+    for (const raw of tscOutput.split("\n")) {
+        const position = TSC_POSITION.exec(raw.trim());
+        if (position === null)
+            continue;
+        const segment = COLLISION_TYPE.exec(position[4]);
+        if (segment === null)
+            continue;
+        sites.push({
+            file: position[1],
+            line: Number(position[2]),
+            column: Number(position[3]),
+            segment: segment[1],
+        });
+    }
+    return sites;
+}
+/** Byte offset of a 1-based (line, column) in `source`, or undefined when it is past the end. */
+const offsetOf = (source, line, column) => {
+    let offset = 0;
+    for (let current = 1; current < line; current += 1) {
+        const next = source.indexOf("\n", offset);
+        if (next === -1)
+            return undefined;
+        offset = next + 1;
+    }
+    const target = offset + column - 1;
+    return target <= source.length ? target : undefined;
+};
+const skipSpaceBack = (source, from) => {
+    let index = from;
+    while (index >= 0 && /\s/.test(source[index]))
+        index -= 1;
+    return index;
+};
+/**
+ * The span to replace for one site: the `.segment` immediately preceding the failing property access,
+ * which becomes `("segment")`. Undefined when the text does not have that shape - the caller reports
+ * those rather than rewriting something it did not recognise.
+ *
+ * The scan runs backwards over the whole source rather than one line, so a chain broken across lines
+ * (`api.foo\n  .delete\n  .post()`) rewrites the same as a chain on one line.
+ */
+export function collisionSpan(source, site) {
+    const offset = offsetOf(source, site.line, site.column);
+    if (offset === undefined)
+        return undefined;
+    // Back over the dot that introduces the FAILING property (`.post` in `…delete.post`).
+    let index = skipSpaceBack(source, offset - 1);
+    if (source[index] !== ".")
+        return undefined;
+    // Back over the colliding segment itself.
+    index = skipSpaceBack(source, index - 1);
+    const segmentEnd = index;
+    const segmentStart = segmentEnd - site.segment.length + 1;
+    if (segmentStart < 0)
+        return undefined;
+    if (source.slice(segmentStart, segmentEnd + 1) !== site.segment)
+        return undefined;
+    // Back over the dot that introduces the segment. Anything else (bracket access, a bare identifier
+    // holding the node) is a shape this rewrite does not understand.
+    const dot = skipSpaceBack(source, segmentStart - 1);
+    if (source[dot] !== ".")
+        return undefined;
+    // Take any whitespace before that dot into the span too, so a chain broken across lines closes up
+    // (`api.jobs\n  .subscribe` becomes `api.jobs("subscribe")`) instead of leaving the call argument
+    // dangling on its own line.
+    return { start: skipSpaceBack(source, dot - 1) + 1, end: segmentEnd };
+}
+/**
+ * Apply every site belonging to one file. Spans are applied back to front so an earlier rewrite never
+ * shifts the offsets of one not yet applied, and a duplicate span (two failing properties resolving
+ * through the same access) is applied once.
+ */
+export function rewriteFile(source, sites) {
+    const skipped = [];
+    const spans = [];
+    for (const site of sites) {
+        const span = collisionSpan(source, site);
+        if (span === undefined) {
+            skipped.push(site);
+            continue;
+        }
+        if (spans.some((other) => other.start === span.start && other.end === span.end))
+            continue;
+        spans.push({ ...span, segment: site.segment });
+    }
+    let out = source;
+    for (const span of [...spans].sort((a, b) => b.start - a.start)) {
+        out = `${out.slice(0, span.start)}("${span.segment}")${out.slice(span.end + 1)}`;
+    }
+    return { source: out, skipped };
+}
+/** The project's own `tsc` binary, found upward from `root`. Never installs one. */
+export function resolveTscBin(root) {
+    let dir = root;
+    while (true) {
+        const candidate = join(dir, "node_modules", "typescript", "bin", "tsc");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+//# sourceMappingURL=reserved-segment-codemod.js.map

package/dist/internal/reserved-segment-codemod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-segment-codemod.js","sourceRoot":"","sources":["../../src/internal/reserved-segment-codemod.ts"],"names":[],"mappings":"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"}

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

@@ -14,7 +14,7 @@
 /** 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.
+ * Import TypeScript from the CLI's own dependency tree, 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

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

@@ -1 +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;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAmB9F"}
+{"version":3,"file":"typescript-import.d.ts","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,cAAc,YAAY,CAAC,CAAA;AAyBvD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAQ3E;AA6BD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAgB9F"}

package/dist/internal/typescript-import.js

@@ -19,8 +19,33 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 /**
- * Import the project's TypeScript, or `undefined` when it is not installed.
+ * Is this module actually the compiler, rather than something else published under the same name?
+ *
+ * The `typescript` package name also carries small non-compiler entry points (a version stub, for
+ * one), and a resolver that falls back to a global download cache can hand one of those back. They
+ * import cleanly and then explode on first use - `undefined is not an object (evaluating
+ * 'ts.ScriptKind.TSX')` deep inside a scan - which reads as a Nifra bug rather than as "the compiler
+ * we loaded is not a compiler". Checking the two members every caller needs turns that into a
+ * resolution miss, which the fallbacks below already know how to handle.
+ */
+function isCompiler(module) {
+    if (typeof module !== "object" || module === null)
+        return false;
+    const api = module;
+    return typeof api.createSourceFile === "function" && api.ScriptKind !== undefined;
+}
+/** Unwrap the CJS default interop wrapper, so both `import * as ts` shapes look the same. */
+function compilerOf(module) {
+    if (isCompiler(module))
+        return module;
+    const wrapped = module?.default;
+    return isCompiler(wrapped) ? wrapped : undefined;
+}
+/**
+ * Import TypeScript from the CLI's own dependency tree, 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
@@ -28,7 +53,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  */
 export async function importTypeScript() {
     try {
-        return (await import("typescript"));
+        return compilerOf(await import("typescript"));
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
@@ -37,6 +62,35 @@ export async function importTypeScript() {
         throw cause;
     }
 }
+/**
+ * Find the project's compiler the way module resolution would: `node_modules/typescript` in `root`,
+ * then each parent directory up to the filesystem root - the same walk the typecheck gate uses to
+ * find `tsc`, so both gates agree on which compiler the project has.
+ *
+ * The walk is deliberate, not a fallback for a missing resolver. `Bun.resolveSync` memoizes a
+ * specifier for the life of the process AND auto-installs from the global download cache when the
+ * project has none, so a long-lived process (the MCP server) that first resolved `typescript` before
+ * `bun install` kept handing back that cache entry afterwards - the typecheck went phantom until the
+ * server was restarted. A filesystem probe is re-answered every call, so an install that lands
+ * mid-session is picked up on the next scan.
+ */
+function resolveProjectTypeScript(root) {
+    let dir = root;
+    while (true) {
+        const pkg = join(dir, "node_modules", "typescript");
+        // `lib/typescript.js` is the compiler entry across every published major; probing it directly
+        // (rather than importing the directory) keeps a package whose main entry is a stub out of play.
+        const entry = join(pkg, "lib", "typescript.js");
+        if (existsSync(entry))
+            return entry;
+        if (existsSync(join(pkg, "package.json")))
+            return pkg;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
 /**
  * Import TypeScript resolved from the PROJECT root first, falling back to the CLI's own dependency
  * tree. A bare `import("typescript")` resolves relative to this file - the CLI's install - so a
@@ -46,17 +100,14 @@ export async function importTypeScript() {
  * the CLI was installed - the same cwd-invariance the typecheck gate's tsc resolution has.
  */
 export async function importProjectTypeScript(root) {
-    let resolved;
-    try {
-        resolved = Bun.resolveSync("typescript", root);
-    }
-    catch {
-        // Unresolvable from the project (not installed there, or a non-Bun host without resolveSync):
-        // fall back to the CLI's own tree, which keeps the previous behavior as the floor.
+    const resolved = resolveProjectTypeScript(root);
+    // Not installed in the project (or installed without a compiler entry): fall back to the CLI's own
+    // tree, which keeps the previous behavior as the floor.
+    if (resolved === undefined)
         return importTypeScript();
-    }
     try {
-        return (await import(__rewriteRelativeImportExtension(resolved)));
+        const compiler = compilerOf(await import(__rewriteRelativeImportExtension(resolved)));
+        return compiler ?? (await importTypeScript());
     }
     catch (cause) {
         // Same contract as importTypeScript: a compiler that RESOLVES and then fails evaluating is a

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

@@ -1 +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;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,IAAY;IACxD,IAAI,QAAgB,CAAA;IACpB,IAAI,CAAC;QACH,QAAQ,GAAG,GAAG,CAAC,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,8FAA8F;QAC9F,mFAAmF;QACnF,OAAO,gBAAgB,EAAE,CAAA;IAC3B,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,kCAAC,QAAQ,EAAC,CAAkB,CAAA;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6FAA6F;QAC7F,+FAA+F;QAC/F,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;YACtE,OAAO,gBAAgB,EAAE,CAAA;QAC3B,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}
+{"version":3,"file":"typescript-import.js","sourceRoot":"","sources":["../../src/internal/typescript-import.ts"],"names":[],"mappings":"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"}

package/dist/introspect.d.ts

@@ -26,6 +26,11 @@ export declare function tsTypeOf(schema: unknown, depth?: number): string;
  * 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 -
  * so the `{ query }` argument lands in the right slot for each.
+ *
+ * A segment spelling a reserved proxy key (`delete`, `subscribe`, `then`, ...) is emitted as a call on
+ * the parent node instead - and NOT as bracket access, which does not help: the proxy intercepts the
+ * key however it is spelled. Emitting `.delete` here would hand an agent a chain that resolves the
+ * DELETE verb and silently requests the wrong path.
  */
 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. */
@@ -109,6 +114,20 @@ export interface RouteTableInput {
  * joined methods, for stable output.
  */
 export declare function buildRouteTable(input: RouteTableInput): RouteTableEntry[];
+/**
+ * The typed-client spelling for a route path, and the reserved key it collides with when one of its
+ * static segments cannot be reached by property access.
+ *
+ * This is where a dev meets the reserved set EARLIEST: `nifra routes` is what you run while the
+ * route is being written, long before a typed client call site exists to break. The reserved names
+ * are deliberately unguessable from the outside (`then` and `index` especially - they exist so the
+ * proxy stays await-safe and can address `/`), so the route table names the collision and shows the
+ * spelling that reaches the route, rather than leaving it to be discovered by a failing build.
+ */
+export declare function clientSpellingFor(path: string): {
+    readonly spelling: string;
+    readonly reserved: string;
+} | undefined;
 /** Render the route table as a terse aligned text table (the `nifra routes` default output). Pure. */
 export declare function renderRouteTable(rows: readonly RouteTableEntry[]): string;
 /** One JSON row for `nifra routes --json` (the agent-facing, stable shape). */
@@ -118,9 +137,15 @@ export interface RouteJsonRow {
     readonly methods: readonly string[];
     readonly file?: string;
     readonly autoMounted?: boolean;
+    /** The reserved typed-client key a static segment of this path collides with, when one does. */
+    readonly reservedKey?: string;
+    /** The typed-client call spelling that reaches this route, present only alongside `reservedKey`. */
+    readonly clientSpelling?: string;
 }
 /** The route table as a JSON document for `--json` (agents). Stable keys; `file`/`autoMounted` present
- * only where meaningful (file on pages, autoMounted on API routes). */
+ * only where meaningful (file on pages, autoMounted on API routes). A colliding row additionally
+ * carries `reservedKey`/`clientSpelling` so an agent writing client code from this table never has to
+ * infer the closed set of reserved names - the one thing about it nobody can guess. */
 export declare function routeTableToJson(rows: readonly RouteTableEntry[]): {
     readonly routes: readonly RouteJsonRow[];
 };