@mauroandre/velojs 0.0.59 → 0.0.60

package/README.md

@@ -170,6 +170,7 @@ veloPlugin({
     serverInit: "server.tsx",   // default
     clientInit: "client.tsx",   // default
     hostname: "127.0.0.1",      // bind interface, dev and production (the HOST env wins)
+    serverOnly: ["server/**"],  // declares server-only modules to the leak diagnostic
 });
 ```
 
@@ -1780,13 +1781,15 @@ Callbacks queue until the server starts. If called after startup, executes immed
 
 ## Vite Plugin Architecture
 
-`veloPlugin()` returns 6 plugins:
+`veloPlugin()` returns 8 plugins:
 
 | Plugin | Purpose |
 |--------|---------|
 | `velo:config` | Build config (client/server modes, aliases, defines) |
 | `velo:transform` | AST transforms (metadata injection, action stubs, loader removal) |
 | `velo:static-url` | Rewrites CSS `url(/path)` to `url(STATIC_BASE_URL/path)` at build time |
+| `velo:graph` | Generates `.velojs/graph.json` (route tree + dependency graph) on build and dev |
+| `velo:leak-diagnostic` | Prints the server→client leak report on build and dev (read-only) |
 | `@preact/preset-vite` | Preact JSX support |
 | `@hono/vite-dev-server` | Dev server with SSR |
 | `velo:ws-bridge` | Exposes Vite's HTTP server for WebSocket handlers in dev mode |
@@ -1829,6 +1832,55 @@ velojs build
 
 When `routes.tsx` changes, the plugin rebuilds the fullPath map and triggers a full page reload (not partial HMR).
 
+### Server→Client Leak Diagnostic
+
+What ships to the browser is checked on every `velojs build` (including `build --static`) and `velojs dev`: the terminal prints a report of every server module the client entry can reach — a leak of the server→client boundary.
+
+A **server module** is a module that touches a Node builtin in its own code — static import, re-export or `await import()`, by any import path — or that matches a `serverOnly` pattern declared in the plugin config.
+A **leak** is a server module reachable from what the browser loads, following static and dynamic imports.
+The analysis reads the code *after* the client transforms — the same ones the build applies (loaders, actions, streams, sockets, middlewares and endpoints stripped, orphaned imports pruned) — so the normal VeloJS shape (a `loader` importing server code) is silent by construction: what the framework removes never travels.
+
+Each leak in the report brings:
+
+- the leaked module and what qualifies it as server (the Node builtin touched, or the `serverOnly` pattern matched);
+- the full import chain from the client entry to it — file and line at every link;
+- the **entry point** — the import where the chain pulls the first server module, marked `entry point (cut here)`: exactly where the cut happens.
+
+```text
+[velojs] server->client leak analysis: 1 leak(s) in what ships to the client.
+
+1) app/server-side.ts
+   server because: imports Node builtin "node:fs"
+   import chain from the client entry:
+     virtual:velo/client-entry (generated) -> app/routes.tsx
+     app/routes.tsx:3 -> app/pages/Home.tsx
+     app/pages/Home.tsx:6 -> app/server-side.ts  <- entry point (cut here)
+
+The report is read-only: nothing is blocked or rewritten; the cut is yours.
+```
+
+Two chains to the same module are two items — every cut point shows up — and the list is stable between runs.
+When there is nothing to report, one line says so (`0 leaks — what ships to the client is clean.`), so silence is distinguishable from the analysis not running.
+In dev the report appears when the server comes up (no navigation needed) and is re-emitted whenever a file change shifts what travels to the client — an import added stitches a new path into the next report, an import removed takes the leak out of it.
+
+The report is the light, never the hand: nothing is blocked, rewritten, stubbed or moved, `await import()` included; the build finishes with success, the dev keeps serving, and the decision to cut any edge is entirely yours.
+
+#### Declaring server-only code: `serverOnly`
+
+A module that touches no Node builtin is invisible to the analysis — the framework does not guess your app's domain.
+Declare it:
+
+```typescript
+veloPlugin({
+    serverOnly: ["src/fsm/**", "server/**"],
+});
+```
+
+Patterns are globs (`*`, `**`, `?`) matched against the module's file path relative to the project root, always with `/` as separator.
+The declaration feeds the diagnostic only — nothing is blocked or altered because of it.
+
+**Limitation (craved):** server code that touches no Node builtin and matches no `serverOnly` pattern generates no item; that is what the declaration is for.
+
 ---
 
 ## Request Isolation
@@ -1986,6 +2038,7 @@ interface VeloConfig {
     clientInit?: string;     // default: "client.tsx"
     port?: number;           // default: 3000; the PORT env wins
     hostname?: string;       // bind interface, dev and production; the HOST env wins
+    serverOnly?: string[];   // glob patterns declaring server-only modules to the leak diagnostic
 }
 ```
 

package/agent/AGENTS.md

@@ -39,6 +39,27 @@ hard constraints, not style.
 
 Never pass a module id to `useLoader()` / `Loader()` yourself — the plugin injects it.
 
+## The server→client leak report
+
+`velojs build` (and `build --static`, `velojs dev`) prints a report of every **server module** the browser can reach — a module that touches a Node builtin in its own code (static import, re-export or `await import()`), or that matches a `serverOnly` pattern.
+The analysis reads the code **after** the client transforms (the table above describes what those remove), so a `loader`/`action_*`/`stream_*`/`socket_*`/`middlewares` importing server code where the framework strips it is silent by construction.
+
+What the warning means: the module named in the item reaches what ships to the browser; the chain lists every import from the client entry to it (file and line per link); `entry point (cut here)` marks the import where the chain pulls the first server module — that is where the cut happens.
+The report never blocks, rewrites, stubs or moves anything: the build finishes with success, the dev keeps serving, and cutting any edge is always your call.
+Two chains to the same module are two items — every cut point shows up.
+
+Code that touches **no** Node builtin is invisible to the analysis — the framework does not guess your app's domain. Declare it:
+
+```typescript
+veloPlugin({
+    serverOnly: ["src/fsm/**", "server/**"],
+});
+```
+
+Patterns are globs (`*`, `**`, `?`) matched against the module's file path relative to the project root, always with `/` as separator.
+The declaration feeds the diagnostic only — nothing is blocked or altered because of it.
+A server module with no builtin and no declaration generates no item: that limitation is craved, and the declaration is how you lift it.
+
 ## Sharing a layout's data with its children
 
 `Loader()` is the importable handle for a module's loader data; `useLoader()` is the

package/agent/skills/velojs-type-reference/SKILL.md

@@ -139,5 +139,6 @@ interface VeloConfig {
     clientInit?: string;     // default: "client.tsx"
     port?: number;           // default: 3000 (the PORT env always wins)
     hostname?: string;       // bind interface, dev and production; the HOST env wins
+    serverOnly?: string[];   // glob patterns declaring server-only modules to the leak diagnostic
 }
 ```

package/agent/skills/velojs-vite-plugin/SKILL.md

@@ -5,9 +5,9 @@ description: "The `veloPlugin` build pipeline: the 9 AST transforms that inject
 
 # Vite Plugin
 
-The `veloPlugin()` is the core of VeloJS. It's a single function that returns 6 Vite plugins working together to handle routing, SSR, code transforms, and more.
+The `veloPlugin()` is the core of VeloJS. It's a single function that returns 8 Vite plugins working together to handle routing, SSR, code transforms, and more.
 
-## The 7 plugins
+## The 8 plugins
 
 | Plugin | What it does |
 |--------|-------------|
@@ -15,6 +15,7 @@ The `veloPlugin()` is the core of VeloJS. It's a single function that returns 6
 | `velo:transform` | Performs AST transforms on your code (the most important plugin) |
 | `velo:static-url` | Rewrites CSS `url(/path)` to use `STATIC_BASE_URL` in production builds |
 | `velo:graph` | Generates `.velojs/graph.json` (route tree + dependency graph) on build and dev |
+| `velo:leak-diagnostic` | Prints the server→client leak report on build and dev (read-only) |
 | `@preact/preset-vite` | Adds Preact JSX support |
 | `@hono/vite-dev-server` | Runs the SSR dev server |
 | `velo:ws-bridge` | Exposes Vite's HTTP server for WebSocket handlers during development |
@@ -79,6 +80,54 @@ VeloJS uses Vite virtual modules to generate the server and client entry points
 
 You never import these directly — they're generated by the plugin.
 
+## The server→client leak diagnostic
+
+What ships to the browser is checked on every `velojs build` (including `build --static`) and `velojs dev`: the terminal prints a report of every server module the client entry can reach — a leak of the server→client boundary.
+
+A **server module** is a module that touches a Node builtin in its own code — static import, re-export or `await import()`, by any import path — or that matches a `serverOnly` pattern declared in the plugin config.
+A **leak** is a server module reachable from what the browser loads, following static and dynamic imports.
+The analysis reads the code *after* the client transforms above — loaders, actions, streams, sockets, middlewares and endpoints stripped, orphaned imports pruned — never the raw source, so a `loader` importing server code is silent by construction.
+
+Each leak in the report brings:
+
+- the leaked module and what qualifies it as server (the Node builtin touched, or the `serverOnly` pattern matched);
+- the full import chain from the client entry to it — file and line at every link;
+- the **entry point** — the import where the chain pulls the first server module, marked `entry point (cut here)`: exactly where the cut happens.
+
+```text
+[velojs] server->client leak analysis: 1 leak(s) in what ships to the client.
+
+1) app/server-side.ts
+   server because: imports Node builtin "node:fs"
+   import chain from the client entry:
+     virtual:velo/client-entry (generated) -> app/routes.tsx
+     app/routes.tsx:3 -> app/pages/Home.tsx
+     app/pages/Home.tsx:6 -> app/server-side.ts  <- entry point (cut here)
+
+The report is read-only: nothing is blocked or rewritten; the cut is yours.
+```
+
+Two chains to the same module are two items — every cut point shows up — and the list is stable between runs.
+When nothing leaks, one line says so (`0 leaks — what ships to the client is clean.`), so silence is distinguishable from the analysis not running.
+In dev the report appears when the server comes up (no navigation needed) and is re-emitted whenever a file change shifts what travels to the client.
+
+### Declaring server-only code: `serverOnly`
+
+A module that touches no Node builtin is invisible to the analysis — the framework does not guess your app's domain.
+Declare it:
+
+```typescript
+veloPlugin({
+    serverOnly: ["src/fsm/**", "server/**"],
+});
+```
+
+Patterns are globs (`*`, `**`, `?`) matched against the module's file path relative to the project root, always with `/` as separator.
+The declaration feeds the diagnostic only — nothing is blocked or altered because of it.
+
+**Limitation (craved):** server code that touches no Node builtin and matches no `serverOnly` pattern generates no item; that is what the declaration is for.
+The diagnostic is the light, never the hand: nothing is blocked, rewritten, stubbed or moved, `await import()` included; the build finishes with success and the dev keeps serving.
+
 ## Hot reload
 
 When you edit `routes.tsx`, the plugin detects the change, rebuilds the path map, and triggers a full page reload. Other file changes use Vite's standard HMR (hot module replacement).

package/dist/config.d.ts

@@ -40,5 +40,13 @@ export interface VeloConfig {
      * @hono/vite-dev-server, não os substituem.
      */
     devServerExclude?: (string | RegExp)[];
+    /**
+     * Padrões de glob (`*`, `**`, `?`) que declaram módulos só de servidor ao
+     * diagnóstico de vazamento server->client, casados contra o caminho do
+     * arquivo do módulo relativo à raiz do projeto, com `/` como separador
+     * (ex.: `serverOnly: ["src/fsm/**", "server/**"]`). Serve só ao
+     * diagnóstico — nada é bloqueado ou alterado por causa da declaração.
+     */
+    serverOnly?: string[];
 }
 export declare function defineConfig(config: VeloConfig): VeloConfig;

package/dist/leak-diagnostic.d.ts

@@ -0,0 +1,77 @@
+/** One import in the chain: `from` imports `to` at `line` (`null` = generated). */
+export interface LeakLink {
+    from: string;
+    line: number | null;
+    to: string;
+}
+export interface LeakItem {
+    /** Display path of the leaked server module. */
+    target: string;
+    /** Why it qualifies as a server module (English). */
+    qualifiers: string[];
+    /** Full import chain, client entry -> target, one link per import. */
+    chain: LeakLink[];
+    /** Index in `chain` of the entry-point link — the cut. */
+    entryIndex: number;
+}
+export interface LeakReport {
+    leaks: LeakItem[];
+    /** True when the enumeration stopped at its safety budget. */
+    truncated: boolean;
+    /** Stable fingerprint of what ships to the client (dev re-emit trigger). */
+    signature: string;
+    /** How many modules the walk visited (informational). */
+    moduleCount: number;
+}
+export type ResolveFn = (spec: string, importer: string) => string | null;
+export interface ModuleInfo {
+    file: string;
+    display: string;
+    edges: RawEdge[];
+    builtins: string[];
+    patterns: string[];
+}
+export interface CachedModule {
+    mtimeMs: number;
+    info: ModuleInfo;
+}
+export interface LeakAnalyzerOptions {
+    /** Project root — display paths and `serverOnly` matching are relative to it. */
+    rootDir: string;
+    /** Absolute app directory (velo:transform's scope). */
+    appDir: string;
+    /** Routes file name inside appDir (default "routes.tsx"). */
+    routesFile?: string | undefined;
+    /** The client entry's import specifiers (the virtual entry's imports). */
+    entrySpecs: string[];
+    /** Glob patterns declaring server-only modules (VeloConfig.serverOnly). */
+    serverOnly?: readonly string[] | undefined;
+    /** Import resolver: (specifier, importer file) -> absolute file or null. */
+    resolve?: ResolveFn | undefined;
+    /** Optional parse cache shared across runs (dev). */
+    cache?: Map<string, CachedModule> | undefined;
+}
+interface RawEdge {
+    spec: string;
+    line: number;
+    kind: "static" | "dynamic";
+    locals: string[];
+}
+/** True when the specifier names a Node builtin (with or without the `node:` prefix). */
+export declare function isBuiltinSpec(spec: string): boolean;
+/**
+ * Compiles a glob (`*` = within a segment, `**` across segments, `?` = one
+ * char) into a full-match regex over the module path relative to the project
+ * root, always with `/` separators.
+ */
+export declare function globToRegex(glob: string): RegExp;
+/**
+ * Resolution mirroring what the client build follows: relative specifiers with
+ * TS extension completion, bare specifiers through `node_modules` with the
+ * package's browser/import `exports` conditions. Returns null for anything
+ * that does not resolve to a file (external, virtual or unresolvable).
+ */
+export declare function defaultResolve(spec: string, importer: string): string | null;
+export declare function analyzeClientLeaks(options: LeakAnalyzerOptions): LeakReport;
+export declare function formatLeakReport(report: LeakReport): string;
+export {};

package/dist/leak-diagnostic.js

@@ -0,0 +1,14 @@
+import "node:fs";
+import "node:path";
+import "node:module";
+import "@babel/parser";
+import "@babel/traverse";
+import "@babel/types";
+import { a as s, d as l, f, g, i as n } from "./vite.js";
+export {
+  s as analyzeClientLeaks,
+  l as defaultResolve,
+  f as formatLeakReport,
+  g as globToRegex,
+  n as isBuiltinSpec
+};

package/dist/vite.d.ts

@@ -81,6 +81,42 @@ export declare function declaredChannelNames(code: string): string[] | null;
  * A missing file yields an empty set, which makes every declaration unknown.
  */
 export declare function readChannelMapNames(file: string): Set<string>;
+export interface ModuleTransformOptions {
+    /** Absolute module id (the Vite module id). */
+    id: string;
+    /** Absolute app directory (velo:transform's scope). */
+    appDir: string;
+    /** Whether this is the SSR/server pass. */
+    isSSR: boolean;
+    /** Routes file name inside appDir (default "routes.tsx"). */
+    routesFile?: string | undefined;
+    /** Route path info (metadata injection only — never changes imports). */
+    pathInfo?: PathInfo | undefined;
+}
+export interface ModuleTransformResult {
+    code: string;
+    moduleId: string;
+}
+/** The moduleId velo:transform derives for a module (appDir-relative, no ext). */
+export declare function moduleIdFor(appDir: string, id: string): string;
+/**
+ * The exact module transform velo:transform applies — one pipeline, two users:
+ * the build itself and the server->client leak diagnostic (which must see what
+ * travels, never a reprint that could diverge). Returns null when the module is
+ * out of scope or no transformation fired; the build then ships the source
+ * untouched.
+ */
+export declare function transformModuleCode(code: string, options: ModuleTransformOptions): ModuleTransformResult | null;
+/**
+ * The client entry's import specifiers — the same list the generated
+ * `virtual:velo/client-entry` module imports. Shared so the leak diagnostic
+ * starts its walk at exactly what the browser loads.
+ */
+export declare function clientEntryModulePaths(appDir: string, veloConfig: VeloConfig): {
+    clientInit: string;
+    routes: string;
+    framework: string;
+};
 /**
  * @hono/vite-dev-server treats `exclude` as all-or-nothing: passing one
  * replaces the defaults entirely. We compose instead — the upstream defaults