@nifrajs/cli 3.5.0 → 4.0.0

package/dist/rules/zones.js

@@ -0,0 +1,174 @@
+/**
+ * NF-C028 and NF-C029: the frontend/backend zone rules, checked from source.
+ *
+ * Every browser build and dev server enforces these already; this reports them without building,
+ * with the same classifier (`@nifrajs/web/zones`) so the three can never disagree. NF-C004 owns
+ * browser code reaching server code (with the chain); NF-C028 owns the other directions: a zoned
+ * file importing one in no zone, backend code importing frontend code, and shared code importing
+ * anything but shared code. NF-C029 owns private environment reads in browser code.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { createZoneClassifier, importAllowed, importRuleMessage, privateEnvReads, privateEnvReason, } from "@nifrajs/web/zones";
+import { CONFIG_FILE, FRAMEWORK_FILE } from "../app-files.js";
+import { importSites, stripComments } from "../check-scan.js";
+import { diagnostic } from "../diagnostics.js";
+import { codeUnitOrder } from "../internal/code-unit-order.js";
+const ZONE_FOLDER = new Set(["routes", "frontend", "backend", "shared"]);
+const FRONTEND = new Set(["route-frontend", "frontend"]);
+const SERVER = new Set(["backend", "route-backend", "fn"]);
+const BACKEND = new Set(["backend", "route-backend"]);
+const BROWSER_CODE = new Set(["route-frontend", "frontend", "shared"]);
+const CODE_FILE = /\.(?:[cm]?[jt]sx?|svelte|vue|mdx)$/;
+/** The app a project file belongs to: the path before its first zone folder, or `undefined`. */
+function appOf(file) {
+    const parts = file.split("/");
+    const at = parts.findIndex((part, i) => i < parts.length - 1 && ZONE_FOLDER.has(part));
+    return at === -1 ? undefined : parts.slice(0, at).join("/");
+}
+/** Every scanned source file that belongs to an app, classified once per app classifier. */
+export function zonedFiles(ctx) {
+    const classifiers = new Map();
+    const classifierFor = (app) => {
+        let classifier = classifiers.get(app);
+        if (classifier === undefined) {
+            const appRoot = join(ctx.root, app);
+            classifier = createZoneClassifier({
+                appRoot,
+                generatedFiles: [join(appRoot, "server-manifest.ts")],
+            });
+            classifiers.set(app, classifier);
+        }
+        return classifier;
+    };
+    const files = [];
+    for (const file of ctx.sources.files) {
+        if (!CODE_FILE.test(file))
+            continue;
+        const app = appOf(file);
+        if (app === undefined)
+            continue;
+        files.push({ file, app, classification: classifierFor(app).classify(join(ctx.root, file)) });
+    }
+    return { files, classifierFor };
+}
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+};
+/** Where a resolved import lands, as the project names it. Both sides are real paths: a checkout
+ * reached through a symlink (`/var` -> `/private/var` on macOS) still names files project-relative. */
+function display(root, file) {
+    const rel = relative(real(root), real(file)).replaceAll("\\", "/");
+    return rel.startsWith("../") || isAbsolute(rel) ? file : rel;
+}
+/** A relative import resolved against the importing file, or `undefined` when it does not resolve. */
+function resolveRelative(root, from, specifier) {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../"))
+        return undefined;
+    try {
+        // Relative specifiers only: a bare one would let the resolver reach for a global install.
+        return Bun.resolveSync(specifier, dirname(join(root, from)));
+    }
+    catch {
+        return undefined;
+    }
+}
+export const zoneImportRule = {
+    code: "NF-C028",
+    title: "Zone import check",
+    async scan(ctx) {
+        const { files, classifierFor } = zonedFiles(ctx);
+        const findings = [];
+        for (const { file, app, classification: from } of files) {
+            if (from.zone === "error" || from.zone === "library" || from.zone === "generated")
+                continue;
+            const content = ctx.sources.read(file);
+            if (content === undefined)
+                continue;
+            for (const { specifier, line } of importSites(content, file)) {
+                const target = resolveRelative(ctx.root, file, specifier);
+                if (target === undefined)
+                    continue;
+                const to = classifierFor(app).classify(target);
+                const targetName = display(ctx.root, target);
+                let message;
+                if (to.zone === "error")
+                    message = `${file} imports ${targetName}: ${to.reason}`;
+                else if ((SERVER.has(from.zone) && FRONTEND.has(to.zone)) ||
+                    // Shared code reaching backend code is NF-C004's, reported there with the chain.
+                    (from.zone === "shared" && !importAllowed(from.zone, to.zone) && !BACKEND.has(to.zone))) {
+                    message = importRuleMessage(file, from.zone, targetName, to.zone);
+                }
+                else
+                    continue;
+                findings.push(diagnostic({
+                    code: "NF-C028",
+                    severity: "error",
+                    file,
+                    line,
+                    message,
+                    evidence: [`import: ${specifier}`, `from zone: ${from.zone}`, `to zone: ${to.zone}`],
+                    verify: "nifra check",
+                }));
+            }
+        }
+        return findings.sort((a, b) => codeUnitOrder(a.file ?? "", b.file ?? "") || (a.line ?? 0) - (b.line ?? 0));
+    },
+};
+const PREFIX_EXPORT = /\bexport\s+const\s+publicEnvPrefix\s*(?::\s*string\s*)?=\s*(?:"([^"\\\r\n]*)"|'([^'\\\r\n]*)')/;
+/** The app's public-env prefix when its config declares it as a string literal, else the default. */
+function publicPrefix(root, app) {
+    for (const config of [FRAMEWORK_FILE, CONFIG_FILE]) {
+        const path = join(root, app, config);
+        if (!existsSync(path))
+            continue;
+        const match = PREFIX_EXPORT.exec(stripComments(readFileSync(path, "utf8")));
+        if (match !== null)
+            return match[1] ?? match[2] ?? "PUBLIC_";
+    }
+    return "PUBLIC_";
+}
+export const privateEnvRule = {
+    code: "NF-C029",
+    title: "Private environment read in browser code",
+    async scan(ctx) {
+        const { files } = zonedFiles(ctx);
+        const prefixes = new Map();
+        const findings = [];
+        for (const { file, app, classification } of files) {
+            if (!BROWSER_CODE.has(classification.zone))
+                continue;
+            const content = ctx.sources.read(file);
+            if (content === undefined)
+                continue;
+            let prefix = prefixes.get(app);
+            if (prefix === undefined) {
+                prefix = publicPrefix(ctx.root, app);
+                prefixes.set(app, prefix);
+            }
+            const reads = privateEnvReads(file, content, prefix);
+            if (reads.length === 0)
+                continue;
+            const first = reads[0] ?? "";
+            const name = /[.[(]["']?([A-Za-z_$][\w$]*)["']?[)\]]?$/.exec(first)?.[1];
+            const index = name === undefined ? -1 : content.indexOf(name);
+            findings.push(diagnostic({
+                code: "NF-C029",
+                severity: "error",
+                file,
+                ...(index === -1 ? {} : { line: content.slice(0, index).split("\n").length }),
+                message: `${file} ${privateEnvReason(reads, prefix)}`,
+                evidence: reads.map((read) => `read: ${read}`),
+                verify: "nifra check",
+            }));
+        }
+        return findings;
+    },
+};
+export const zoneRules = Object.freeze([zoneImportRule, privateEnvRule]);
+//# sourceMappingURL=zones.js.map

package/dist/rules/zones.js.map

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

package/dist/scaffold.d.ts

@@ -1,13 +1,14 @@
 /**
- * `nifra_scaffold` - turn a URL path into the correct `routes/` file (the convention an agent most often
- * gets wrong) + a minimal, contract-correct stub. The mapping is the inverse of @nifrajs/web's
- * `filePathToPatterns`: `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional,
- * `/` → `index`. The framework (→ file extension) comes from the project's `clientModule`.
+ * `nifra_scaffold` - turn a URL path into the correct `routes/` files (the convention an agent most often
+ * gets wrong) + a minimal, contract-correct route pair: the page, and its `.backend.ts` half holding the
+ * loader and its output schema. The mapping is the inverse of @nifrajs/web's `filePathToPatterns`:
+ * `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional, `/` → `index`. The
+ * framework (→ file extension) comes from the project's `clientModule`.
  *
  * Page stubs are emitted for the JSX family (react/preact/solid - one shared, verified shape) and
  * for vanilla (a zero-runtime `html` page carrying the golden island pattern); for vue/svelte we
- * return the correct PATH + the route-module contract and point at `nifra_example` for the body,
- * rather than hand-writing an SFC we can't typecheck here.
+ * return the correct PATHS, the backend half and the route contract, and point at `nifra_example` for
+ * the page body, rather than hand-writing an SFC we can't typecheck here.
  */
 export type Framework = "react" | "preact" | "solid" | "vue" | "svelte" | "vanilla";
 /** A scaffold flavour on top of the framework. `default` is the plain page stub; `stateful` only
@@ -20,22 +21,34 @@ export declare function frameworkFromClientModule(clientModule: string | undefin
 /** Map a URL path to its `routes/` file path (relative to `routes/`, without extension prefix dir).
  * `/` → `index`; `/users/:id` → `users/[id]`; `/blog/*slug` → `blog/[...slug]`. */
 export declare function routePathToFile(urlPath: string, ext: string): string;
+/** `routes/users/[id].tsx` → `routes/users/[id].backend.ts`. */
+export declare const backendFileOf: (file: string) => string;
 export interface ScaffoldResult {
+    /** The page file. */
     readonly file: string;
+    /** The page stub, when there is a verified one for the framework. */
     readonly content?: string;
+    /** The page's backend half - framework-independent, so always present. */
+    readonly backend: {
+        readonly file: string;
+        readonly content: string;
+    };
     readonly note: string;
 }
 export interface ScaffoldWriteResult extends ScaffoldResult {
     readonly written: boolean;
     readonly reason?: string;
 }
-/** Scaffold a page route for `urlPath` under the project's `framework`. Returns the correct file path
- * always; a ready-to-write stub for the JSX family, contract guidance otherwise. */
+/** Scaffold a page route for `urlPath` under the project's `framework`. Returns the correct file paths
+ * and the backend half always; a ready-to-write page stub for the JSX family and vanilla, contract
+ * guidance otherwise. */
 export declare function scaffoldRoute(urlPath: string, framework: Framework, variant?: ScaffoldVariant): ScaffoldResult;
-/** Write a scaffolded route stub when the framework has a verified ready-to-write body. The write is
- * intentionally conservative: it refuses non-JSX stubs (where we only return contract guidance) and
- * uses `wx`, so an agent cannot overwrite user work by accident. */
+/** Write a scaffolded route pair when the framework has a verified ready-to-write page body. The write
+ * is intentionally conservative: it refuses frameworks where we only return contract guidance (a
+ * backend half alone is a build error), refuses when either file exists, and uses `wx`, so an agent
+ * cannot overwrite user work by accident. It then generates the route's `./+types` module, so both
+ * halves typecheck at once. */
 export declare function writeScaffoldRoute(cwd: string, urlPath: string, framework: Framework, variant?: ScaffoldVariant): Promise<ScaffoldWriteResult>;
-/** Render the tool result as markdown - the file path, the stub (if any), and the contract note. */
+/** Render the tool result as markdown - the file paths, the stubs (if any), and the contract note. */
 export declare function renderScaffold(urlPath: string, framework: Framework, variant?: ScaffoldVariant): string;
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEnF;;;yFAGyF;AACzF,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,CAAA;AAWpD,sGAAsG;AACtG,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAGrF;AAkCD;mFACmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAWpE;AAiKD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;oFACoF;AACpF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,cAAc,CA+BhB;AA2CD;;oEAEoE;AACpE,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAsB9B;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,MAAM,CASR"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEnF;;;yFAGyF;AACzF,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,CAAA;AAWpD,sGAAsG;AACtG,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAGrF;AAwCD;mFACmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAWpE;AAuBD,gEAAgE;AAChE,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAAkD,CAAA;AAwJ/F,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;yBAEyB;AACzB,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,cAAc,CAuChB;AA2CD;;;;+BAI+B;AAC/B,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAmC9B;AAED,sGAAsG;AACtG,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,eAA2B,GACnC,MAAM,CAUR"}

package/dist/scaffold.js

@@ -1,16 +1,18 @@
 /**
- * `nifra_scaffold` - turn a URL path into the correct `routes/` file (the convention an agent most often
- * gets wrong) + a minimal, contract-correct stub. The mapping is the inverse of @nifrajs/web's
- * `filePathToPatterns`: `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional,
- * `/` → `index`. The framework (→ file extension) comes from the project's `clientModule`.
+ * `nifra_scaffold` - turn a URL path into the correct `routes/` files (the convention an agent most often
+ * gets wrong) + a minimal, contract-correct route pair: the page, and its `.backend.ts` half holding the
+ * loader and its output schema. The mapping is the inverse of @nifrajs/web's `filePathToPatterns`:
+ * `:id`/`[id]` → `[id]`, `*rest`/`[...rest]` → `[...rest]`, `[[lang]]` optional, `/` → `index`. The
+ * framework (→ file extension) comes from the project's `clientModule`.
  *
  * Page stubs are emitted for the JSX family (react/preact/solid - one shared, verified shape) and
  * for vanilla (a zero-runtime `html` page carrying the golden island pattern); for vue/svelte we
- * return the correct PATH + the route-module contract and point at `nifra_example` for the body,
- * rather than hand-writing an SFC we can't typecheck here.
+ * return the correct PATHS, the backend half and the route contract, and point at `nifra_example` for
+ * the page body, rather than hand-writing an SFC we can't typecheck here.
  */
 import { lstat, mkdir, realpath, writeFile } from "node:fs/promises";
-import { dirname, resolve, sep } from "node:path";
+import { basename, dirname, resolve, sep } from "node:path";
+import { paramConstraint } from "@nifrajs/core/pattern";
 const EXT = {
     react: "tsx",
     preact: "tsx",
@@ -40,6 +42,10 @@ function assertSafeRouteSegment(segment, urlPath) {
     if (segment === "." || segment === ".." || segment.includes("\0") || segment.includes("\\")) {
         throw new Error(`invalid route segment in ${JSON.stringify(urlPath)}: ${JSON.stringify(segment)}`);
     }
+    const brace = segment.indexOf("{");
+    if (segment.startsWith(":") && brace > 0 && paramConstraint(segment.slice(brace)) !== undefined) {
+        throw new Error(`a param constraint cannot be written in a route file name: ${JSON.stringify(segment)} in ${JSON.stringify(urlPath)}. Scaffold the page without it and check the value in the route's loader.`);
+    }
     const fileSegment = segmentToFile(segment);
     if (fileSegment === "." ||
         fileSegment === ".." ||
@@ -67,22 +73,58 @@ export function routePathToFile(urlPath, ext) {
     }
     return `routes/${segments.map(segmentToFile).join("/")}.${ext}`;
 }
-const ROUTE_CONTRACT = `A route module may export:
-- \`export default function Page(props: { data: LoaderData<typeof loader> }) { … }\` - the page component.
-- \`export async function loader({ params, request, api }: LoaderArgs<typeof backend>) { … }\` - server-only; data for SSR. Reach the backend via \`api\` (typed) / DB via the backend, NEVER a top-level server-only import.
-- \`export async function action({ request, api }: ActionArgs<typeof backend>) { … }\` - server-only; handles the form POST.
-- \`export const meta = { title, meta:[…] }\` - head tags.
-Path params are typed on \`params\`.`;
-function jsxStub(file, params) {
-    const paramsNote = params.length > 0 ? `params.${params.join(", params.")}` : "no path params on this route";
-    const loaderLine = params.length > 0
-        ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* fetch by ${params[0]} */ } }`
-        : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`;
-    return `// ${file} - server-only loader/action allowed; never top-level-import server-only code (DB/secrets).
-// Available here: ${paramsNote}. Fetch data in a loader via the typed \`api\`; see nifra_example("loader").
-${loaderLine}
-export default function Page() {
-  return <main>TODO: ${file}</main>
+const ROUTE_CONTRACT = `A route is two files:
+- The page, \`routes/x.<ext>\` - ships to the browser: \`export default function Page({ data }: Route.ComponentProps)\` and \`export const meta = { title, meta: […] }\`. It never imports backend code.
+- Its backend half, \`routes/x.backend.ts\` - never reaches the browser: \`export const loaderOutput = t.object({…})\` with \`export async function loader({ params, api }: Route.LoaderArgs)\` (data for SSR - only what the schema declares is sent), \`actionOutput\` with \`action\` (the form POST), and \`hydrate\`, \`islandScripts\`, \`revalidate\`, \`middleware\`. Reach the backend through the typed \`api\`.
+Both import \`type { Route } from "./+types/<name>"\`, which \`nifra dev\`, \`nifra build\`, \`nifra check\` and \`nifra types\` generate. Path params are typed on \`params\`.`;
+/** Param names a route file declares, for the stubs. */
+function paramsOf(file) {
+    const out = [];
+    for (const m of file.matchAll(/(\[)?\[(?:\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\]/g))
+        out.push({ name: m[2], optional: m[1] !== undefined });
+    return out;
+}
+/** `./+types/<name>` for a route file: the generated module both halves import `Route` from. */
+const typesOf = (file) => `./+types/${basename(file).replace(/\.[^.]+$/, "")}`;
+/** `routes/users/[id].tsx` → `routes/users/[id].backend.ts`. */
+export const backendFileOf = (file) => file.replace(/\.[^./]+$/, ".backend.ts");
+/** The page's backend half: its loader, and the schema that bounds what the loader sends. */
+function backendStub(file, params, vanilla) {
+    const last = params.at(-1);
+    const loader = last === undefined
+        ? `export async function loader(_args: Route.LoaderArgs) {
+  // Load through the typed backend client, \`api\` in these args; see nifra_example("loader").
+  return { title: "TODO" }
+}`
+        : `export async function loader({ params }: Route.LoaderArgs) {
+  // Load by params.${last.name} through the typed backend client, \`api\` in these args; see nifra_example("loader").
+  return { title: \`TODO: \${params.${last.name}${last.optional ? ' ?? ""' : ""}}\` }
+}`;
+    const vanillaExports = vanilla
+        ? `
+
+// No client framework to hydrate with - vanilla routes are documents, not hydrated apps.
+export const hydrate = false
+
+// The built URL of each island enhancer this page renders a marker for (./<name>.client.ts).
+// export const islandScripts = []`
+        : "";
+    return `// ${backendFileOf(file)} - the server half of ${file}; it never reaches the browser.
+import { t } from "@nifrajs/schema"
+import type { Route } from "${typesOf(file)}"
+
+// Only what this schema declares is sent to the page.
+export const loaderOutput = t.object({ title: t.string() })
+
+${loader}${vanillaExports}
+`;
+}
+function jsxStub(file) {
+    return `// ${file} - the page; it ships to the browser. Its data comes from ${basename(backendFileOf(file))}.
+import type { Route } from "${typesOf(file)}"
+
+export default function Page({ data }: Route.ComponentProps) {
+  return <main>{data.title}</main>
 }
 `;
 }
@@ -93,27 +135,20 @@ export default function Page() {
  * returns its cleanup (the one thing NF-C020 checks), wired through `mountIslands`. Interactivity is
  * added by uncommenting and writing the companion `<name>.client.ts`, never by turning on hydration.
  */
-function vanillaStub(file, params) {
-    const paramsNote = params.length > 0 ? `params.${params.join(", params.")}` : "no path params on this route";
-    const loaderLine = params.length > 0
-        ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* fetch by ${params[0]} */ } }`
-        : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`;
-    return `// ${file} - @nifrajs/web-vanilla route. Server-rendered HTML, ZERO framework runtime.
-// Available here: ${paramsNote}. Fetch data in a loader via the typed \`api\`; see nifra_example("loader").
+function vanillaStub(file) {
+    return `// ${file} - @nifrajs/web-vanilla page. Server-rendered HTML, ZERO framework runtime; its data,
+// and \`hydrate = false\`, live in ${basename(backendFileOf(file))}.
 import { html } from "@nifrajs/web-vanilla"
+import type { Route } from "${typesOf(file)}"
 
-// No client framework to hydrate with - vanilla routes are documents, not hydrated apps.
-export const hydrate = false
-
-${loaderLine}
-
-export default function Page() {
-  return html\`<main><h1>TODO: ${file}</h1></main>\`
+export default function Page({ data }: Route.ComponentProps) {
+  return html\`<main><h1>\${data.title}</h1></main>\`
 }
 
 // --- Add interactivity the AI-safe way (islands), NOT hydration ---------------------------------
 // 1. Render a marker in the page above:  html\`<nifra-island data-id="counter" data-props=\${JSON.stringify({ start: 0 })}></nifra-island>\`
-// 2. Wire the route to its enhancer bundle:  export const islandScripts = [/* built URL of ./counter.client.ts */]
+// 2. Wire the route to its enhancer bundle, in ${basename(backendFileOf(file))}:
+//    export const islandScripts = [/* built URL of ./counter.client.ts */]
 // 3. Write ./counter.client.ts as an imperative enhancer that ALWAYS returns its cleanup:
 //
 //    import { defineIsland, mountIslands } from "@nifrajs/web/islands"
@@ -141,31 +176,21 @@ export default function Page() {
  * The page body is a valid, typecheckable static document; interactivity is added by writing the
  * companion client shown, never by turning on hydration.
  */
-function nanoStub(file, params) {
-    const paramsNote = params.length > 0 ? `params.${params.join(", params.")}` : "no path params on this route";
-    const loaderLine = params.length > 0
-        ? `// export async function loader({ params, api }: LoaderArgs<typeof backend>) { return { /* seed by ${params[0]} */ } }`
-        : `// export async function loader({ api }: LoaderArgs<typeof backend>) { return {} }`;
-    return `// ${file} - @nifrajs/web-vanilla route + a nano island (explicit reactivity, zero VDOM).
-// Available here: ${paramsNote}. Seed data in a loader via the typed \`api\`; see nifra_example("loader").
+function nanoStub(file) {
+    return `// ${file} - @nifrajs/web-vanilla page + a nano island (explicit reactivity, zero VDOM). The
+// document is static and the nano client below owns all interactivity; \`hydrate = false\` and the
+// island's \`islandScripts\` URL live in ${basename(backendFileOf(file))}.
 import { html } from "@nifrajs/web-vanilla"
+import type { Route } from "${typesOf(file)}"
 
-// The document is static; the nano client below owns all interactivity. No hydration.
-export const hydrate = false
-
-${loaderLine}
-
-export default function Page() {
+export default function Page({ data }: Route.ComponentProps) {
   // The island marker: data-props is the initial state the client reads on mount.
   return html\`<main>
-    <h1>Todos</h1>
+    <h1>\${data.title}</h1>
     <nifra-island data-id="todos" data-props=\${JSON.stringify({ items: [] })}></nifra-island>
   </main>\`
 }
 
-// Wire the route to the built URL of ./todos.client.ts (the nano enhancer below).
-// export const islandScripts = [/* built URL of ./todos.client.ts */]
-
 // --- ./todos.client.ts - the golden nano pattern (write this as a companion file) -----------------
 //
 //   import { defineIsland, mountIslands } from "@nifrajs/web/islands"
@@ -208,45 +233,47 @@ export default function Page() {
 // has the full cookbook; \`nifra check\` runs NF-C021/C022/C023 over the client you write.
 `;
 }
-/** Param names a route file declares, for the stub's notes. */
-function paramsOf(file) {
-    const out = [];
-    for (const m of file.matchAll(/\[(?:\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\]/g))
-        out.push(m[1]);
-    return out;
-}
-/** Scaffold a page route for `urlPath` under the project's `framework`. Returns the correct file path
- * always; a ready-to-write stub for the JSX family, contract guidance otherwise. */
+/** Scaffold a page route for `urlPath` under the project's `framework`. Returns the correct file paths
+ * and the backend half always; a ready-to-write page stub for the JSX family and vanilla, contract
+ * guidance otherwise. */
 export function scaffoldRoute(urlPath, framework, variant = "default") {
     const ext = EXT[framework];
     const file = routePathToFile(urlPath, ext);
     const params = paramsOf(file);
+    const backend = {
+        file: backendFileOf(file),
+        content: backendStub(file, params, framework === "vanilla"),
+    };
     // `stateful` is vanilla-only: it swaps the static island stub for the nano golden pattern. Asking
     // for it on a JSX/SFC framework is a no-op on the flavour (those lanes have their own reactivity).
     if (framework === "vanilla" && variant === "stateful") {
         return {
             file,
-            content: nanoStub(file, params),
-            note: `Create ${file} as a zero-runtime @nifrajs/web-vanilla route with a nano island. ${ROUTE_CONTRACT}\nThe stub embeds the golden nano client (signal + computed(fn,[deps]) + keyed bindList + collected cleanups); write it as the companion .client.ts. \`nifra check\` runs NF-C021/C022/C023 over it; nifra_docs("nano") is the full cookbook.`,
+            content: nanoStub(file),
+            backend,
+            note: `Create ${file} and ${backend.file} as a zero-runtime @nifrajs/web-vanilla route with a nano island. ${ROUTE_CONTRACT}\nThe stub embeds the golden nano client (signal + computed(fn,[deps]) + keyed bindList + collected cleanups); write it as the companion .client.ts. \`nifra check\` runs NF-C021/C022/C023 over it; nifra_docs("nano") is the full cookbook.`,
         };
     }
     if (framework === "react" || framework === "preact" || framework === "solid") {
         return {
             file,
-            content: jsxStub(file, params),
-            note: `Create ${file}. ${ROUTE_CONTRACT}\nIf the rendered page misbehaves (hydration warning, a value that stops updating), call nifra_frontend { adapter: "${framework}" } for the cause + fix.`,
+            content: jsxStub(file),
+            backend,
+            note: `Create ${file} and ${backend.file}. ${ROUTE_CONTRACT}\nIf the rendered page misbehaves (hydration warning, a value that stops updating), call nifra_frontend { adapter: "${framework}" } for the cause + fix.`,
         };
     }
     if (framework === "vanilla") {
         return {
             file,
-            content: vanillaStub(file, params),
-            note: `Create ${file} as a zero-runtime @nifrajs/web-vanilla route. ${ROUTE_CONTRACT}\nInteractivity comes from islands (imperative enhancers), never hydration - the stub embeds the golden pattern; nifra_example("islands") has the full cookbook. For explicit local state (a list a human edits), scaffold with variant "stateful" to get the nano pattern instead.`,
+            content: vanillaStub(file),
+            backend,
+            note: `Create ${file} and ${backend.file} as a zero-runtime @nifrajs/web-vanilla route. ${ROUTE_CONTRACT}\nInteractivity comes from islands (imperative enhancers), never hydration - the stub embeds the golden pattern; nifra_example("islands") has the full cookbook. For explicit local state (a list a human edits), scaffold with variant "stateful" to get the nano pattern instead.`,
         };
     }
     return {
         file,
-        note: `Create ${file} as a ${framework} route module. ${ROUTE_CONTRACT}\nFor the ${framework} page body, call nifra_example (it ships verified ${framework} snippets) rather than guessing the SFC shape. If a value stops updating the template, call nifra_frontend { adapter: "${framework}" } for the ${framework} reactivity-loss fix.`,
+        backend,
+        note: `Create ${file} as a ${framework} route module, and ${backend.file} from the stub below. ${ROUTE_CONTRACT}\nFor the ${framework} page body, call nifra_example (it ships verified ${framework} snippets) rather than guessing the SFC shape. If a value stops updating the template, call nifra_frontend { adapter: "${framework}" } for the ${framework} reactivity-loss fix.`,
     };
 }
 function resolveInsideRoutes(cwd, relativeFile) {
@@ -289,9 +316,11 @@ async function assertNoSymlinkedAncestors(root, target) {
         current = dirname(current);
     }
 }
-/** Write a scaffolded route stub when the framework has a verified ready-to-write body. The write is
- * intentionally conservative: it refuses non-JSX stubs (where we only return contract guidance) and
- * uses `wx`, so an agent cannot overwrite user work by accident. */
+/** Write a scaffolded route pair when the framework has a verified ready-to-write page body. The write
+ * is intentionally conservative: it refuses frameworks where we only return contract guidance (a
+ * backend half alone is a build error), refuses when either file exists, and uses `wx`, so an agent
+ * cannot overwrite user work by accident. It then generates the route's `./+types` module, so both
+ * halves typecheck at once. */
 export async function writeScaffoldRoute(cwd, urlPath, framework, variant = "default") {
     const result = scaffoldRoute(urlPath, framework, variant);
     if (result.content === undefined) {
@@ -301,22 +330,37 @@ export async function writeScaffoldRoute(cwd, urlPath, framework, variant = "def
             reason: "no verified ready-to-write stub for this framework; use nifra_example for the body",
         };
     }
-    const target = resolveInsideRoutes(cwd, result.file);
-    await assertNoSymlinkedAncestors(cwd, target);
-    await mkdir(dirname(target), { recursive: true });
-    await assertNoSymlinkedAncestors(cwd, target);
-    try {
-        await writeFile(target, result.content, { flag: "wx" });
+    const files = [
+        { file: result.file, content: result.content },
+        { file: result.backend.file, content: result.backend.content },
+    ];
+    const targets = files.map(({ file }) => resolveInsideRoutes(cwd, file));
+    for (const target of targets)
+        await assertNoSymlinkedAncestors(cwd, target);
+    for (const [i, target] of targets.entries()) {
+        if ((await lstat(target).catch(() => undefined)) !== undefined) {
+            return { ...result, written: false, reason: `file already exists: ${files[i]?.file}` };
+        }
     }
-    catch (err) {
-        if (err && typeof err === "object" && err.code === "EEXIST") {
-            return { ...result, written: false, reason: `file already exists: ${result.file}` };
+    await mkdir(dirname(targets[0]), { recursive: true });
+    for (const target of targets)
+        await assertNoSymlinkedAncestors(cwd, target);
+    for (const [i, target] of targets.entries()) {
+        try {
+            await writeFile(target, files[i]?.content ?? "", { flag: "wx" });
+        }
+        catch (err) {
+            if (err && typeof err === "object" && err.code === "EEXIST") {
+                return { ...result, written: false, reason: `file already exists: ${files[i]?.file}` };
+            }
+            throw err;
         }
-        throw err;
     }
+    const { refreshRouteTypes } = await import("./route-types.js");
+    refreshRouteTypes(cwd, () => { });
     return { ...result, written: true };
 }
-/** Render the tool result as markdown - the file path, the stub (if any), and the contract note. */
+/** Render the tool result as markdown - the file paths, the stubs (if any), and the contract note. */
 export function renderScaffold(urlPath, framework, variant = "default") {
     let r;
     try {
@@ -325,7 +369,8 @@ export function renderScaffold(urlPath, framework, variant = "default") {
     catch (err) {
         return `Cannot scaffold ${JSON.stringify(urlPath)}: ${err instanceof Error ? err.message : String(err)}`;
     }
-    const stub = r.content ? `\n\n\`\`\`${EXT[framework]}\n${r.content}\`\`\`` : "";
-    return `# Scaffold route \`${urlPath}\` (${framework})\n\n**File:** \`${r.file}\`\n\n${r.note}${stub}`;
+    const page = r.content ? `\n\n\`${r.file}\`:\n\n\`\`\`${EXT[framework]}\n${r.content}\`\`\`` : "";
+    const backend = `\n\n\`${r.backend.file}\`:\n\n\`\`\`ts\n${r.backend.content}\`\`\``;
+    return `# Scaffold route \`${urlPath}\` (${framework})\n\n**Files:** \`${r.file}\` + \`${r.backend.file}\`\n\n${r.note}${page}${backend}`;
 }
 //# sourceMappingURL=scaffold.js.map