@nifrajs/cli 3.3.0 → 4.0.0

package/dist/rules/typescript.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic } from "../diagnostics.js";
+import { type TypeScriptApi, type TypeScriptSession } from "../internal/typescript-import.js";
+import type { RuleContext } from "./index.js";
+interface RuleTypeScriptLoad {
+    readonly compiler: TypeScriptApi | undefined;
+    readonly session: TypeScriptSession | undefined;
+    readonly diagnostics: readonly Diagnostic[] | undefined;
+}
+/** Retain a direct rule-registry session until the whole registry run has completed. */
+export declare function retainRuleTypeScript(ctx: RuleContext): void;
+/** Release a direct rule-registry session and terminate its TypeScript 7 worker when unused. */
+export declare function releaseRuleTypeScript(ctx: RuleContext): Promise<void>;
+/** Keep every AST-backed rule on the same project compiler session. */
+export declare function loadRuleTypeScript(ctx: RuleContext): Promise<RuleTypeScriptLoad>;
+export {};
+//# sourceMappingURL=typescript.d.ts.map

package/dist/rules/typescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../src/rules/typescript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAEvB,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,CAAA;CACxD;AAoBD,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAG3D;AAED,gGAAgG;AAChG,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3E;AAED,uEAAuE;AACvE,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqBtF"}

package/dist/rules/typescript.js

@@ -0,0 +1,59 @@
+import { loadProjectTypeScript, unsupportedTypeScriptDiagnostic, } from "../internal/typescript-import.js";
+const sessionCache = new WeakMap();
+function cachedLoad(ctx) {
+    const cached = sessionCache.get(ctx.sources);
+    if (cached !== undefined)
+        return cached;
+    const entry = {
+        pending: loadProjectTypeScript(ctx.root, undefined, ctx.sources),
+        leases: 0,
+    };
+    sessionCache.set(ctx.sources, entry);
+    return entry;
+}
+/** Retain a direct rule-registry session until the whole registry run has completed. */
+export function retainRuleTypeScript(ctx) {
+    const entry = cachedLoad(ctx);
+    entry.leases += 1;
+}
+/** Release a direct rule-registry session and terminate its TypeScript 7 worker when unused. */
+export async function releaseRuleTypeScript(ctx) {
+    const entry = sessionCache.get(ctx.sources);
+    if (entry === undefined)
+        return;
+    entry.leases = Math.max(0, entry.leases - 1);
+    if (entry.leases !== 0)
+        return;
+    sessionCache.delete(ctx.sources);
+    try {
+        const loaded = await entry.pending;
+        await loaded.session?.close();
+    }
+    catch {
+        // The scanner that consumed the same pending load owns the diagnostic for load failures.
+    }
+}
+/** Keep every AST-backed rule on the same project compiler session. */
+export async function loadRuleTypeScript(ctx) {
+    if (ctx.project.check.unsupportedTypeScriptVersion !== undefined) {
+        // The check-wide loader already supplied the single structured failure diagnostic.
+        return { compiler: undefined, session: undefined, diagnostics: [] };
+    }
+    if (ctx.typescriptSession !== undefined) {
+        return {
+            compiler: ctx.typescriptSession.compiler,
+            session: ctx.typescriptSession,
+            diagnostics: undefined,
+        };
+    }
+    const loaded = await cachedLoad(ctx).pending;
+    if (loaded.unsupported !== undefined) {
+        return {
+            compiler: undefined,
+            session: undefined,
+            diagnostics: [unsupportedTypeScriptDiagnostic(loaded.unsupported.version)],
+        };
+    }
+    return { compiler: loaded.compiler, session: loaded.session, diagnostics: undefined };
+}
+//# sourceMappingURL=typescript.js.map

package/dist/rules/typescript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript.js","sourceRoot":"","sources":["../../src/rules/typescript.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EAGrB,+BAA+B,GAChC,MAAM,kCAAkC,CAAA;AAczC,MAAM,YAAY,GAAG,IAAI,OAAO,EAA6C,CAAA;AAE7E,SAAS,UAAU,CAAC,GAAgB;IAClC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC5C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IACvC,MAAM,KAAK,GAAsB;QAC/B,OAAO,EAAE,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC;QAChE,MAAM,EAAE,CAAC;KACV,CAAA;IACD,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACpC,OAAO,KAAK,CAAA;AACd,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,oBAAoB,CAAC,GAAgB;IACnD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAC7B,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;AACnB,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAgB;IAC1D,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC3C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAM;IAC/B,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAC9B,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAA;QAClC,MAAM,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,yFAAyF;IAC3F,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAgB;IACvD,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,4BAA4B,KAAK,SAAS,EAAE,CAAC;QACjE,mFAAmF;QACnF,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;IACrE,CAAC;IACD,IAAI,GAAG,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO;YACL,QAAQ,EAAE,GAAG,CAAC,iBAAiB,CAAC,QAAQ;YACxC,OAAO,EAAE,GAAG,CAAC,iBAAiB;YAC9B,WAAW,EAAE,SAAS;SACvB,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAA;IAC5C,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO;YACL,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,SAAS;YAClB,WAAW,EAAE,CAAC,+BAA+B,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;SAC3E,CAAA;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,CAAA;AACvF,CAAC"}

package/dist/rules/zones.d.ts

@@ -0,0 +1,17 @@
+import { type Classification, type ZoneClassifier } from "@nifrajs/web/zones";
+import type { CheckRule, RuleContext } from "./index.js";
+interface ZonedFile {
+    readonly file: string;
+    readonly app: string;
+    readonly classification: Classification;
+}
+/** Every scanned source file that belongs to an app, classified once per app classifier. */
+export declare function zonedFiles(ctx: RuleContext): {
+    readonly files: readonly ZonedFile[];
+    readonly classifierFor: (app: string) => ZoneClassifier;
+};
+export declare const zoneImportRule: CheckRule;
+export declare const privateEnvRule: CheckRule;
+export declare const zoneRules: readonly CheckRule[];
+export {};
+//# sourceMappingURL=zones.d.ts.map

package/dist/rules/zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.d.ts","sourceRoot":"","sources":["../../src/rules/zones.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,KAAK,cAAc,EAMnB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAA;AAK3B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAgBxD,UAAU,SAAS;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;CACxC;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,cAAc,CAAA;CACxD,CAsBA;AA4BD,eAAO,MAAM,cAAc,EAAE,SAyC5B,CAAA;AAgBD,eAAO,MAAM,cAAc,EAAE,SAmC5B,CAAA;AAED,eAAO,MAAM,SAAS,sBAAkD,CAAA"}

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":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC/D,OAAO,EAEL,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GAEjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAC7D,OAAO,EAAmB,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAG9D,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;AACxE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC,CAAA;AACxD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC,CAAA;AAC1D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAA;AACrD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAA;AACtE,MAAM,SAAS,GAAG,oCAAoC,CAAA;AAEtD,gGAAgG;AAChG,SAAS,KAAK,CAAC,IAAY;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;IACtF,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7D,CAAC;AAQD,4FAA4F;AAC5F,MAAM,UAAU,UAAU,CAAC,GAAgB;IAIzC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAA;IACrD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;QACpD,IAAI,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;YACnC,UAAU,GAAG,oBAAoB,CAAC;gBAChC,OAAO;gBACP,cAAc,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;aACtD,CAAC,CAAA;YACF,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;IACD,MAAM,KAAK,GAAgB,EAAE,CAAA;IAC7B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAQ;QACnC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;QACvB,IAAI,GAAG,KAAK,SAAS;YAAE,SAAQ;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;IAC9F,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAA;AACjC,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,IAAY,EAAU,EAAE;IACpC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED;uGACuG;AACvG,SAAS,OAAO,CAAC,IAAY,EAAE,IAAY;IACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAClE,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;AAC9D,CAAC;AAED,sGAAsG;AACtG,SAAS,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,SAAiB;IACpE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACjF,IAAI,CAAC;QACH,0FAA0F;QAC1F,OAAO,GAAG,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,mBAAmB;IAC1B,KAAK,CAAC,IAAI,CAAC,GAAG;QACZ,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAChD,MAAM,QAAQ,GAAiB,EAAE,CAAA;QACjC,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;YACxD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;gBAAE,SAAQ;YAC3F,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACtC,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAQ;YACnC,KAAK,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC7D,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;gBACzD,IAAI,MAAM,KAAK,SAAS;oBAAE,SAAQ;gBAClC,MAAM,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;gBAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;gBAC5C,IAAI,OAAe,CAAA;gBACnB,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO;oBAAE,OAAO,GAAG,GAAG,IAAI,YAAY,UAAU,KAAK,EAAE,CAAC,MAAM,EAAE,CAAA;qBAC3E,IACH,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;oBAChD,iFAAiF;oBACjF,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EACvF,CAAC;oBACD,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;gBACnE,CAAC;;oBAAM,SAAQ;gBACf,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;oBACT,IAAI,EAAE,SAAS;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI;oBACJ,IAAI;oBACJ,OAAO;oBACP,QAAQ,EAAE,CAAC,WAAW,SAAS,EAAE,EAAE,cAAc,IAAI,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC;oBACpF,MAAM,EAAE,aAAa;iBACtB,CAAC,CACH,CAAA;YACH,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,CAClB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CACrF,CAAA;IACH,CAAC;CACF,CAAA;AAED,MAAM,aAAa,GACjB,gGAAgG,CAAA;AAElG,qGAAqG;AACrG,SAAS,YAAY,CAAC,IAAY,EAAE,GAAW;IAC7C,KAAK,MAAM,MAAM,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;QACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC/B,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;QAC3E,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,SAAS,CAAA;IAC9D,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,0CAA0C;IACjD,KAAK,CAAC,IAAI,CAAC,GAAG;QACZ,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;QAC1C,MAAM,QAAQ,GAAiB,EAAE,CAAA;QACjC,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,KAAK,EAAE,CAAC;YAClD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACpD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACtC,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAQ;YACnC,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;gBACpC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;YAC3B,CAAC;YACD,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;YACpD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAQ;YAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;YAC5B,MAAM,IAAI,GAAG,0CAA0C,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;YACxE,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YAC7D,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;gBACT,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,OAAO;gBACjB,IAAI;gBACJ,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;gBAC7E,OAAO,EAAE,GAAG,IAAI,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;gBACrD,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC;gBAC9C,MAAM,EAAE,aAAa;aACtB,CAAC,CACH,CAAA;QACH,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAA"}

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;AAWD;mFACmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAUpE;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;AA0CD;;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"}