@celsian/vura-cli 0.6.1 → 0.8.0

package/dist/commands/admin.d.ts

@@ -23,6 +23,22 @@ export declare function isAllowedAdminRequest(headers: {
     host?: string | string[];
     origin?: string | string[];
 }, bindHost: string, port: number): boolean;
+/**
+ * Start the admin server and return once it is listening.
+ *
+ * Split out of `adminCommand` so tests can drive a real server: the command
+ * itself never returns, and the bug this exists to pin lived in the wiring
+ * rather than in any function a unit test could reach. `vura admin --port 0`
+ * built its same-origin allowlist from the *requested* port, so the allowlist
+ * held `localhost:0` while the browser sent the real one and every API request
+ * was refused as cross-origin with a valid token in hand.
+ */
+export declare function startAdminServer(opts: AdminOptions): Promise<{
+    server: import('node:http').Server;
+    port: number;
+    token: string;
+    close: () => Promise<void>;
+}>;
 export declare function adminCommand(args: string[]): Promise<void>;
 export declare function renderDashboardHtml(adminToken: string): string;
 export {};

package/dist/commands/admin.js

@@ -60,8 +60,17 @@ export function isAllowedAdminRequest(headers, bindHost, port) {
         return false;
     }
 }
-export async function adminCommand(args) {
-    const opts = parseAdminOptions(args);
+/**
+ * Start the admin server and return once it is listening.
+ *
+ * Split out of `adminCommand` so tests can drive a real server: the command
+ * itself never returns, and the bug this exists to pin lived in the wiring
+ * rather than in any function a unit test could reach. `vura admin --port 0`
+ * built its same-origin allowlist from the *requested* port, so the allowlist
+ * held `localhost:0` while the browser sent the real one and every API request
+ * was refused as cross-origin with a valid token in hand.
+ */
+export async function startAdminServer(opts) {
     assertSafeAdminBindHost(opts.host);
     const { createServer } = await import('node:http');
     const { randomBytes } = await import('node:crypto');
@@ -72,11 +81,17 @@ export async function adminCommand(args) {
     const config = await loadConfig(opts.projectRoot);
     const projectName = basename(opts.projectRoot);
     const adminToken = randomBytes(32).toString('base64url');
+    // The port the server actually bound. `--port 0` means "pick a free port",
+    // and the same-origin allowlist below is built from it: with the *requested*
+    // port the allowlist held `localhost:0` while the browser sent the real one,
+    // so every request to a `--port 0` dashboard was refused as cross-origin.
+    // Assigned in the listen callback, before any request can arrive.
+    let boundPort = opts.port;
     const server = createServer(async (req, res) => {
         const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
         const method = (req.method ?? 'GET').toUpperCase();
         const isAdminApi = url.pathname.startsWith('/__admin/api/');
-        const sameOrigin = isAllowedAdminRequest(req.headers, opts.host, opts.port);
+        const sameOrigin = isAllowedAdminRequest(req.headers, opts.host, boundPort);
         const apiHeaders = adminApiHeaders();
         if (method === 'OPTIONS') {
             res.writeHead(sameOrigin ? 204 : 403, {
@@ -311,25 +326,52 @@ export async function adminCommand(args) {
         res.writeHead(404, apiHeaders);
         res.end(JSON.stringify({ error: 'Not found' }));
     });
-    server.listen(opts.port, opts.host, () => {
+    const onListening = () => {
         const displayHost = opts.host === '127.0.0.1' ? 'localhost' : opts.host;
+        const addr = server.address();
+        boundPort = addr && typeof addr === 'object' ? addr.port : opts.port;
         const displayUrl = displayHost.includes(':')
-            ? `http://[${displayHost}]:${opts.port}`
-            : `http://${displayHost}:${opts.port}`;
-        console.log(`
-  ┌─────────────────────────────────────────┐
-  │                                         │
-  │   vura admin                            │
-  │                                         │
-  │   Dashboard: ${displayUrl.padEnd(22)} │
-  │   Token:     ${adminToken.slice(0, 8).padEnd(25)} │
-  │   Project:   ${projectName.slice(0, 25).padEnd(25)} │
-  │                                         │
-  │   ${manifest.api.length} API routes · ${manifest.pages.length} pages             │
-  │                                         │
-  └─────────────────────────────────────────┘
-`);
+            ? `http://[${displayHost}]:${boundPort}`
+            : `http://${displayHost}:${boundPort}`;
+        // Every line is padded to one width. They used to be padded to four
+        // different ones (36, 39, 39 and 38 inside a 41-wide box), so the box only
+        // ever looked square by accident of the default port's length.
+        const W = 41;
+        const line = (text = '') => `  │${text.padEnd(W).slice(0, W)}│`;
+        const rule = (l, r) => `  ${l}${'─'.repeat(W)}${r}`;
+        const field = (label, value) => line(`   ${label.padEnd(12)}${value}`);
+        console.log([
+            '',
+            rule('┌', '┐'),
+            line(),
+            line('   vura admin'),
+            line(),
+            field('Dashboard:', displayUrl),
+            field('Token:', `${adminToken.slice(0, 8)}...`),
+            field('Project:', projectName),
+            line(),
+            line(`   ${manifest.api.length} API routes · ${manifest.pages.length} pages`),
+            line(),
+            rule('└', '┘'),
+            '',
+        ].join('\n'));
+    };
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port, opts.host, () => {
+            onListening();
+            resolve();
+        });
     });
+    return {
+        server,
+        port: boundPort,
+        token: adminToken,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+export async function adminCommand(args) {
+    await startAdminServer(parseAdminOptions(args));
     await new Promise(() => { });
 }
 // ─── Dashboard HTML ───

package/dist/commands/build.d.ts

@@ -11,5 +11,29 @@
  * 8. Write manifest.json
  * 9. Emit hot deploy templates (Dockerfile, fly.toml, package.json) when hot routes present
  */
+/**
+ * Remove hashed page bundles that this build did not emit.
+ *
+ * Bundle filenames carry a content hash, so every edit to a client or hybrid
+ * page produces a new name and orphans the old one. Nothing removed those, so
+ * `dist/static/_then/pages` grew with every incremental build and the dead
+ * copies shipped to whatever the project deployed to.
+ *
+ * Recursive, because pages nest (`loaders/island.js`). Empty directories left
+ * behind by a deleted page are removed too. `fs` is injected so this can be
+ * tested without touching a disk.
+ */
+export declare function pruneStaleBundles(dir: string, keep: Set<string>, fs: {
+    readdir: (p: string, o: {
+        withFileTypes: true;
+    }) => Promise<Array<{
+        name: string;
+        isDirectory: () => boolean;
+    }>>;
+    rm: (p: string, o?: {
+        recursive?: boolean;
+        force?: boolean;
+    }) => Promise<void>;
+}): Promise<number>;
 export declare function buildCommand(_args: string[]): Promise<void>;
 //# sourceMappingURL=build.d.ts.map

package/dist/commands/build.js

@@ -11,12 +11,55 @@
  * 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';
+/**
+ * Remove hashed page bundles that this build did not emit.
+ *
+ * Bundle filenames carry a content hash, so every edit to a client or hybrid
+ * page produces a new name and orphans the old one. Nothing removed those, so
+ * `dist/static/_then/pages` grew with every incremental build and the dead
+ * copies shipped to whatever the project deployed to.
+ *
+ * Recursive, because pages nest (`loaders/island.js`). Empty directories left
+ * behind by a deleted page are removed too. `fs` is injected so this can be
+ * tested without touching a disk.
+ */
+export async function pruneStaleBundles(dir, keep, fs) {
+    let removed = 0;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0; // nothing was written here
+    }
+    for (const entry of entries) {
+        const full = pathJoin(dir, entry.name);
+        if (entry.isDirectory()) {
+            removed += await pruneStaleBundles(full, keep, fs);
+            // The page that lived here is gone; do not leave the empty shell.
+            try {
+                const rest = await fs.readdir(full, { withFileTypes: true });
+                if (rest.length === 0)
+                    await fs.rm(full, { recursive: true, force: true });
+            }
+            catch {
+                /* raced or unreadable: leaving it is harmless */
+            }
+            continue;
+        }
+        if (keep.has(full))
+            continue;
+        await fs.rm(full, { force: true });
+        removed++;
+    }
+    return removed;
+}
 // ---------------------------------------------------------------------------
 // Deploy template strings — inlined so they survive tsc compilation (tsc does
 // not copy non-TS assets).  Emitted by emitHotDeployTemplates() when hot
@@ -116,6 +159,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
@@ -177,7 +231,7 @@ export async function buildCommand(_args) {
     // Shared esbuild helpers
     const { build: esbuild } = await import('esbuild');
     const { join, resolve } = await import('node:path');
-    const { mkdir, readFile, rename } = await import('node:fs/promises');
+    const { mkdir, readFile, rename, rm, readdir } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { createHash } = await import('node:crypto');
     const cliRequire = createRequire(import.meta.url);
@@ -215,7 +269,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 +297,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,69 +326,23 @@ export async function buildCommand(_args) {
                 return null;
             });
         },
-    };
-    // 3. Bundle server-mode pages
-    const serverPages = manifest.pages.filter(p => p.mode === 'server' || p.mode === 'hybrid');
-    if (serverPages.length > 0) {
-        console.log(`  Bundling ${serverPages.length} server-mode pages...`);
-        const serverPagesDir = join(root, 'dist', 'server', 'pages');
-        await mkdir(serverPagesDir, { recursive: true });
-        for (const page of serverPages) {
-            const absPath = resolve(root, page.filePath);
-            const outFile = page.filePath.replace(/^src\/pages\//, '').replace(/\.tsx?$/, '.js');
-            const outPath = join(serverPagesDir, outFile);
-            await mkdir(join(outPath, '..'), { recursive: true });
-            await esbuild({
-                entryPoints: [absPath],
-                bundle: true,
-                format: 'esm',
-                target: 'es2022',
-                platform: 'node',
-                outfile: outPath,
-                jsx: 'automatic',
-                jsxImportSource,
-                plugins: [esmResolvePlugin],
-                external: [],
-            });
-            console.log(`    ◈ ${page.urlPattern} → dist/server/pages/${outFile}`);
-        }
-    }
-    // 3b. Bundle layout files used by server-mode pages
-    if (manifest.layouts.length > 0 && serverPages.length > 0) {
-        // Only compile layouts that are actually referenced by server-mode pages
-        const usedLayoutPaths = new Set();
-        for (const page of serverPages) {
-            if (page.layouts) {
-                for (const lp of page.layouts)
-                    usedLayoutPaths.add(lp);
-            }
-        }
-        const layoutsToCompile = manifest.layouts.filter(l => usedLayoutPaths.has(l.filePath));
-        if (layoutsToCompile.length > 0) {
-            console.log(`  Bundling ${layoutsToCompile.length} layout files...`);
-            const serverPagesDir = join(root, 'dist', 'server', 'pages');
-            await mkdir(serverPagesDir, { recursive: true });
-            for (const layout of layoutsToCompile) {
-                const absPath = resolve(root, layout.filePath);
-                const outFile = layout.filePath.replace(/^src\/pages\//, '').replace(/\.tsx?$/, '.js');
-                const outPath = join(serverPagesDir, outFile);
-                await mkdir(join(outPath, '..'), { recursive: true });
-                await esbuild({
-                    entryPoints: [absPath],
-                    bundle: true,
-                    format: 'esm',
-                    target: 'es2022',
-                    platform: 'node',
-                    outfile: outPath,
-                    jsx: 'automatic',
-                    jsxImportSource,
-                    plugins: [esmResolvePlugin],
-                    external: [],
-                });
-                console.log(`    ⊟ layout ${layout.dirPattern || '(root)'} → dist/server/pages/${outFile}`);
-            }
-        }
-    }
+    });
+    /** Externals every server-side bundle shares: one framework copy per process. */
+    /** 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 });
+    // Steps 3a and 3b used to live here: the CLI bundled every server-mode page
+    // and every layout into `dist/server/pages/`, and then core's `build()` ran
+    // `bundleServerPageModules()` over the same inputs and overwrote every one of
+    // those files. The output was byte-identical, so the only thing the CLI's
+    // copy produced was a second esbuild pass per page and per layout on every
+    // build, plus a second copy of the resolve configuration to keep in sync with
+    // core's. The `useSignal` bug shipped through exactly that kind of duplicate:
+    // one copy was fixed and the other was not.
+    //
+    // Page and layout bundling now happens once, in core. `serverEsmResolvePlugin`
+    // below is still used for the standalone entry.
     // 3c. Bundle browser entries for client and hybrid pages.
     // Each bundle is a generated wrapper (generateClientPageEntry) that imports
     // the page module and calls mount() (client) / hydrate() (hybrid) — bundling
@@ -327,6 +354,10 @@ export async function buildCommand(_args) {
         console.log(`  Bundling ${browserPages.length} browser page entries...`);
         const clientPagesDir = join(root, 'dist', 'static', '_then', 'pages');
         await mkdir(clientPagesDir, { recursive: true });
+        // Every bundle this build writes. Anything else under the directory is a
+        // bundle from an earlier build whose content hash has since changed, and
+        // nothing references it any more.
+        const emittedBundles = new Set();
         const { dirname, basename } = await import('node:path');
         for (const page of browserPages) {
             const absPath = resolve(root, page.filePath);
@@ -335,7 +366,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 +385,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')
@@ -359,10 +402,23 @@ export async function buildCommand(_args) {
                 .slice(0, 12);
             const hashedOutFile = outFile.replace(/\.js$/, `.${bundleHash}.js`);
             await rename(outPath, join(clientPagesDir, hashedOutFile));
+            emittedBundles.add(join(clientPagesDir, hashedOutFile));
             const scriptPath = `/_then/pages/${hashedOutFile.replace(/\\/g, '/')}`;
             clientScripts[page.filePath] = scriptPath;
             console.log(`    ◇ ${page.urlPattern} → dist/static${scriptPath}`);
         }
+        // Drop bundles left behind by earlier builds. The filename carries a
+        // content hash, so editing a page emits a new name and orphans the old
+        // one, which nothing then removes: `dist/` grew with every incremental
+        // build and shipped the dead copies to whatever you deployed to.
+        //
+        // Pruning *after* the writes rather than wiping the directory first is
+        // deliberate. A build that fails partway leaves the previous bundles
+        // intact instead of leaving nothing to serve.
+        const pruned = await pruneStaleBundles(clientPagesDir, emittedBundles, { readdir, rm });
+        if (pruned > 0) {
+            console.log(`    ✓ removed ${pruned} stale bundle${pruned === 1 ? '' : 's'} from earlier builds`);
+        }
     }
     // 4. Build API routes + task entries
     console.log('  Building...');
@@ -412,7 +468,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, createVuraStreamRoute, isStreamingPage, } 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,52 @@ 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)] : []),
+    });
+    /**
+     * The streaming counterpart, built from the same options as the string
+     * renderer above so the two cannot disagree about which scripts a page gets.
+     */
+    const devStreamRouteFor = (page) => createVuraStreamRoute({
+        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 +287,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 +334,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 +352,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 +397,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 +587,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 +653,58 @@ 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,
+                        // 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 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,
+                        });
+                        // Streaming pages take the same route in dev as in production,
+                        // through the same helper and the same response writer. A dev
+                        // server that renders a streamed page as a string would hide
+                        // exactly the bugs streaming introduces.
+                        if (method === 'GET' && isStreamingPage(runtimePage)) {
+                            const streamed = await devStreamRouteFor(pageMatch.page)({
+                                path: url.pathname,
                                 query: Object.fromEntries(url.searchParams.entries()),
+                                route: { path: url.pathname, page: { mode: 'server' }, vura: runtimePage },
+                                params: pageMatch.params,
+                                request: webReq,
                             });
+                            await writeWebResponse(res, streamed);
+                            return;
                         }
-                        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 });
-                                }
-                            }
-                        }
-                        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 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(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                        res.end(html);
+                        res.writeHead(result.status, {
+                            'Content-Type': 'text/html; charset=utf-8',
+                            ...(result.headers ?? {}),
+                        });
+                        res.end(result.html);
                         return;
                     }
                 }
@@ -627,7 +761,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 +787,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();
@@ -689,7 +824,13 @@ export async function startStandaloneServer(manifest, opts) {
     process.on('SIGINT', onSigint);
     await new Promise((resolve) => {
         server.listen(opts.port, opts.host, () => {
-            console.log(`  Server listening on http://${opts.host}:${opts.port}\n`);
+            // The *bound* port, not the requested one. `--port 0` means "pick a free
+            // port", and printing the request back gave a URL of `:0`, which cannot
+            // be connected to. The address is also what tells you which port you got
+            // when the requested one was taken.
+            const addr = server.address();
+            const boundPort = addr && typeof addr === 'object' ? addr.port : opts.port;
+            console.log(`  Server listening on http://${opts.host}:${boundPort}\n`);
             // Warn once at startup when the user explicitly exposes the dev server beyond loopback.
             if (isLanDevHost(opts.host)) {
                 console.warn(`  [vura] Dev server exposed on ${opts.host}. Only use --host for trusted LAN testing.`);

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.8.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",
-    "esbuild": "^0.28.1",
-    "what-framework": "^0.13.2"
+    "@celsian/vura-core": "0.8.0",
+    "esbuild": "^0.28.2",
+    "what-framework": "^0.13.4"
   },
   "peerDependencies": {
-    "@celsian/vura-adapter-vura": "0.6.1",
+    "@celsian/vura-adapter-vura": "0.8.0",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -32,9 +32,9 @@
     }
   },
   "devDependencies": {
-    "@celsian/vura-adapter-vura": "0.6.1",
+    "@celsian/vura-adapter-vura": "0.8.0",
     "@types/ws": "^8.18.1",
-    "ws": "^8.21.0"
+    "ws": "^8.21.3"
   },
   "license": "MIT",
   "publishConfig": {