@celsian/vura-cli 0.6.1 → 0.7.0

package/dist/commands/build.js

@@ -11,10 +11,10 @@
  * 8. Write manifest.json
  * 9. Emit hot deploy templates (Dockerfile, fly.toml, package.json) when hot routes present
  */
-import { buildManifest, build, renderStaticPages, generateClientPageEntry, vuraBrowserResolvePlugin } from '@celsian/vura-core';
+import { buildManifest, build, renderStaticPages, generateClientPageEntry, vuraBrowserResolvePlugin, vuraActionsStubPlugin } from '@celsian/vura-core';
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync } from 'node:fs';
-import { join as pathJoin, resolve as pathResolve } from 'node:path';
+import { join as pathJoin, resolve as pathResolve, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { loadConfig } from '../config-loader.js';
 // ---------------------------------------------------------------------------
@@ -116,6 +116,17 @@ async function emitDeployPackageJson(distDir, projectRoot, hasWsRoutes) {
     await writeFile(pkgPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
 }
 /** The exact what-framework version installed in the project, or null. */
+/**
+ * Import specifiers for a page's layout chain, relative to the page's own
+ * directory (the resolveDir the generated browser entry is bundled with).
+ */
+function layoutSpecifiersFor(page, projectRoot) {
+    const pageDir = pathResolve(projectRoot, page.filePath, '..');
+    return (page.layouts ?? []).map((layoutPath) => {
+        const rel = relative(pageDir, pathResolve(projectRoot, layoutPath)).replace(/\\/g, '/');
+        return rel.startsWith('.') ? rel : `./${rel}`;
+    });
+}
 function resolveWhatFrameworkVersion(projectRoot) {
     // Read the installed package.json off disk instead of resolving the
     // specifier. `require('what-framework/package.json')` looks like the obvious
@@ -215,7 +226,24 @@ export async function buildCommand(_args) {
         }
         return join(root, 'node_modules', pkg);
     }
-    const esmResolvePlugin = {
+    /**
+     * Resolve the bare specifiers esbuild cannot.
+     *
+     * `inlineWhatFramework` decides what happens to `what-framework` and
+     * `what-core`. A browser bundle needs them inlined — there is no module
+     * resolution in a browser, and their exports maps are import-condition-only,
+     * so `require.resolve` cannot find them. A **server** bundle must keep them
+     * external, and this is the switch that says which.
+     *
+     * It exists because an `onResolve` that returns a path *beats* esbuild's
+     * `external` list. Setting both, as the build-time page loader did, silently
+     * loses: the page module inlined its own copy of what-core while
+     * `renderToString` ran from the installed one, the two disagreed about which
+     * component was rendering, and `useSignal()` threw "can only be called
+     * inside a component function" in every `static` and `hybrid` page. Loaders
+     * escaped it only because `@celsian/vura-core` is not intercepted here.
+     */
+    const makeEsmResolvePlugin = ({ inlineWhatFramework }) => ({
         name: 'esm-resolve',
         setup(build) {
             build.onResolve({ filter: /^@celsian\/vura-core\/(jsx-runtime|jsx-dev-runtime)$/ }, (args) => {
@@ -226,6 +254,8 @@ export async function buildCommand(_args) {
                     return { path: cliRequire.resolve(args.path) };
                 }
             });
+            if (!inlineWhatFramework)
+                return;
             // Bare what-framework/what-core imports (the generated client entry
             // imports { h, mount, hydrate } from 'what-framework'). The exports map
             // is import-condition-only, so require.resolve can't find it — resolve
@@ -253,7 +283,13 @@ export async function buildCommand(_args) {
                 return null;
             });
         },
-    };
+    });
+    /** Externals every server-side bundle shares: one framework copy per process. */
+    const serverRuntimeExternals = ['what-framework', 'what-framework/*', 'what-core', 'what-core/*'];
+    /** Browser bundles: what-framework is inlined, because a browser has no resolver. */
+    const browserEsmResolvePlugin = makeEsmResolvePlugin({ inlineWhatFramework: true });
+    /** Server bundles: what-framework stays external, so the process holds one copy. */
+    const serverEsmResolvePlugin = makeEsmResolvePlugin({ inlineWhatFramework: false });
     // 3. Bundle server-mode pages
     const serverPages = manifest.pages.filter(p => p.mode === 'server' || p.mode === 'hybrid');
     if (serverPages.length > 0) {
@@ -274,8 +310,10 @@ export async function buildCommand(_args) {
                 outfile: outPath,
                 jsx: 'automatic',
                 jsxImportSource,
-                plugins: [esmResolvePlugin],
-                external: [],
+                plugins: [serverEsmResolvePlugin],
+                // Server bundles keep the framework external so the process holds one
+                // copy; core's builder rewrites these files with the same externals.
+                external: serverRuntimeExternals,
             });
             console.log(`    ◈ ${page.urlPattern} → dist/server/pages/${outFile}`);
         }
@@ -309,8 +347,8 @@ export async function buildCommand(_args) {
                     outfile: outPath,
                     jsx: 'automatic',
                     jsxImportSource,
-                    plugins: [esmResolvePlugin],
-                    external: [],
+                    plugins: [serverEsmResolvePlugin],
+                    external: serverRuntimeExternals,
                 });
                 console.log(`    ⊟ layout ${layout.dirPattern || '(root)'} → dist/server/pages/${outFile}`);
             }
@@ -335,7 +373,11 @@ export async function buildCommand(_args) {
             await mkdir(join(outPath, '..'), { recursive: true });
             await esbuild({
                 stdin: {
-                    contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode),
+                    contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode, 
+                    // The server rendered this page inside its layouts, so the browser
+                    // has to hydrate the same tree. Specifiers are relative to the
+                    // page's own directory, which is the entry's resolveDir.
+                    { layoutImportSpecifiers: layoutSpecifiersFor(page, root) }),
                     resolveDir: dirname(absPath),
                     sourcefile: '__vura-client-entry__.js',
                     loader: 'js',
@@ -350,7 +392,15 @@ export async function buildCommand(_args) {
                 // Browser-resolve first: a page that imports `@celsian/vura-core` for
                 // useLoaderData must get the pure client module here, not the package
                 // root, which reaches node:fs and cannot be bundled for a browser.
-                plugins: [vuraBrowserResolvePlugin(), esmResolvePlugin],
+                //
+                // The actions stub plugin is the security boundary for `src/actions/`:
+                // it answers onResolve, so esbuild never opens an action file for this
+                // bundle and nothing inside one can reach the browser.
+                plugins: [
+                    vuraBrowserResolvePlugin(),
+                    vuraActionsStubPlugin({ projectRoot: root }),
+                    browserEsmResolvePlugin,
+                ],
                 external: [],
             });
             const bundleHash = createHash('sha256')
@@ -412,7 +462,7 @@ export async function buildCommand(_args) {
                 outfile: tmpFile,
                 jsx: 'automatic',
                 jsxImportSource,
-                plugins: [esmResolvePlugin],
+                plugins: [serverEsmResolvePlugin],
                 external: sharedRuntimeExternals,
             });
             return nativeImport(pathToFileURL(tmpFile).href);

package/dist/commands/dev.js

@@ -12,9 +12,9 @@
  *   vura dev              — Start dev server on port 3000
  *   vura dev --port 8080  — Start on custom port
  */
-import { renderToString as builtinRenderToString } from 'what-framework/server';
 import { importRouteModule } from './shared.js';
-import { buildManifest, compilePageRoutes, matchPageRoute, compileRoutes, matchApiPath, getLogger, wrapDocument, escapeHtml, parseNodeBody, reportError, getMimeType, runTaskOnce, buildTaskEnvelope, createApiApp, createWsUpgradeHandler, createNoServerWebSocketServer, GLOBAL_HOOKS_FILENAMES, nodeToWebRequest, writeWebResponse, generateClientPageEntry, vuraBrowserResolvePlugin, } from '@celsian/vura-core';
+import { resolve as nodeResolve, relative as nodeRelative } from 'node:path';
+import { buildManifest, compilePageRoutes, matchPageRoute, compileRoutes, matchApiPath, getLogger, wrapDocument, escapeHtml, parseNodeBody, reportError, getMimeType, runTaskOnce, buildTaskEnvelope, createApiApp, createWsUpgradeHandler, createNoServerWebSocketServer, GLOBAL_HOOKS_FILENAMES, nodeToWebRequest, writeWebResponse, generateClientPageEntry, vuraBrowserResolvePlugin, vuraActionsStubPlugin, registerActionModules, ACTION_ENDPOINT, createMiddlewareRunner, createVuraRenderRoute, } from '@celsian/vura-core';
 export function parseDevOptions(args, projectRoot = process.cwd()) {
     const portArg = args.find((_, i) => args[i - 1] === '--port');
     const hostArg = args.find((_, i) => args[i - 1] === '--host');
@@ -141,6 +141,15 @@ function printRouteTable(manifest) {
             console.log(`    ${icon} ${page.mode.padEnd(18)} ${page.urlPattern}`);
         }
     }
+    const actions = manifest.actions ?? [];
+    if (actions.length > 0) {
+        console.log('  Actions:');
+        for (const mod of actions) {
+            for (const name of mod.exports) {
+                console.log(`    ⚡ ${'server action'.padEnd(18)} ${mod.moduleId}#${name}`);
+            }
+        }
+    }
     console.log();
 }
 /**
@@ -181,7 +190,45 @@ export async function startStandaloneServer(manifest, opts) {
         return mod;
     }
     const logger = getLogger();
+    /**
+     * The render callback for one page request.
+     *
+     * A hybrid page's browser bundle lives at a dev-server path that does not
+     * exist at build time, so it is injected here rather than read off the page.
+     *
+     * Built per request, closing over the matched page, because the RuntimePage
+     * handed to the renderer has its `mode` forced to `'server'` (dev SSRs every
+     * non-client page per request, with no build output and no ISR in front of
+     * it). A predicate reading the mode off *that* object can never see
+     * `'hybrid'`, so it silently stopped injecting the bundle and every hybrid
+     * page in dev rendered its markup and then never hydrated. The real mode
+     * lives on the matched page, so that is what decides.
+     */
+    const devRenderRouteFor = (page) => createVuraRenderRoute({
+        extraScripts: () => (page.mode === 'hybrid' ? [browserScriptPath(page)] : []),
+    });
     const { existsSync } = await import('node:fs');
+    // ── Middleware ──
+    // Loaded through the same cached loader as routes so an edit is picked up on
+    // the next request, and so module-level state in a middleware behaves the way
+    // it does in a route. `manifest.middleware` is refreshed by the fs-watcher
+    // rescan, so adding or deleting the file mid-session is picked up too.
+    async function currentMiddlewareRunner(forManifest) {
+        if (!forManifest.middleware)
+            return createMiddlewareRunner(null);
+        try {
+            const mod = await loadHandlerCached(forManifest.middleware);
+            return createMiddlewareRunner(mod);
+        }
+        catch (err) {
+            // A syntax error in middleware must not take the whole dev server down,
+            // and it must not silently disable the auth guard the developer is
+            // relying on either. Say so, loudly, on every request until it is fixed.
+            const error = err instanceof Error ? err : new Error(String(err));
+            logger.error(`[vura] middleware failed to load: ${error.message}`);
+            return createMiddlewareRunner(null);
+        }
+    }
     function findGlobalHooksFile() {
         for (const filename of GLOBAL_HOOKS_FILENAMES) {
             if (existsSync(join(opts.projectRoot, filename)))
@@ -233,12 +280,29 @@ export async function startStandaloneServer(manifest, opts) {
             onError: [...(globalHooks?.onError ?? []), devErrorHook],
             onResponse: globalHooks?.onResponse ?? [],
         };
+        // Server actions. Loaded and registered on every rebuild, so editing an
+        // action file takes effect on the next request the way editing a route
+        // does. Registration is keyed by id, so a re-register replaces rather than
+        // duplicates; an action deleted from a file stops being callable only once
+        // the process restarts, which is the same limitation dev has for a deleted
+        // route module and is not worth a registry generation counter.
+        const actionModules = {};
+        for (const mod of forManifest.actions ?? []) {
+            actionModules[mod.moduleId] = await loadHandler(mod.filePath);
+        }
+        const hasActions = Object.keys(actionModules).length > 0;
+        if (hasActions)
+            registerActionModules(actionModules);
         // Compile route regexes for the path-existence pre-check (method-agnostic).
         const compiledApiRoutes = compileRoutes(routes);
-        return { app: createApiApp({ routes, globalHooks: mergedHooks }), compiledApiRoutes };
+        return {
+            app: createApiApp({ routes, globalHooks: mergedHooks, enableActions: hasActions }),
+            compiledApiRoutes,
+            internalPaths: hasActions ? [ACTION_ENDPOINT] : [],
+        };
     }
     // Build initial CelsianApp and page route table
-    let { app: apiApp, compiledApiRoutes } = await buildStandaloneApiApp(manifest);
+    let { app: apiApp, compiledApiRoutes, internalPaths } = await buildStandaloneApiApp(manifest);
     // In dev mode, compile ALL page routes — not just server/hybrid.
     // Static and server pages are SSR'd on the fly; client pages are served as
     // a shell + on-demand browser bundle (SSR'ing them would run hooks like
@@ -263,7 +327,10 @@ export async function startStandaloneServer(manifest, opts) {
         catch { /* not installed — keep default */ }
         const result = await esbuild({
             stdin: {
-                contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode, { dev: true }),
+                contents: generateClientPageEntry(`./${basename(absPath)}`, page.mode, 
+                // Same layout chain the dev renderer wraps the page in, so hydration
+                // walks the tree that is actually in the document.
+                { dev: true, layoutImportSpecifiers: devLayoutSpecifiers(page) }),
                 resolveDir: dirname(absPath),
                 sourcefile: '__vura-client-entry__.js',
                 loader: 'js',
@@ -278,13 +345,28 @@ export async function startStandaloneServer(manifest, opts) {
             jsxImportSource,
             // Same redirect the production build applies: `@celsian/vura-core` in a
             // browser bundle resolves to the pure client module.
-            plugins: [vuraBrowserResolvePlugin()],
+            // The actions stub plugin is what keeps `src/actions/` source out of a
+            // browser bundle in dev as well as in a build. Without it `vura dev`
+            // would happily bundle a database client into the page and only the
+            // production build would catch it.
+            plugins: [vuraBrowserResolvePlugin(), vuraActionsStubPlugin({ projectRoot: opts.projectRoot })],
             nodePaths: [join(opts.projectRoot, 'node_modules')],
         });
         const text = result.outputFiles[0].text;
         browserBundleCache.set(page.filePath, text);
         return text;
     }
+    /**
+     * Import specifiers for a page's layouts, relative to the page's directory,
+     * which is the resolveDir the browser entry is bundled with.
+     */
+    function devLayoutSpecifiers(page) {
+        const pageDir = nodeResolve(opts.projectRoot, page.filePath, '..');
+        return (page.layouts ?? []).map((layoutPath) => {
+            const rel = nodeRelative(pageDir, nodeResolve(opts.projectRoot, layoutPath)).replace(/\\/g, '/');
+            return rel.startsWith('.') ? rel : `./${rel}`;
+        });
+    }
     const server = createServer(async (req, res) => {
         const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
         const method = (req.method ?? 'GET').toUpperCase();
@@ -308,6 +390,34 @@ export async function startStandaloneServer(manifest, opts) {
             res.end();
             return;
         }
+        // ── Middleware ──
+        // Before static serving, before routes: an auth guard has to be able to
+        // keep a visitor away from a page, and a page may be a prerendered file.
+        let middlewareHeaders;
+        {
+            const runner = await currentMiddlewareRunner(manifest);
+            if (runner.enabled) {
+                const webReq = new Request(url.toString(), {
+                    method,
+                    headers: req.headers,
+                });
+                const outcome = await runner.run(webReq, url);
+                if (outcome.response) {
+                    const headers = {};
+                    outcome.response.headers.forEach((v, k) => { headers[k] = v; });
+                    res.writeHead(outcome.response.status, headers);
+                    res.end(outcome.response.body ? await outcome.response.text() : '');
+                    return;
+                }
+                middlewareHeaders = outcome.headers;
+            }
+            if (middlewareHeaders) {
+                for (const [k, v] of middlewareHeaders) {
+                    if (!res.hasHeader(k))
+                        res.setHeader(k, v);
+                }
+            }
+        }
         // Static file serving from public/ directory
         if (method === 'GET' || method === 'HEAD') {
             const publicDir = join(opts.projectRoot, 'public');
@@ -470,7 +580,7 @@ export async function startStandaloneServer(manifest, opts) {
             // pattern matches this pathname, skip celsian entirely and fall through to
             // pages/404. This also correctly passes through intentional handler 404s —
             // if the route exists but returns 404, that response is delivered as-is.
-            if (matchApiPath(compiledApiRoutes, url.pathname)) {
+            if (matchApiPath(compiledApiRoutes, url.pathname) || internalPaths.includes(url.pathname)) {
                 try {
                     const webReq = nodeToWebRequest(req, url);
                     const webRes = await apiApp.handle(webReq);
@@ -536,41 +646,43 @@ export async function startStandaloneServer(manifest, opts) {
                         return;
                     }
                     if (typeof Component === 'function') {
-                        let serverData = {};
-                        if (typeof mod.getServerData === 'function') {
-                            serverData = await mod.getServerData({
-                                params: pageMatch.params,
-                                url: url.pathname,
-                                query: Object.fromEntries(url.searchParams.entries()),
-                            });
-                        }
-                        let vnode = Component({ ...serverData, params: pageMatch.params });
-                        // Wrap in layout chain if layouts are defined (outermost first)
-                        if (pageMatch.page.layouts && pageMatch.page.layouts.length > 0) {
-                            // Load layouts innermost-last, wrap from inside out
-                            for (let li = pageMatch.page.layouts.length - 1; li >= 0; li--) {
-                                const layoutMod = await loadHandler(pageMatch.page.layouts[li]);
-                                const LayoutComponent = layoutMod.default;
-                                if (typeof LayoutComponent === 'function') {
-                                    vnode = LayoutComponent({ children: vnode, params: pageMatch.params });
-                                }
-                            }
+                        // Rendered by the SAME function the production server uses.
+                        // The dev server used to carry its own copy of this logic, and it
+                        // drifted: it called the component directly instead of through
+                        // `h()`, it knew only `getServerData` and not `loader`, and it had
+                        // no layout data, no payload and no notFound/redirect. So RFC 0001
+                        // loaders worked in a built app and failed in `vura dev`, which is
+                        // where a developer meets the feature first.
+                        const layoutModules = [];
+                        for (const layoutPath of pageMatch.page.layouts ?? []) {
+                            layoutModules.push(await loadHandler(layoutPath));
                         }
-                        const bodyHtml = builtinRenderToString(vnode);
-                        const html = wrapDocument(bodyHtml, {
-                            title: pageConfig.title ?? 'Vura App',
-                            meta: pageConfig.meta ?? [],
-                            styles: pageConfig.styles ?? [],
-                            // Hybrid pages also load their browser bundle so hydrate() runs
-                            // against the SSR'd DOM — same contract as the production build.
-                            scripts: [
-                                ...(pageConfig.scripts ?? []),
-                                ...(pageMatch.page.mode === 'hybrid' ? [browserScriptPath(pageMatch.page)] : []),
-                            ],
-                            head: pageConfig.head ?? '',
+                        const runtimePage = {
+                            ...pageMatch.page,
+                            // Dev renders every non-client page per request: there is no
+                            // build output to serve, and no ISR cache in front of it.
+                            mode: 'server',
+                            config: { ...(pageMatch.page.config ?? {}), revalidate: undefined },
+                            module: mod,
+                            layoutModules,
+                        };
+                        const webReq = new Request(url.toString(), {
+                            method,
+                            headers: req.headers,
                         });
-                        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                        res.end(html);
+                        const result = await devRenderRouteFor(pageMatch.page)({
+                            path: url.pathname,
+                            query: Object.fromEntries(url.searchParams.entries()),
+                            config: { mode: 'server' },
+                            route: { path: url.pathname, page: { mode: 'server' }, vura: runtimePage },
+                            params: pageMatch.params,
+                            request: webReq,
+                        });
+                        res.writeHead(result.status, {
+                            'Content-Type': 'text/html; charset=utf-8',
+                            ...(result.headers ?? {}),
+                        });
+                        res.end(result.html);
                         return;
                     }
                 }
@@ -627,7 +739,8 @@ export async function startStandaloneServer(manifest, opts) {
     // Watch for file changes and re-scan manifest
     const apiDir = join(opts.projectRoot, 'src', 'api');
     const pagesDir = join(opts.projectRoot, 'src', 'pages');
-    const watchDirs = [apiDir, pagesDir];
+    const actionsDir = join(opts.projectRoot, 'src', 'actions');
+    const watchDirs = [apiDir, pagesDir, actionsDir];
     const watchers = [];
     for (const dir of watchDirs) {
         try {
@@ -652,7 +765,7 @@ export async function startStandaloneServer(manifest, opts) {
                         // Rebuild against the FRESH manifest (nextManifest) — `manifest`
                         // is only swapped after success, so building from the closure
                         // variable would use the stale route set (see buildStandaloneApiApp).
-                        ({ app: apiApp, compiledApiRoutes } = await buildStandaloneApiApp(nextManifest));
+                        ({ app: apiApp, compiledApiRoutes, internalPaths } = await buildStandaloneApiApp(nextManifest));
                     }
                     catch (err) {
                         moduleCache.clear();

package/dist/commands/shared.js

@@ -44,6 +44,25 @@ export async function importRouteModule(projectRoot, filePath) {
         platform: 'node',
         write: false,
         outfile: 'handler.mjs',
+        // The framework stays external, for the same reason it does in a
+        // production build: this module is imported into the dev server's own
+        // process and rendered by the dev server's `renderToString`. Inlining
+        // what-framework gives the page a second copy with its own "currently
+        // rendering component" and its own context registry, so every hook it
+        // calls reads a registry the renderer never wrote to. That is what made
+        // `useLoaderData()` fail in `vura dev` while working in a built app: the
+        // page reported "found no loader data" and What warned that useContext had
+        // been called outside a render.
+        //
+        // Safe to mark external here because the output is written to a real file
+        // inside the project, so Node resolves these specifiers from the project's
+        // own node_modules.
+        external: [
+            'what-framework',
+            'what-framework/*',
+            '@celsian/vura-core',
+            '@celsian/vura-core/*',
+        ],
         ...(isPage ? { jsx: 'automatic', jsxImportSource } : {}),
     });
     const tmpDir = join(projectRoot, DEV_CACHE_SUBPATH);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celsian/vura-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Vura CLI — build and deploy full-stack apps",
   "type": "module",
   "bin": {
@@ -15,12 +15,12 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@celsian/vura-core": "0.6.1",
+    "@celsian/vura-core": "0.7.0",
     "esbuild": "^0.28.1",
     "what-framework": "^0.13.2"
   },
   "peerDependencies": {
-    "@celsian/vura-adapter-vura": "0.6.1",
+    "@celsian/vura-adapter-vura": "0.7.0",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -32,7 +32,7 @@
     }
   },
   "devDependencies": {
-    "@celsian/vura-adapter-vura": "0.6.1",
+    "@celsian/vura-adapter-vura": "0.7.0",
     "@types/ws": "^8.18.1",
     "ws": "^8.21.0"
   },