@valbuild/server 0.130.0 → 0.132.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @valbuild/server
 
+## 0.132.0
+
+### Minor Changes
+
+- [#689](https://github.com/valbuild/val/pull/689) [`72cc676`](https://github.com/valbuild/val/commit/72cc6765e92a6e72b5c09ddd9eed8efa7ce899f2) Thanks [@freekh](https://github.com/freekh)! - `VAL_ENV=app` selects `http` mode.
+
+  A host knows WHERE it is running; which Val mode that implies is Val's to
+  derive. `VAL_ENV=app` says "this is the Val app" — a project built in a browser
+  and served from a Worker isolate — and Val reads that as http mode: there is no
+  disk, so `fs` is never the right fall-through, and the content is Val's own,
+  read over HTTP at a commit like any other deployed app.
+
+  Unlike `VAL_MODE=memory`, this **selects** the mode rather than only refusing a
+  fall-through, because everything http mode needs is an environment variable. The
+  point is what happens when one is missing: inference reads an absent
+  `VAL_API_KEY` as "not a proxy" and resolves `fs` mode, which in an isolate fails
+  on `.val/patches.lock` — a path, two layers below the actual mistake. Now each
+  of `VAL_API_KEY`, `VAL_SECRET`, `VAL_PROJECT`, `VAL_GIT_COMMIT` and
+  `VAL_GIT_BRANCH` is named when it is the one that is not set, and the message
+  says which variable put the app in http mode.
+
+  An explicit `VAL_MODE` still wins, including when it is a typo that has to be
+  refused, and `http` is still not a value `VAL_MODE` accepts. A host that passes
+  `sourceFiles` still gets memory mode: that is checked before the environment is
+  consulted at all, so a build published by an older platform keeps working.
+
+## 0.131.0
+
+### Minor Changes
+
+- [#686](https://github.com/valbuild/val/pull/686) [`0d5857b`](https://github.com/valbuild/val/commit/0d5857b731e11f7e6a011f79297df6485908c31f) Thanks [@freekh](https://github.com/freekh)! - Say `VAL_MODE=memory` where there is no disk, and get a sentence instead of an `EPERM`
+
+  Memory mode — the one for a host that holds the project's source itself — is
+  selected by passing `sourceFiles`, and it has to be: nothing in an environment
+  can supply a project's source, so a mode that an env var could switch on would
+  be a server with no content in it.
+
+  The cost was the failure when a host forgot. Val inferred `fs` mode, `fs` mode
+  went looking for a working tree, and in a Worker isolate the first thing to
+  touch the disk failed:
+
+  ```
+  patch-error /bundle/.val/patches.lock: EPERM
+  ```
+
+  That names a path two layers below the decision that caused it, and nobody
+  reading it would guess "your server was configured for the wrong mode".
+
+  So an environment can now DECLARE that it has no disk:
+
+  ```
+  VAL_MODE=memory
+  ```
+
+  It does not turn memory mode on. It says the host is supposed to be supplying
+  `sourceFiles`, so if none arrive, Val refuses at configuration time and says
+  where to pass them. `VAL_MODE=` counts as unset, the way a shell means it; any
+  other value is refused rather than ignored, since leaving you in `fs` mode is
+  the exact failure this is meant to catch.
+
+  **`initValContent` takes the same options, and this is the release that
+  noticed.** It builds a Val server of its own — these readers resolve content by
+  asking it, not by calling the API over HTTP — so configuring `initValServer`
+  alone left them inferring `fs` mode. On a host with no filesystem that is a
+  reader looking for a working tree that is not there; it went unnoticed because
+  published reads still worked.
+
+  ```ts
+  const patchStore = new InMemoryPatchStore(); // now exported from this package
+
+  const { valApiHandler, draftMode } = initValServer(valModules, config, {
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+
+  const { fetchValStega } = initValContent(config, valModules, {
+    draftMode,
+    // The same three. Two patch stores are two sets of pending edits, and a
+    // reader that checks a session the host never issues answers itself 401 and
+    // falls back to published content — a draft render showing the live site.
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+  ```
+
+  All three are optional. Left out, this reader gets its own store and its own
+  answer about authentication, which is right for published content.
+
+  `@valbuild/next` has no memory mode: its `initValServer` takes neither option,
+  so for a Next app `VAL_MODE=memory` names an environment Val cannot serve from,
+  and the error says so.
+
+  Nothing changes for an app that sets none of this: `http` when `VAL_API_KEY`
+  and `VAL_SECRET` are both present, `fs` otherwise, as before.
+
 ## 0.130.0
 
 ### Minor Changes

package/dist/declarations/src/ValRouter.d.ts

@@ -61,6 +61,11 @@ type ValServerOverrides = Partial<{
      * and "proxy" this one cannot be inferred from the environment -- there is
      * nothing to infer it FROM, and a mode that can be turned on without
      * supplying the source would be a server with no content in it.
+     *
+     * An environment that has no disk can still say it EXPECTS this, by setting
+     * `VAL_MODE=memory`. That does not select the mode; it makes forgetting to
+     * pass the source an error here rather than an `EPERM` from `fs` mode two
+     * layers down.
      */
     sourceFiles: Record<string, string>;
     /**

package/dist/valbuild-server.cjs.dev.js

@@ -10051,6 +10051,67 @@ function parsePersonalAccessTokenFile(content) {
 
 const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
 
+/**
+ * The value of `VAL_ENV` that means "this is the Val app".
+ *
+ * The Val app builds a project in a browser and runs it in a Worker isolate.
+ * There is no disk there and there never will be, so `fs` mode is never the
+ * right fall-through -- and the content is Val's own, reached over HTTP at a
+ * commit, exactly as it is for any other deployed app. So this names `http`.
+ *
+ * What makes the app unusual is not where its content comes from but what
+ * publishing means: the browser rebuilds the site and the new build is served
+ * immediately, instead of a host noticing a commit and redeploying. That is a
+ * difference in what happens AFTER the commit, and `publishOverride` is where
+ * a host says so -- not a difference in where patches, files or sources live.
+ *
+ * A host says WHERE it runs, which is a fact it knows. Which Val mode that
+ * implies is Val's to derive, and that is the whole reason this exists next to
+ * `VAL_MODE` rather than the platform naming a mode itself: one is a
+ * description of an environment, the other an assertion about Val's internals,
+ * and only the first stays true when the internals move. They have already
+ * moved once -- this meant `memory` while the app kept its own patch store --
+ * and no platform had to be changed to follow.
+ */
+const VAL_APP_ENV = "app";
+
+/** Which mode the environment SAYS this is, and which variable said so. */
+
+/**
+ * `null` is "the environment did not say", which is the normal case.
+ *
+ * The two variables differ in what can be DONE with an answer, and the
+ * difference is whether the environment holds everything the mode needs.
+ * `http` does -- an api key, a secret, a project, a commit and a branch are all
+ * env vars -- so `VAL_ENV=app` SELECTS it, and the checks in
+ * {@link initHandlerOptions} name whichever one is missing. `memory` does not:
+ * it needs the host's own source files, which nothing in an environment can
+ * supply, so `VAL_MODE=memory` can only ever turn a fall-through into an error.
+ */
+function namedMode() {
+  const declared = process.env.VAL_MODE;
+  /*
+   * An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+   * CI settings page means. An explicit `VAL_MODE` otherwise wins over
+   * `VAL_ENV`: naming a mode outright says something more specific than naming
+   * an environment does, including when what it names is wrong and has to be
+   * refused.
+   */
+  if (declared !== undefined && declared !== "") {
+    return {
+      mode: declared,
+      from: "VAL_MODE"
+    };
+  }
+  if (process.env.VAL_ENV === VAL_APP_ENV) {
+    return {
+      mode: "http",
+      from: "VAL_ENV"
+    };
+  }
+  return null;
+}
+
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *
@@ -10103,9 +10164,53 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * The environment saying 'memory' means the host MEANT to hold the source,
+   * and did not. Either variable can say it: `VAL_MODE=memory` outright, or
+   * `VAL_ENV=app`, which names an environment that has no disk.
+   *
+   * Neither can SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What they do is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declared = namedMode();
+  if ((declared === null || declared === void 0 ? void 0 : declared.mode) === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset VAL_MODE to go back to the inferred mode instead " + "('http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' " + "otherwise).");
+  }
+  /*
+   * Every other value is refused rather than ignored: ignoring `VAL_MODE=memry`
+   * would leave the app in `fs` mode, which is the exact failure this variable
+   * exists to catch.
+   *
+   * `VAL_ENV` is excluded by name rather than by its value happening to pass:
+   * it names 'http', which is selected below, and a reader who sees only
+   * `declared !== null` here would reasonably conclude that 'http' is a
+   * `VAL_MODE` value -- it is not, and the message below says so.
+   */
+  if (declared !== null && declared.from === "VAL_MODE") {
+    throw new Error(`VAL_MODE is '${declared.mode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
-  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
+  /*
+   * The app's environment selects http mode, rather than leaving it to be
+   * inferred from a credential being present.
+   *
+   * The difference shows when something is MISSING. Inference reads an absent
+   * api key as "not a proxy" and falls through to `fs`, which in an isolate
+   * reaches for a working tree that is not there -- an `EPERM` on
+   * `.val/patches.lock`, several layers below the mistake. Selecting the mode
+   * means the checks below run instead, and each one names what it wanted.
+   */
+  const isAppEnv = (declared === null || declared === void 0 ? void 0 : declared.from) === "VAL_ENV";
+  const isProxyMode = opts.mode === "proxy" || isAppEnv || opts.mode === undefined && (maybeApiKey || maybeValSecret);
   const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
   const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
   const maybeValProject = opts.project || process.env.VAL_PROJECT;
@@ -10117,19 +10222,28 @@ async function initHandlerOptions(route, opts, config) {
   });
   if (isProxyMode) {
     var _opts$versions, _opts$versions2;
+    /*
+     * Why this app is in http mode, in the message that says what is missing.
+     *
+     * "must be set in proxy mode" is a fine sentence for a developer who wrote
+     * `mode: "proxy"` and a poor one for an app that never mentioned a mode:
+     * there, the answer to "why am I in proxy mode?" is a variable set by the
+     * platform, in a file the reader of this error is not looking at.
+     */
+    const because = isAppEnv ? " (VAL_ENV is 'app', which is the Val app: its content is Val's own " + "and is read over HTTP at a commit, so http mode is the mode and " + "these are what it needs)" : "";
     if (!maybeApiKey || !maybeValSecret) {
-      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
+      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode" + because);
     }
     const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
     if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
+      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode" + because);
     }
     const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
     if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
+      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode" + because);
     }
     if (!maybeValProject) {
-      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
+      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
     }
     const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
     if (!coreVersion) {

package/dist/valbuild-server.cjs.prod.js

@@ -10051,6 +10051,67 @@ function parsePersonalAccessTokenFile(content) {
 
 const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
 
+/**
+ * The value of `VAL_ENV` that means "this is the Val app".
+ *
+ * The Val app builds a project in a browser and runs it in a Worker isolate.
+ * There is no disk there and there never will be, so `fs` mode is never the
+ * right fall-through -- and the content is Val's own, reached over HTTP at a
+ * commit, exactly as it is for any other deployed app. So this names `http`.
+ *
+ * What makes the app unusual is not where its content comes from but what
+ * publishing means: the browser rebuilds the site and the new build is served
+ * immediately, instead of a host noticing a commit and redeploying. That is a
+ * difference in what happens AFTER the commit, and `publishOverride` is where
+ * a host says so -- not a difference in where patches, files or sources live.
+ *
+ * A host says WHERE it runs, which is a fact it knows. Which Val mode that
+ * implies is Val's to derive, and that is the whole reason this exists next to
+ * `VAL_MODE` rather than the platform naming a mode itself: one is a
+ * description of an environment, the other an assertion about Val's internals,
+ * and only the first stays true when the internals move. They have already
+ * moved once -- this meant `memory` while the app kept its own patch store --
+ * and no platform had to be changed to follow.
+ */
+const VAL_APP_ENV = "app";
+
+/** Which mode the environment SAYS this is, and which variable said so. */
+
+/**
+ * `null` is "the environment did not say", which is the normal case.
+ *
+ * The two variables differ in what can be DONE with an answer, and the
+ * difference is whether the environment holds everything the mode needs.
+ * `http` does -- an api key, a secret, a project, a commit and a branch are all
+ * env vars -- so `VAL_ENV=app` SELECTS it, and the checks in
+ * {@link initHandlerOptions} name whichever one is missing. `memory` does not:
+ * it needs the host's own source files, which nothing in an environment can
+ * supply, so `VAL_MODE=memory` can only ever turn a fall-through into an error.
+ */
+function namedMode() {
+  const declared = process.env.VAL_MODE;
+  /*
+   * An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+   * CI settings page means. An explicit `VAL_MODE` otherwise wins over
+   * `VAL_ENV`: naming a mode outright says something more specific than naming
+   * an environment does, including when what it names is wrong and has to be
+   * refused.
+   */
+  if (declared !== undefined && declared !== "") {
+    return {
+      mode: declared,
+      from: "VAL_MODE"
+    };
+  }
+  if (process.env.VAL_ENV === VAL_APP_ENV) {
+    return {
+      mode: "http",
+      from: "VAL_ENV"
+    };
+  }
+  return null;
+}
+
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *
@@ -10103,9 +10164,53 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * The environment saying 'memory' means the host MEANT to hold the source,
+   * and did not. Either variable can say it: `VAL_MODE=memory` outright, or
+   * `VAL_ENV=app`, which names an environment that has no disk.
+   *
+   * Neither can SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What they do is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declared = namedMode();
+  if ((declared === null || declared === void 0 ? void 0 : declared.mode) === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset VAL_MODE to go back to the inferred mode instead " + "('http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' " + "otherwise).");
+  }
+  /*
+   * Every other value is refused rather than ignored: ignoring `VAL_MODE=memry`
+   * would leave the app in `fs` mode, which is the exact failure this variable
+   * exists to catch.
+   *
+   * `VAL_ENV` is excluded by name rather than by its value happening to pass:
+   * it names 'http', which is selected below, and a reader who sees only
+   * `declared !== null` here would reasonably conclude that 'http' is a
+   * `VAL_MODE` value -- it is not, and the message below says so.
+   */
+  if (declared !== null && declared.from === "VAL_MODE") {
+    throw new Error(`VAL_MODE is '${declared.mode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
-  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
+  /*
+   * The app's environment selects http mode, rather than leaving it to be
+   * inferred from a credential being present.
+   *
+   * The difference shows when something is MISSING. Inference reads an absent
+   * api key as "not a proxy" and falls through to `fs`, which in an isolate
+   * reaches for a working tree that is not there -- an `EPERM` on
+   * `.val/patches.lock`, several layers below the mistake. Selecting the mode
+   * means the checks below run instead, and each one names what it wanted.
+   */
+  const isAppEnv = (declared === null || declared === void 0 ? void 0 : declared.from) === "VAL_ENV";
+  const isProxyMode = opts.mode === "proxy" || isAppEnv || opts.mode === undefined && (maybeApiKey || maybeValSecret);
   const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
   const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
   const maybeValProject = opts.project || process.env.VAL_PROJECT;
@@ -10117,19 +10222,28 @@ async function initHandlerOptions(route, opts, config) {
   });
   if (isProxyMode) {
     var _opts$versions, _opts$versions2;
+    /*
+     * Why this app is in http mode, in the message that says what is missing.
+     *
+     * "must be set in proxy mode" is a fine sentence for a developer who wrote
+     * `mode: "proxy"` and a poor one for an app that never mentioned a mode:
+     * there, the answer to "why am I in proxy mode?" is a variable set by the
+     * platform, in a file the reader of this error is not looking at.
+     */
+    const because = isAppEnv ? " (VAL_ENV is 'app', which is the Val app: its content is Val's own " + "and is read over HTTP at a commit, so http mode is the mode and " + "these are what it needs)" : "";
     if (!maybeApiKey || !maybeValSecret) {
-      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
+      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode" + because);
     }
     const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
     if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
+      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode" + because);
     }
     const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
     if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
+      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode" + because);
     }
     if (!maybeValProject) {
-      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
+      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
     }
     const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
     if (!coreVersion) {

package/dist/valbuild-server.esm.js

@@ -10017,6 +10017,67 @@ function parsePersonalAccessTokenFile(content) {
 
 const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
 
+/**
+ * The value of `VAL_ENV` that means "this is the Val app".
+ *
+ * The Val app builds a project in a browser and runs it in a Worker isolate.
+ * There is no disk there and there never will be, so `fs` mode is never the
+ * right fall-through -- and the content is Val's own, reached over HTTP at a
+ * commit, exactly as it is for any other deployed app. So this names `http`.
+ *
+ * What makes the app unusual is not where its content comes from but what
+ * publishing means: the browser rebuilds the site and the new build is served
+ * immediately, instead of a host noticing a commit and redeploying. That is a
+ * difference in what happens AFTER the commit, and `publishOverride` is where
+ * a host says so -- not a difference in where patches, files or sources live.
+ *
+ * A host says WHERE it runs, which is a fact it knows. Which Val mode that
+ * implies is Val's to derive, and that is the whole reason this exists next to
+ * `VAL_MODE` rather than the platform naming a mode itself: one is a
+ * description of an environment, the other an assertion about Val's internals,
+ * and only the first stays true when the internals move. They have already
+ * moved once -- this meant `memory` while the app kept its own patch store --
+ * and no platform had to be changed to follow.
+ */
+const VAL_APP_ENV = "app";
+
+/** Which mode the environment SAYS this is, and which variable said so. */
+
+/**
+ * `null` is "the environment did not say", which is the normal case.
+ *
+ * The two variables differ in what can be DONE with an answer, and the
+ * difference is whether the environment holds everything the mode needs.
+ * `http` does -- an api key, a secret, a project, a commit and a branch are all
+ * env vars -- so `VAL_ENV=app` SELECTS it, and the checks in
+ * {@link initHandlerOptions} name whichever one is missing. `memory` does not:
+ * it needs the host's own source files, which nothing in an environment can
+ * supply, so `VAL_MODE=memory` can only ever turn a fall-through into an error.
+ */
+function namedMode() {
+  const declared = process.env.VAL_MODE;
+  /*
+   * An empty value counts as unset, which is what `VAL_MODE=` in a shell or a
+   * CI settings page means. An explicit `VAL_MODE` otherwise wins over
+   * `VAL_ENV`: naming a mode outright says something more specific than naming
+   * an environment does, including when what it names is wrong and has to be
+   * refused.
+   */
+  if (declared !== undefined && declared !== "") {
+    return {
+      mode: declared,
+      from: "VAL_MODE"
+    };
+  }
+  if (process.env.VAL_ENV === VAL_APP_ENV) {
+    return {
+      mode: "http",
+      from: "VAL_ENV"
+    };
+  }
+  return null;
+}
+
 /**
  * Resolve options plus environment into a concrete {@link ValServerConfig}.
  *
@@ -10069,9 +10130,53 @@ async function initHandlerOptions(route, opts, config) {
       config
     };
   }
+  /*
+   * The environment saying 'memory' means the host MEANT to hold the source,
+   * and did not. Either variable can say it: `VAL_MODE=memory` outright, or
+   * `VAL_ENV=app`, which names an environment that has no disk.
+   *
+   * Neither can SELECT memory mode -- nothing in the environment can supply
+   * `sourceFiles`, and a mode turned on without them is a server with no
+   * content in it. What they do is turn the fall-through into an error.
+   *
+   * Without it, a host that forgot to pass its source got `fs` mode, and `fs`
+   * mode in a Worker isolate reaches for a working tree that is not there: the
+   * failure is an `EPERM` on `.val/patches.lock`, several layers below the
+   * mistake, naming a path rather than the decision that led to it. Every
+   * environment that runs Val without a disk can set this once and get a
+   * sentence instead.
+   */
+  const declared = namedMode();
+  if ((declared === null || declared === void 0 ? void 0 : declared.mode) === "memory") {
+    throw new Error("VAL_MODE is 'memory', but no `sourceFiles` were given here, so there " + "is no source to serve. Memory mode cannot be turned on by the " + "environment: it needs the project's own source, and only the host " + "that holds it can hand it over. On TanStack Start that is the " + "`sourceFiles` option, passed to `initValServer` AND to " + "`initValContent`, which has a Val server of its own and is " + "configured separately. @valbuild/next has no memory mode yet, so " + "for a Next app this variable is set on an environment Val cannot " + "serve from. Unset VAL_MODE to go back to the inferred mode instead " + "('http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' " + "otherwise).");
+  }
+  /*
+   * Every other value is refused rather than ignored: ignoring `VAL_MODE=memry`
+   * would leave the app in `fs` mode, which is the exact failure this variable
+   * exists to catch.
+   *
+   * `VAL_ENV` is excluded by name rather than by its value happening to pass:
+   * it names 'http', which is selected below, and a reader who sees only
+   * `declared !== null` here would reasonably conclude that 'http' is a
+   * `VAL_MODE` value -- it is not, and the message below says so.
+   */
+  if (declared !== null && declared.from === "VAL_MODE") {
+    throw new Error(`VAL_MODE is '${declared.mode}', which is not a mode Val knows. The only ` + "value it accepts is 'memory', which asserts that the host supplies " + "`sourceFiles`. 'fs' and 'http' are inferred rather than named: " + "'http' when VAL_API_KEY and VAL_SECRET are both set, 'fs' otherwise.");
+  }
   const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
   const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
-  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
+  /*
+   * The app's environment selects http mode, rather than leaving it to be
+   * inferred from a credential being present.
+   *
+   * The difference shows when something is MISSING. Inference reads an absent
+   * api key as "not a proxy" and falls through to `fs`, which in an isolate
+   * reaches for a working tree that is not there -- an `EPERM` on
+   * `.val/patches.lock`, several layers below the mistake. Selecting the mode
+   * means the checks below run instead, and each one names what it wanted.
+   */
+  const isAppEnv = (declared === null || declared === void 0 ? void 0 : declared.from) === "VAL_ENV";
+  const isProxyMode = opts.mode === "proxy" || isAppEnv || opts.mode === undefined && (maybeApiKey || maybeValSecret);
   const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
   const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
   const maybeValProject = opts.project || process.env.VAL_PROJECT;
@@ -10083,19 +10188,28 @@ async function initHandlerOptions(route, opts, config) {
   });
   if (isProxyMode) {
     var _opts$versions, _opts$versions2;
+    /*
+     * Why this app is in http mode, in the message that says what is missing.
+     *
+     * "must be set in proxy mode" is a fine sentence for a developer who wrote
+     * `mode: "proxy"` and a poor one for an app that never mentioned a mode:
+     * there, the answer to "why am I in proxy mode?" is a variable set by the
+     * platform, in a file the reader of this error is not looking at.
+     */
+    const because = isAppEnv ? " (VAL_ENV is 'app', which is the Val app: its content is Val's own " + "and is read over HTTP at a commit, so http mode is the mode and " + "these are what it needs)" : "";
     if (!maybeApiKey || !maybeValSecret) {
-      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
+      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode" + because);
     }
     const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
     if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
+      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode" + because);
     }
     const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
     if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
+      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode" + because);
     }
     if (!maybeValProject) {
-      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
+      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
     }
     const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
     if (!coreVersion) {

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.130.0",
+  "version": "0.132.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/shared": "0.130.0",
     "@valbuild/core": "0.130.0",
-    "@valbuild/ui": "0.130.0"
+    "@valbuild/ui": "0.130.0",
+    "@valbuild/shared": "0.130.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22"