@valbuild/server 0.120.0 → 0.120.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @valbuild/server
 
+## 0.120.1
+
+### Patch Changes
+
+- [#590](https://github.com/valbuild/val/pull/590) [`6f318d4`](https://github.com/valbuild/val/commit/6f318d406295b772e721bf463283f47e2822e996) Thanks [@freekh](https://github.com/freekh)! - MCP: survive a signing-key rotation, and say what a refused local token means.
+
+  `@valbuild/next` caches the authorization server's JWKS for five minutes. Until
+  now a token signed with a key that arrived inside that window was refused
+  outright, so every warm instance rejected valid tokens until the cache expired —
+  a rotation on the issuer's side showed up as an outage on yours.
+
+  A token naming a key the cache does not hold now provokes one refetch of the key
+  set, at most once per issuer every 30 seconds. The rate limit matters because the
+  key id comes from the token: without it, unknown key ids would be a way to make
+  your app call its issuer once per request. It limits how often a fetch is
+  _started_, so requests that arrive while one is already running join it — which
+  is the normal shape of a rotation, where many requests meet the new key at once.
+
+  Separately, an MCP call that presents an access token to a project running in
+  local filesystem mode is still refused — there is nothing to authenticate against
+  — but the message now names the cause, which is that the project has an `oauth`
+  issuer configured (often `VAL_OAUTH_ISSUER` in a local `.env`) and should not
+  have one for local development.
+
 ## 0.120.0
 
 ### Patch Changes

package/dist/declarations/src/tools/createValTools.d.ts

@@ -1,6 +1,8 @@
 import type { ValModules } from "@valbuild/core";
 import type { ValServerConfig } from "../ValServer.js";
-import { type ValTools } from "./types.js";
+import type { ValOps } from "../ValOps.js";
+import type { ValToolState } from "./defineTool.js";
+import { type ValToolResult, type ValTools } from "./types.js";
 export type ValToolsOptions = ValServerConfig;
 /**
  * Val's server-side tool registry.
@@ -15,3 +17,25 @@ export type ValToolsOptions = ValServerConfig;
  * host adapts {@link ValToolResult} at its own edge.
  */
 export declare function createValTools(valModules: ValModules, options: ValToolsOptions): ValTools;
+/**
+ * The content as the caller should see it, loaded once per call.
+ *
+ * Pending patches are applied, because an agent looking at a project mid-edit
+ * should see what the Studio would show rather than the last published state.
+ *
+ * Deliberately not cached across calls. In fs mode a save recomputes the base
+ * sha within the same process, so a cached view would go stale silently — and
+ * the cost of being wrong here is an agent writing a patch against content that
+ * has already moved.
+ *
+ * Exported for `toolsFixture`, not for consumers: `tools/index.ts` re-exports by
+ * name, so this stays inside the package. A test that assembled its own state
+ * would be asserting against a view no real call ever sees.
+ */
+export declare function loadState(ops: ValOps): Promise<{
+    status: "ok";
+    state: ValToolState;
+} | {
+    status: "error";
+    result: ValToolResult;
+}>;

package/dist/declarations/src/tools/defineTool.d.ts

@@ -0,0 +1,69 @@
+import type { Json, ModuleFilePath, PatchId, SerializedSchema } from "@valbuild/core";
+import type { z } from "zod";
+import type { ValOps, OrderedPatches, PatchAnalysis, Schemas, Sources } from "../ValOps.js";
+import type { ValToolContext, ValToolDefinition, ValToolErrorCode, ValToolResult } from "./types.js";
+/**
+ * How a tool is written, and what it is handed.
+ *
+ * Tools are defined with {@link defineTool} so that the handler's `args` are
+ * inferred from the tool's own `inputSchema`. Without that the array of tools
+ * would have to be typed at its widest and every handler would start by
+ * re-narrowing `unknown`, which is exactly where a tool and its schema drift
+ * apart unnoticed.
+ */
+/** Everything a tool is allowed to reach. Deliberately narrow. */
+export type ValToolDeps = {
+    /**
+     * The data layer for *this call*. In proxy mode it is authenticated as the
+     * caller, so a tool must never reach for an ambient instance instead.
+     */
+    ops: ValOps;
+    ctx: ValToolContext;
+    /**
+     * The content as the caller should see it: base sources with pending patches
+     * applied, plus the schemas and the patch analysis that produced them.
+     *
+     * Loaded once per call and shared, because a tool that re-derived it would
+     * both pay for it again and risk reading a different revision than the one it
+     * validated against.
+     */
+    state: ValToolState;
+};
+export type ValToolState = {
+    schemas: Schemas;
+    serializedSchemas: Record<ModuleFilePath, SerializedSchema>;
+    sources: Sources;
+    patches: OrderedPatches;
+    analysis: PatchAnalysis;
+    /**
+     * Pending patches that would not apply, by the module they belong to.
+     *
+     * A module listed here has `sources` that silently lack those changes, so its
+     * content is not what publishing would produce. Reads still return it — it is
+     * what the Studio would show too, and a project has to stay diagnosable — but
+     * a write to such a module is refused, because it would be based on a state
+     * that does not exist.
+     */
+    unappliedPatches: Record<ModuleFilePath, {
+        patchId: PatchId;
+        skipped: boolean;
+        error: {
+            message: string;
+        };
+    }[]>;
+};
+export type ValToolImpl = ValToolDefinition & {
+    handler: (args: unknown, deps: ValToolDeps) => Promise<ValToolResult>;
+};
+/**
+ * Declare a tool, binding its handler to its input schema.
+ *
+ * The handler receives already-parsed arguments: the registry validates against
+ * `inputSchema` before calling, so a handler never sees input its schema would
+ * have rejected.
+ */
+export declare function defineTool<S extends z.ZodType>(definition: Omit<ValToolDefinition, "inputSchema"> & {
+    inputSchema: S;
+}, handler: (args: z.infer<S>, deps: ValToolDeps) => Promise<ValToolResult>): ValToolImpl;
+export declare function ok(data: Json): ValToolResult;
+export declare function err(code: ValToolErrorCode, message: string): ValToolResult;

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

@@ -11935,12 +11935,19 @@ function createOpsResolver(valModules, options) {
         // credential should not silently get local filesystem access instead —
         // and the difference matters, because fs mode writes straight to disk
         // with no backend permission check at all.
+        //
+        // The two credentials get different messages because they arrive here
+        // for different reasons. A PAT is something the caller chose to send. A
+        // verified access token is not: it only exists because this app
+        // advertised an authorization server, so the developer seeing this did
+        // not do anything wrong — a config file did, and naming it is the
+        // difference between a two-minute fix and an afternoon.
         return {
           status: "error",
           result: {
             status: "error",
             code: "unsupported",
-            message: "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
+            message: ctx.auth.type === "verified-profile" ? "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development." : "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
           }
         };
       }
@@ -12036,6 +12043,10 @@ function createOpsResolver(valModules, options) {
  * sha within the same process, so a cached view would go stale silently — and
  * the cost of being wrong here is an agent writing a patch against content that
  * has already moved.
+ *
+ * Exported for `toolsFixture`, not for consumers: `tools/index.ts` re-exports by
+ * name, so this stays inside the package. A test that assembled its own state
+ * would be asserting against a view no real call ever sees.
  */
 async function loadState(ops) {
   const patches = await ops.fetchPatches({

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

@@ -11935,12 +11935,19 @@ function createOpsResolver(valModules, options) {
         // credential should not silently get local filesystem access instead —
         // and the difference matters, because fs mode writes straight to disk
         // with no backend permission check at all.
+        //
+        // The two credentials get different messages because they arrive here
+        // for different reasons. A PAT is something the caller chose to send. A
+        // verified access token is not: it only exists because this app
+        // advertised an authorization server, so the developer seeing this did
+        // not do anything wrong — a config file did, and naming it is the
+        // difference between a two-minute fix and an afternoon.
         return {
           status: "error",
           result: {
             status: "error",
             code: "unsupported",
-            message: "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
+            message: ctx.auth.type === "verified-profile" ? "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development." : "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
           }
         };
       }
@@ -12036,6 +12043,10 @@ function createOpsResolver(valModules, options) {
  * sha within the same process, so a cached view would go stale silently — and
  * the cost of being wrong here is an agent writing a patch against content that
  * has already moved.
+ *
+ * Exported for `toolsFixture`, not for consumers: `tools/index.ts` re-exports by
+ * name, so this stays inside the package. A test that assembled its own state
+ * would be asserting against a view no real call ever sees.
  */
 async function loadState(ops) {
   const patches = await ops.fetchPatches({

package/dist/valbuild-server.esm.js

@@ -11901,12 +11901,19 @@ function createOpsResolver(valModules, options) {
         // credential should not silently get local filesystem access instead —
         // and the difference matters, because fs mode writes straight to disk
         // with no backend permission check at all.
+        //
+        // The two credentials get different messages because they arrive here
+        // for different reasons. A PAT is something the caller chose to send. A
+        // verified access token is not: it only exists because this app
+        // advertised an authorization server, so the developer seeing this did
+        // not do anything wrong — a config file did, and naming it is the
+        // difference between a two-minute fix and an afternoon.
         return {
           status: "error",
           result: {
             status: "error",
             code: "unsupported",
-            message: "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
+            message: ctx.auth.type === "verified-profile" ? "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development." : "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
           }
         };
       }
@@ -12002,6 +12009,10 @@ function createOpsResolver(valModules, options) {
  * sha within the same process, so a cached view would go stale silently — and
  * the cost of being wrong here is an agent writing a patch against content that
  * has already moved.
+ *
+ * Exported for `toolsFixture`, not for consumers: `tools/index.ts` re-exports by
+ * name, so this stays inside the package. A test that assembled its own state
+ * would be asserting against a view no real call ever sees.
  */
 async function loadState(ops) {
   const patches = await ops.fetchPatches({

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.120.0",
+  "version": "0.120.1",
   "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.120.0",
     "@valbuild/core": "0.120.0",
-    "@valbuild/ui": "0.120.0"
+    "@valbuild/ui": "0.120.0",
+    "@valbuild/shared": "0.120.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22"