@valbuild/server 0.115.0 → 0.117.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# @valbuild/server
+
+## 0.117.0
+
+### Minor Changes
+
+- [#582](https://github.com/valbuild/val/pull/582) [`fca3efa`](https://github.com/valbuild/val/commit/fca3efa389e2817401f55ea3dd184af7c611b807) Thanks [@freekh](https://github.com/freekh)! - Accept OAuth access tokens on the MCP endpoint, so editors can authorize as themselves
+
+  `initValMcp` takes an optional `oauth` config. Give it the authorization server's
+  URL and this endpoint's own URL, and every MCP call must then present an access
+  token that Val's authorization server issued:
+
+  ```ts
+  const { valMcpAuthorize, valMcpTools, valMcpMetadata } = initValMcp(
+    valModules,
+    config,
+    {
+      oauth: {
+        issuer: "https://admin.val.build",
+        resource: "https://your-app.com/api/mcp",
+      },
+    },
+  );
+  ```
+
+  The token is verified in your app — signature against the issuer's published
+  keys, plus issuer, audience and expiry — so the caller's identity is checked
+  rather than claimed. **Patches created over MCP now carry that profile as their
+  author**, which is what makes an edit made from a phone show up in the review
+  screen as somebody's rather than nobody's. Scopes are enforced too: a token
+  without `val:write` cannot reach a tool that writes.
+
+  Mount the discovery document so clients can find where to authorize:
+
+  ```ts
+  // app/.well-known/oauth-protected-resource/route.ts
+  import { valMcpMetadata } from "../../../val/mcp";
+  export const { GET, OPTIONS } = valMcpMetadata!;
+  ```
+
+  `valMcpMetadata` is `null` when no `oauth` config is given.
+
+  **Nothing changes if you leave `oauth` out.** Local development still works with
+  no authorization server, and an app already using a personal access token keeps
+  working as before.
+
+  One breaking change if you built your own host on `createValTools`:
+  `ValToolContext.auth` is now a tagged union, so `{ pat }` becomes
+  `{ type: "pat", pat }`. The new variant is
+  `{ type: "verified-profile", profileId, scopes }`, for a host that verified a
+  token itself.
+
+### Patch Changes
+
+- [#579](https://github.com/valbuild/val/pull/579) [`b2812ae`](https://github.com/valbuild/val/commit/b2812ae4ee03e005ecead3365f49c625e536f94d) Thanks [@freekh](https://github.com/freekh)! - Every release now ships a changelog. Each package's `CHANGELOG.md` records what
+  changed under the version that shipped it — with a link to the pull request, the
+  commit and the author — and the same entry becomes the body of the GitHub
+  Release for the tag. The file is included in the npm tarball, so it is also
+  readable from an installed copy.
+
+  Up to now those changelogs were generated empty, and the GitHub Releases with
+  them, so there was no record of what any given version contained. Releases from
+  this one on have one; earlier versions stay blank.
+
+- Updated dependencies [[`d94a40f`](https://github.com/valbuild/val/commit/d94a40f8bd11027636d183e293aced820b6f341f), [`b2812ae`](https://github.com/valbuild/val/commit/b2812ae4ee03e005ecead3365f49c625e536f94d)]:
+  - @valbuild/core@0.117.0
+  - @valbuild/shared@0.117.0
+  - @valbuild/ui@0.117.0

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

@@ -114,32 +114,6 @@ type ValServerOverrides = Partial<{
     disableCache?: boolean;
 }>;
 export declare function createValServer(valModules: ValModules, route: string, opts: ValApiOptions, config: ValConfig, callbacks: ValServerCallbacks, formatter?: (code: string, filePath: string) => string | Promise<string>): Promise<ValServer>;
-/**
- * Hosts we send credentials to, and what each one puts at risk. They differ:
- * only `valBuildUrl` hands back the app token that becomes the session cookie,
- * so a single shared sentence would overstate one and understate the other.
- */
-type CredentialBearingUrl = "valBuildUrl" | "valContentUrl";
-/**
- * Returns a warning if `url` would send credentials somewhere they can be read
- * off the wire, or null if it is fine.
- *
- * Both URLs default to https, but each is overridable - `opts.valBuildUrl` /
- * `VAL_BUILD_URL`, `opts.valContentUrl` / `VAL_CONTENT_URL` - and neither
- * override has ever been scheme-checked. Point one at a plain http host and the
- * api key goes out in clear text, and whatever comes back is whatever the
- * network says: for `valBuildUrl` that includes the app token this server
- * re-signs into the session cookie.
- *
- * Loopback over http is exempt: that is a val.build running on the developer's
- * own machine, and there is no network to be on the wrong side of.
- *
- * This warns rather than throws. Both overrides are set by the operator, not by
- * an attacker, so this is a misconfiguration to surface - not untrusted input to
- * reject - and refusing to boot would break anyone deliberately pointing at an
- * internal http host today.
- */
-export declare function insecureUrlWarning(name: CredentialBearingUrl, url: string): string | null;
 export declare function safeReadGit(cwd: string): Promise<{
     commit?: string;
     branch?: string;

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

@@ -5,4 +5,4 @@ import { ValidationError } from "@valbuild/core";
  * There is no schema in hand here — a `ValidationError` carries only the value
  * it flagged — so the shape is all there is to go on.
  */
-export declare function getValidationErrorFileRef(validationError: ValidationError): any;
+export declare function getValidationErrorFileRef(validationError: ValidationError): string | null;

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

@@ -1,5 +1,9 @@
 export { createService, Service } from "./Service.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
+export { createValTools } from "./tools/index.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, ValToolsOptions, } from "./tools/index.js";
+export { initHandlerOptions, createValOps } from "./valServerConfig.js";
 export { ValModuleLoader } from "./ValModuleLoader.js";
 export { getCompilerOptions } from "./getCompilerOptions.js";
 export { ValSourceFileHandler } from "./ValSourceFileHandler.js";

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

@@ -1,4 +1,4 @@
-import { PatchId } from "@valbuild/core";
+import { ModuleFilePath, PatchId } from "@valbuild/core";
 import { z } from "zod";
 import type { AuthorId, BaseSha } from "./ValOps.js";
 import { PatchLogEntry, PatchLogProblem } from "./patchLog.js";
@@ -32,14 +32,14 @@ export declare const FSPatch: z.ZodObject<{
     patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         op: z.ZodLiteral<"add">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"remove">;
         path: z.ZodTuple<[z.ZodString], z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"replace">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"move">;
         from: z.ZodTuple<[z.ZodString], z.ZodString>;
@@ -51,15 +51,15 @@ export declare const FSPatch: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"test">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"file">;
         path: z.ZodArray<z.ZodString>;
         filePath: z.ZodString;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
         remote: z.ZodBoolean;
         nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        metadata: z.ZodOptional<z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>>;
+        metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
     }, z.core.$strict>], "op">>;
     patchId: z.ZodString;
     baseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;

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

@@ -0,0 +1,17 @@
+import type { ValModules } from "@valbuild/core";
+import type { ValServerConfig } from "../ValServer.js";
+import { type ValTools } from "./types.js";
+export type ValToolsOptions = ValServerConfig;
+/**
+ * Val's server-side tool registry.
+ *
+ * This is the piece Val did not have: the Studio's chat tools are defined *and
+ * executed in the browser*, against its client stores, so nothing here could be
+ * re-exposed. These tools run against {@link ValOps} instead, which is what lets
+ * an MCP server — or a stdio transport, or anything else — drive Val content
+ * without a browser.
+ *
+ * Transport-agnostic on purpose: nothing under `tools/` imports an MCP SDK. A
+ * host adapts {@link ValToolResult} at its own edge.
+ */
+export declare function createValTools(valModules: ValModules, options: ValToolsOptions): ValTools;

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

@@ -0,0 +1,3 @@
+export { createValTools, type ValToolsOptions } from "./createValTools.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./types.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, } from "./types.js";

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

@@ -0,0 +1,172 @@
+import type { AuthorId } from "../ValOps.js";
+import type { Json } from "@valbuild/core";
+import type { z } from "zod";
+/**
+ * The public surface of Val's server-side tool registry.
+ *
+ * Types only, deliberately: this file is the contract that the MCP hosts, the
+ * CLI's stdio transport and the tools themselves are all written against, and
+ * keeping it free of implementation means those can be built in any order
+ * without one of them owning the shape.
+ *
+ * The design this implements is `docs/plans/mcp.md`, Part A. Two constraints
+ * from it are load-bearing and easy to break by accident:
+ *
+ * 1. **Nothing here may import an MCP SDK.** That is what lets hosts other
+ *    than the template consume these tools, and it is not hypothetical
+ *    hygiene — the TypeScript SDK reorganised itself at v2.0.0, and a registry
+ *    coupled to it would have moved with it.
+ * 2. **The result type is deliberately not MCP's `CallToolResult`.** Each host
+ *    adapts {@link ValToolResult} at its own edge, which is also where an
+ *    error becomes an in-band `isError` result the model can recover from
+ *    rather than a transport failure.
+ */
+/** Why a tool call failed, in a form a host can map onto its own errors. */
+export type ValToolErrorCode = 
+/** No tool of that name is registered. */
+"unknown-tool"
+/** The arguments did not satisfy the tool's `inputSchema`. */
+ | "invalid-args"
+/** The path, module or key the arguments name does not exist. */
+ | "not-found"
+/** The caller is not allowed to do this — wrong credential, or none. */
+ | "forbidden"
+/**
+ * The write was rejected because applying it would leave content invalid.
+ * Nothing was stored. See `docs/plans/mcp.md` Part C on speculative
+ * validation.
+ */
+ | "validation-failed"
+/**
+ * Another writer moved the patch chain first. Callers may re-derive the
+ * parent ref and retry once; the registry does that itself before
+ * surfacing this.
+ */
+ | "conflict"
+/** The tool exists but is not available in this mode (e.g. fs vs http). */
+ | "unsupported"
+/** Anything else, including an upstream failure. */
+ | "internal";
+export type ValToolDefinition = {
+    name: string;
+    title?: string;
+    description: string;
+    /** zod v4 — a Standard Schema, which is what the MCP SDKs consume. */
+    inputSchema: z.ZodType;
+    /**
+     * MCP tool annotations. Hints, not enforcement: a host may show them to a
+     * user or use them to decide what to auto-approve, so they have to be
+     * honest about what the tool does.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+    };
+};
+/**
+ * The same definition with `inputSchema` as JSON Schema, for hosts that want the
+ * wire shape rather than a Standard Schema.
+ *
+ * Typed as whatever zod's own converter produces, so deriving it needs no cast
+ * and no second hand-written description of the same input.
+ */
+export type ValToolDefinitionJson = Omit<ValToolDefinition, "inputSchema"> & {
+    inputSchema: ReturnType<typeof z.toJSONSchema<z.ZodType>>;
+};
+/**
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
+ *
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+export type ValToolAuth = {
+    type: "pat";
+    /**
+     * The caller's PAT. Never log this, never put it in a URL, and never let
+     * it reach a tool result.
+     *
+     * Relayed to the backend as-is: this app is not the authority on what the
+     * token may do, and the backend that is decides. Nothing is derived from
+     * it here — see `docs/plans/mcp.md` D.2.
+     */
+    pat: string;
+} | {
+    type: "verified-profile";
+    /**
+     * The profile the host **verified** — the `sub` of an access token whose
+     * signature, issuer, audience and expiry were all checked against the
+     * authorization server's published key.
+     *
+     * This field is the reason this type became a union, and an earlier
+     * version of this file argued no identity field should exist at all. That
+     * argument was about a specific case and stated too broadly: an id the
+     * host *asserts* on the strength of a credential it cannot check is an
+     * unverified claim dressed as a checked one, and that is still refused —
+     * it is why the `pat` variant carries no profile. An id the host
+     * *verified* cryptographically is a different thing, and it is the same
+     * standing the Studio has when it re-signs a session it established
+     * itself.
+     */
+    profileId: AuthorId;
+    /**
+     * The token's granted scopes, as the authorization server issued them.
+     *
+     * Enforced here as well as by the backend, deliberately. Two checks on
+     * one grant is not redundancy for its own sake: this one can refuse a
+     * write before it is attempted, so a token that may only read never
+     * reaches the code that builds a patch.
+     */
+    scopes: string[];
+};
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * `null` means local fs mode, where there is no credential to hold and patches
+ * are written with no author, exactly as the Studio does locally (D.1). In
+ * proxy mode `null` is refused rather than falling back to the app's own API
+ * key: that key can do more than any single user, and quietly substituting it
+ * would turn a missing credential into full access.
+ */
+export type ValToolContext = {
+    auth: ValToolAuth | null;
+    /** Groups a run of related edits, when the host has such a notion. */
+    sessionId: string | null;
+};
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+export declare function authorIdFromVerifiedSubject(subject: string): AuthorId;
+/** Read access. Every call needs it, the writes included. */
+export declare const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+export declare const VAL_SCOPE_WRITE = "val:write";
+export type ValScope = typeof VAL_SCOPE_READ | typeof VAL_SCOPE_WRITE;
+export type ValToolResult = {
+    status: "ok";
+    data: Json;
+} | {
+    status: "error";
+    code: ValToolErrorCode;
+    message: string;
+};
+export type ValTools = {
+    list(): ValToolDefinition[];
+    listJsonSchema(): ValToolDefinitionJson[];
+    call(name: string, args: unknown, ctx: ValToolContext): Promise<ValToolResult>;
+    dispose(): Promise<void>;
+};

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

@@ -0,0 +1,81 @@
+import { ValConfig, ValModules } from "@valbuild/core";
+import type { ValServerConfig } from "./ValServer.js";
+import type { ValApiOptions } from "./ValRouter.js";
+import { ValOpsFS } from "./ValOpsFS.js";
+import { ValOpsHttp } from "./ValOpsHttp.js";
+/**
+ * Resolving how Val is configured, and building the data layer from it.
+ *
+ * Both live here rather than inside `createValApiRouter` because the MCP tool
+ * registry needs exactly the same answers: which mode we are in, which
+ * credential to use, and which `ValOps` implementation that implies. Two copies
+ * of this would drift, and the failure would be quiet — a registry that decides
+ * it is in fs mode while the Studio decides it is in proxy mode reads different
+ * content from the same project.
+ *
+ * The type-only import from `./ValRouter` is deliberate: it keeps `ValApiOptions`
+ * where its documentation lives without creating a runtime cycle.
+ *
+ * The credential-bearing URL check at the bottom of this file lives here for the
+ * same reason: it is a check on the URLs `initHandlerOptions` resolves, and its
+ * only caller is that function. Leaving it in `./ValRouter` would have meant
+ * importing it back from there, which is the runtime cycle the paragraph above
+ * exists to avoid.
+ */
+export declare const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
+/**
+ * Resolve options plus environment into a concrete {@link ValServerConfig}.
+ *
+ * Moved verbatim out of `createValApiRouter`; the precedence rules are load
+ * bearing, so this is the one place they are written down. Note that "proxy"
+ * mode is inferred when `VAL_API_KEY` or `VAL_SECRET` is present and no mode was
+ * given, which is why a project can be pushed into proxy mode by setting an env
+ * var alone.
+ */
+export declare function initHandlerOptions(route: string, opts: ValApiOptions, config: ValConfig): Promise<ValServerConfig>;
+/**
+ * Build the data layer a {@link ValServerConfig} calls for.
+ *
+ * `auth` decides *whose* credential the http backend sees. Left out, it is the
+ * app's own API key — which is what the Studio wants, because there the app has
+ * already verified a session cookie and is acting on the user's behalf under its
+ * own authority.
+ *
+ * A caller acting for a user it has *not* authenticated itself must pass that
+ * user's personal access token instead, so the backend is the one that decides
+ * what the caller may do. That is the whole of `docs/plans/mcp.md` D.2: the app
+ * stops being an authority and goes back to being a pipe. Passing the app's API
+ * key on such a request is the D.6 confused deputy, and it is worth being blunt
+ * about why it is tempting — it works, and it works for every project the key
+ * can reach, including the ones the caller cannot.
+ */
+export declare function createValOps(valModules: ValModules, options: ValServerConfig, auth?: {
+    pat: string;
+}): ValOpsFS | ValOpsHttp;
+/**
+ * Hosts we send credentials to, and what each one puts at risk. They differ:
+ * only `valBuildUrl` hands back the app token that becomes the session cookie,
+ * so a single shared sentence would overstate one and understate the other.
+ */
+type CredentialBearingUrl = "valBuildUrl" | "valContentUrl";
+/**
+ * Returns a warning if `url` would send credentials somewhere they can be read
+ * off the wire, or null if it is fine.
+ *
+ * Both URLs default to https, but each is overridable - `opts.valBuildUrl` /
+ * `VAL_BUILD_URL`, `opts.valContentUrl` / `VAL_CONTENT_URL` - and neither
+ * override has ever been scheme-checked. Point one at a plain http host and the
+ * api key goes out in clear text, and whatever comes back is whatever the
+ * network says: for `valBuildUrl` that includes the app token this server
+ * re-signs into the session cookie.
+ *
+ * Loopback over http is exempt: that is a val.build running on the developer's
+ * own machine, and there is no network to be on the wrong side of.
+ *
+ * This warns rather than throws. Both overrides are set by the operator, not by
+ * an attacker, so this is a misconfiguration to surface - not untrusted input to
+ * reject - and refusing to boot would break anyone deliberately pointing at an
+ * internal http host today.
+ */
+export declare function insecureUrlWarning(name: CredentialBearingUrl, url: string): string | null;
+export {};