feat(server): split .server.ts source-protection from 'use server' RPC marker

The two markers are now complementary instead of interchangeable:

  .server.{js,ts}        path-level boundary: file router refuses to
                         serve the source to the browser.
  'use server'           semantic opt-in: file exports register as
                         RPC-callable from client code.

Concrete behaviours:

  - .server.ts WITH 'use server'    server action: source-protected
                                    + browser-side imports rewritten
                                    to RPC stubs that POST to
                                    /__webjs/action/<hash>/<fn>.
  - .server.ts WITHOUT 'use server' server-only utility: source-
                                    protected + browser-side imports
                                    get a throw-at-load stub that
                                    errors with a clear message.
  - 'use server' WITHOUT .server.ts ignored (a separate lint rule
                                    flags it). File serves to the
                                    browser as plain TS source.

Implementation surface:

  actions.js  isServerFile() becomes a synchronous path-only check.
              Add hasUseServerDirective() + isServerAction(). Add
              serveServerOnlyStub() for the throw-at-load case.
              buildActionIndex only registers RPC routes when both
              markers are present.

  dev.js      File-serving handler dispatches between RPC stub and
              server-only stub based on hasUseServerDirective().
              Source protection still triggers on .server.ts alone.

Test updates assert the new behaviour: server-file guardrail tests
cover all four combinations of extension/directive presence; action
tests' fixtures now include 'use server' where they expect RPC
behaviour.

Author: vivek7405

packages/server/src/actions.js

@@ -28,16 +28,33 @@ async function rpcResponse(payload, init = {}) {
 /**
  * Server-actions subsystem.
  *
- * A "server action" is an async function defined in:
- *   - any file ending in `.server.js`, OR
- *   - any .js file whose first non-empty, non-comment line is `'use server'`.
+ * Two complementary markers describe server-side files:
+ *
+ *   - `.server.{js,ts,mts,mjs}` extension: file is **server-only**. The
+ *     file router refuses to serve its source to the browser. This is
+ *     the path-level boundary.
+ *   - `'use server'` directive at the top: file's exports are
+ *     **RPC-callable** from client code. This is the semantic opt-in.
+ *
+ * The two together (`.server.ts` AND `'use server'`) define a server
+ * action: source-protected AND RPC-exposed. The extension alone marks
+ * a server-only utility (source-protected, NOT RPC-exposed: browser
+ * imports get an error stub that throws at load). The directive alone
+ * (no extension) does nothing: a `webjs check` lint rule
+ * (`use-server-needs-extension`) flags it because the file is served
+ * to the browser as plain source and the directive is silently
+ * ignored.
  *
  * The server:
- *   1. Scans the app tree on boot, building a map of { hash -> absFile }.
- *   2. Serves a generated ES-module stub when the browser imports the file URL.
- *   3. Exposes POST endpoints at /__webjs/action/:hash/:fn that run the real function.
- *   4. If an exported function was wrapped in `expose('METHOD /path', fn)`, also
- *      registers it as a first-class REST endpoint.
+ *   1. Scans the app tree on boot, classifying server files into
+ *      RPC-callable actions vs. server-only utilities.
+ *   2. Serves a generated ES-module stub when the browser imports
+ *      the file URL (an RPC stub for actions, a throw-at-load stub
+ *      for server-only utilities).
+ *   3. Exposes POST endpoints at /__webjs/action/:hash/:fn for
+ *      RPC-callable actions only.
+ *   4. If an exported function was wrapped in `expose('METHOD /path', fn)`,
+ *      also registers it as a first-class REST endpoint.
  *
  * @typedef {{
  *   method: string,
@@ -74,7 +91,18 @@ export async function buildActionIndex(appDir, dev) {
   const httpRoutes = [];
 
   for await (const file of walk(appDir, (p) => /\.m?[jt]s$/.test(p))) {
-    if (!(await isServerFile(file))) continue;
+    // Path-level: only `.server.{ts,js,mts,mjs}` files are server-only.
+    // A bare `'use server'` directive without the extension is a lint
+    // violation (use-server-needs-extension) and the file is treated as
+    // plain browser code: no source protection, no RPC registration.
+    if (!isServerFile(file)) continue;
+    // Semantic-level: only files that ALSO have `'use server'` are
+    // RPC-callable. `.server.ts` without the directive is server-only
+    // (still source-protected by the file router) but its exports are
+    // NOT registered as RPC endpoints. The browser-side import gets a
+    // throw-at-load stub via `serveServerOnlyStub` instead.
+    if (!(await hasUseServerDirective(file))) continue;
+
     const h = hashFile(file);
     hashToFile.set(h, file);
     fileToHash.set(file, h);
@@ -109,9 +137,32 @@ export function hashFile(file) {
   return createHash('sha256').update(file).digest('hex').slice(0, 10);
 }
 
-/** @param {string} file */
-export async function isServerFile(file) {
-  if (/\.server\.m?[jt]s$/.test(file)) return true;
+/**
+ * Predicate: file is server-only (source-protected, never served as
+ * source to the browser). True for `.server.{js,ts,mts,mjs}` files.
+ * Synchronous, name-only check, the path-level boundary.
+ *
+ * The `'use server'` directive without the extension does NOT make a
+ * file server-only: a `webjs check` lint rule
+ * (`use-server-needs-extension`) flags that pattern instead, and the
+ * file is treated as plain browser code.
+ *
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function isServerFile(file) {
+  return /\.server\.m?[jt]s$/.test(file);
+}
+
+/**
+ * Predicate: file has the `'use server'` directive in its first 5 lines.
+ * Semantic-level marker: when paired with `.server.ts`, registers the
+ * file's exports as RPC-callable from client code.
+ *
+ * @param {string} file
+ * @returns {Promise<boolean>}
+ */
+export async function hasUseServerDirective(file) {
   try {
     const text = await readFile(file, 'utf8');
     const head = text.split('\n').slice(0, 5).join('\n');
@@ -121,6 +172,19 @@ export async function isServerFile(file) {
   }
 }
 
+/**
+ * Predicate: file is a server action (server-only + RPC-callable).
+ * True when both markers are present: `.server.{js,ts}` extension AND
+ * `'use server'` directive.
+ *
+ * @param {string} file
+ * @returns {Promise<boolean>}
+ */
+export async function isServerAction(file) {
+  if (!isServerFile(file)) return false;
+  return await hasUseServerDirective(file);
+}
+
 /**
  * @param {ActionIndex} idx
  * @param {string} urlPath - a browser-visible URL path like `/actions/foo.server.js`
@@ -130,6 +194,27 @@ export function resolveServerModule(idx, urlPath) {
   return idx.fileToHash.has(abs) ? abs : null;
 }
 
+/**
+ * Generate a throw-at-load stub for a server-only file (a `.server.ts`
+ * file WITHOUT a `'use server'` directive). When a browser-side module
+ * imports this file, the stub throws synchronously at module load time
+ * with a clear error pointing at the file, so the developer immediately
+ * sees that server-only code can't be reached from the browser.
+ *
+ * @param {string} relPath path relative to appDir for the error message
+ * @returns {string} JavaScript module source
+ */
+export function serveServerOnlyStub(relPath) {
+  const msg =
+    `Cannot import "${relPath}" from browser code. ` +
+    `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
+    `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
+    `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead.`;
+  return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
+throw new Error(${JSON.stringify(msg)});
+`;
+}
+
 /**
  * Serve the generated client stub for a server module.
  * @param {ActionIndex} idx

packages/server/src/dev.js

@@ -43,13 +43,15 @@ import { handleApi } from './api.js';
 import {
   buildActionIndex,
   serveActionStub,
+  serveServerOnlyStub,
   invokeAction,
   matchExposedAction,
   matchAllAtPath,
   invokeExposedAction,
   buildPreflightResponse,
   withCors,
   isServerFile,
+  hasUseServerDirective,
   hashFile,
 } from './actions.js';
 import { defaultLogger } from './logger.js';
@@ -453,26 +455,34 @@ async function handleCore(req, ctx) {
       }
     }
     if (abs.startsWith(appDir) && (await exists(abs))) {
-      // Server-file guardrail: a file is server-only if its name matches
-      // `.server.{js,ts,mjs,mts}` OR the source starts with `'use server'`.
-      // Such files MUST NEVER be served as source to the browser: they
-      // contain secrets, DB queries, and privileged logic. Always return a
-      // generated RPC stub instead.
+      // Server-file guardrail: a file matching `.server.{js,ts,mjs,mts}`
+      // MUST NEVER be served as source to the browser. The extension is
+      // the path-level boundary; we re-verify it on every request (not
+      // just the action-index snapshot taken at boot) so files created
+      // after boot, FS races, or developer error never punch through.
       //
-      // We re-verify via `isServerFile(abs)` on every request (not just the
-      // action-index snapshot taken at boot). This catches files created
-      // after boot, files that flipped their `'use server'` status, or any
-      // race between scan completion and request: the guardrail is an
-      // independent check, not a cache lookup.
-      if (await isServerFile(abs)) {
-        // Lazily ensure the index knows about this file so serveActionStub
-        // can mint a stable hash and function list.
-        if (!state.actionIndex.fileToHash.has(abs)) {
-          const h = hashFile(abs);
-          state.actionIndex.fileToHash.set(abs, h);
-          state.actionIndex.hashToFile.set(h, abs);
+      // What the browser gets depends on the file's `'use server'` status:
+      //   - With `'use server'` => server action: a generated RPC stub
+      //     whose exports POST to /__webjs/action/:hash/:fn.
+      //   - Without `'use server'` => server-only utility: a stub that
+      //     throws at module load with a clear error. The file's source
+      //     never reaches the browser either way.
+      if (isServerFile(abs)) {
+        if (await hasUseServerDirective(abs)) {
+          // Lazily ensure the index knows about this file so serveActionStub
+          // can mint a stable hash and function list.
+          if (!state.actionIndex.fileToHash.has(abs)) {
+            const h = hashFile(abs);
+            state.actionIndex.fileToHash.set(abs, h);
+            state.actionIndex.hashToFile.set(h, abs);
+          }
+          const stub = await serveActionStub(state.actionIndex, abs);
+          return new Response(stub, {
+            headers: { 'content-type': 'application/javascript; charset=utf-8', 'cache-control': 'no-store' },
+          });
         }
-        const stub = await serveActionStub(state.actionIndex, abs);
+        const relPath = relative(appDir, abs);
+        const stub = serveServerOnlyStub(relPath);
         return new Response(stub, {
           headers: { 'content-type': 'application/javascript; charset=utf-8', 'cache-control': 'no-store' },
         });

test/actions.test.js

@@ -26,7 +26,7 @@ async function scaffold(files) {
 
 test('webjs wire format round-trips Date / Map / BigInt across invokeAction', async () => {
   const dir = await scaffold({
-    'actions/rich.server.js': `
+    'actions/rich.server.js': `'use server';
       export async function now() { return new Date(1234567890000); }
       export async function bag() {
         return { big: 9007199254740993n, set: new Set(['a','b']), map: new Map([[1, 'one']]) };
@@ -59,24 +59,28 @@ test('webjs wire format round-trips Date / Map / BigInt across invokeAction', as
   }
 });
 
-test('detects *.server.js and "use server" pragma files', async () => {
+test('isServerFile is path-only: .server.* yes, anything else no', async () => {
   const dir = await scaffold({
     'actions/a.server.js': 'export const hello = async () => 1',
     'actions/b.js': `'use server';\nexport const bye = async () => 2`,
     'actions/c.js': 'export const plain = () => 3',
   });
   try {
-    assert.equal(await isServerFile(join(dir, 'actions/a.server.js')), true);
-    assert.equal(await isServerFile(join(dir, 'actions/b.js')), true);
-    assert.equal(await isServerFile(join(dir, 'actions/c.js')), false);
+    // .server.{js,ts} extension is the only path-level marker.
+    assert.equal(isServerFile(join(dir, 'actions/a.server.js')), true);
+    // 'use server' WITHOUT the extension is no longer server-only. The
+    // lint rule `use-server-needs-extension` flags it instead; the file
+    // serves to the browser as plain source.
+    assert.equal(isServerFile(join(dir, 'actions/b.js')), false);
+    assert.equal(isServerFile(join(dir, 'actions/c.js')), false);
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
 });
 
 test('stubs server module and invokes action by hash/fn', async () => {
   const dir = await scaffold({
-    'actions/math.server.js': `
+    'actions/math.server.js': `'use server';
       export async function add(a, b) { return a + b; }
       export async function mul(a, b) { return a * b; }
     `,

test/dev-handler.test.js

@@ -563,6 +563,7 @@ test('handle: POST to /__webjs/action/<hash>/<fn> invokes the action', async ()
       `import { html } from ${JSON.stringify(HTML_URL)};\n` +
       `export default function P() { return html\`<p>ok</p>\`; }\n`,
     'actions.server.js':
+      `'use server';\n` +
       `export async function double(n) { return n * 2; }\n`,
   });
   const app = await createRequestHandler({ appDir, dev: true });
@@ -609,6 +610,7 @@ test('handle: expose()d action is reachable by method+path', async () => {
       `import { html } from ${JSON.stringify(HTML_URL)};\n` +
       `export default function P() { return html\`<p>ok</p>\`; }\n`,
     'api.server.js':
+      `'use server';\n` +
       `import { expose } from ${JSON.stringify(pathToFileURL(
         resolve(__dirname, '../packages/core/index.js'),
       ).toString())};\n` +
@@ -626,6 +628,7 @@ test('handle: OPTIONS preflight on expose()d action with cors returns CORS heade
       `import { html } from ${JSON.stringify(HTML_URL)};\n` +
       `export default function P() { return html\`<p>ok</p>\`; }\n`,
     'api.server.js':
+      `'use server';\n` +
       `import { expose } from ${JSON.stringify(pathToFileURL(
         resolve(__dirname, '../packages/core/index.js'),
       ).toString())};\n` +
@@ -648,6 +651,7 @@ test('handle: OPTIONS at a path with exposed actions but no CORS → plain allow
       `import { html } from ${JSON.stringify(HTML_URL)};\n` +
       `export default function P() { return html\`<p>ok</p>\`; }\n`,
     'api.server.js':
+      `'use server';\n` +
       `import { expose } from ${JSON.stringify(pathToFileURL(
         resolve(__dirname, '../packages/core/index.js'),
       ).toString())};\n` +
@@ -667,6 +671,7 @@ test('handle: POST /__webjs/action without CSRF → 403', async () => {
       `import { html } from ${JSON.stringify(HTML_URL)};\n` +
       `export default function P() { return html\`<p>ok</p>\`; }\n`,
     'actions.server.js':
+      `'use server';\n` +
       `export async function noop() { return 1; }\n`,
   });
   const app = await createRequestHandler({ appDir, dev: true });

test/expose.test.js

@@ -54,7 +54,7 @@ async function scaffold(files) {
 test('action scanner discovers expose()d routes and invokes them over HTTP', async () => {
   // Use a relative import so the scaffolded module can find webjs via the workspace.
   const dir = await scaffold({
-    'actions/math.server.js': `
+    'actions/math.server.js': `'use server';
       import { expose } from '@webjskit/core';
       export const add = expose('POST /api/add', async ({ a, b }) => a + b);
       export const get = expose('GET /api/value/:id', async ({ id }) => ({ id: Number(id) }));
@@ -99,7 +99,7 @@ test('action scanner discovers expose()d routes and invokes them over HTTP', asy
 
 test('validate hook rejects bad input with 400 before handler runs', async () => {
   const dir = await scaffold({
-    'actions/guarded.server.js': `
+    'actions/guarded.server.js': `'use server';
       import { expose } from '@webjskit/core';
       let called = 0;
       export const make = expose(