@valbuild/server 0.114.0 → 0.116.0

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,8 @@
 export { createService, Service } from "./Service.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
+export { createValTools } from "./tools/index.js";
+export type { 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";
@@ -25,8 +28,8 @@ export { checkRemoteRef, downloadFileFromRemote, getCachedRemoteFileDir, getCach
 export { hasRemoteFileSchema } from "@valbuild/core";
 export { getFileExt } from "./getFileExt.js";
 export { evalValConfigFile, findAndEvalValConfigFile, } from "./evalValConfigFile.js";
-export { startValLogin, awaitValLoginConfirmation, persistPersonalAccessToken, ValLoginError, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, } from "./login.js";
-export type { ValLoginErrorCode, ValLoginResult, ValLoginSession, } from "./login.js";
+export { startValLogin, awaitValLoginConfirmation, persistPersonalAccessToken, ValLoginError, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, } from "./login.js";
+export type { ValLoginErrorCode, ValLoginResult, ValDeviceAuthorization, } from "./login.js";
 export { createModulePathMap, createJsonEntryPathMap, getModulePathRange, } from "./modulePathMap.js";
 export { findJsonEntryFilePath } from "./jsonEntryLocation.js";
 export { classifyJsonValuesOp, rebaseContentOp } from "./patch/jsonValuesPatch.js";

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

@@ -1,5 +1,15 @@
 /**
- * The Val login device flow, as reusable primitives.
+ * The Val login flow, as reusable primitives.
+ *
+ * This is an RFC 8628 device authorization grant. The shape that matters:
+ * {@link ValDeviceAuthorization.deviceCode} is a secret this process holds and
+ * polls with, while {@link ValDeviceAuthorization.userCode} is the short string
+ * the human reads out of the terminal and types into a browser. Only the device
+ * code can collect a token.
+ *
+ * Keep them apart. Show the user code; never print, log or put the device code
+ * in a URL. An earlier version of this flow used one value for both jobs, which
+ * meant anyone who saw the verification link could collect the token it led to.
  *
  * The CLI wraps these with terminal output, and `@valbuild/language-server`
  * wraps them with LSP `window/showDocument` and progress reporting. Neither the
@@ -16,6 +26,10 @@ export type ValLoginErrorCode =
  | "unexpected-response"
 /** The server returned a 5xx. */
  | "server-error"
+/** The user declined the login in the browser. */
+ | "access-denied"
+/** The login was not approved before the code expired. */
+ | "expired"
 /** The user did not complete the login within the allotted time. */
  | "timeout"
 /** The caller aborted the flow. */
@@ -25,12 +39,23 @@ export declare class ValLoginError extends Error {
     readonly details?: string | undefined;
     constructor(code: ValLoginErrorCode, message: string, details?: string | undefined);
 }
-/** A login attempt that is waiting for the user to confirm in a browser. */
-export type ValLoginSession = {
-    /** Opaque token used to poll for confirmation. */
-    nonce: string;
-    /** URL the user must open to confirm the login. */
-    url: string;
+/** A login attempt that is waiting for the user to approve it in a browser. */
+export type ValDeviceAuthorization = {
+    /**
+     * Secret. Polls for the token. Do not display, log or transmit anywhere but
+     * the token endpoint.
+     */
+    deviceCode: string;
+    /** Short code for the user to compare and type. Safe to display. */
+    userCode: string;
+    /** Where the user goes to enter {@link userCode}. */
+    verificationUri: string;
+    /** {@link verificationUri} with the code prefilled, for convenience. */
+    verificationUriComplete: string;
+    /** Seconds until the code stops being approvable. */
+    expiresInSeconds: number;
+    /** Minimum seconds between polls, per the server. */
+    intervalSeconds: number;
 };
 export type ValLoginResult = {
     profile: {
@@ -39,24 +64,26 @@ export type ValLoginResult = {
     pat: string;
 };
 /**
- * Begin a login attempt. The caller is responsible for getting
- * {@link ValLoginSession.url} in front of the user.
+ * Begin a login attempt. The caller is responsible for getting the user code
+ * and verification URL in front of the user.
  */
 export declare function startValLogin(options?: {
     host?: string;
-}): Promise<ValLoginSession>;
-export declare const DEFAULT_LOGIN_MAX_DURATION: number;
-export declare const DEFAULT_LOGIN_POLL_INTERVAL = 1000;
+    deviceName?: string;
+}): Promise<ValDeviceAuthorization>;
+/** Fallbacks for a server that omits the optional RFC 8628 timing fields. */
+export declare const DEFAULT_LOGIN_EXPIRES_IN_SECONDS = 600;
+export declare const DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = 5;
 /**
- * Poll until the user confirms the login in their browser.
+ * Poll until the user approves the login in their browser.
  *
  * Accepts an `AbortSignal` so an editor can cancel the flow when the user
- * dismisses the prompt, instead of leaving a poll loop running for 5 minutes.
+ * dismisses the prompt, instead of leaving a poll loop running to expiry.
  */
-export declare function awaitValLoginConfirmation(nonce: string, options?: {
+export declare function awaitValLoginConfirmation(authorization: ValDeviceAuthorization, options?: {
     host?: string;
+    /** Defaults to the authorization's own `expiresInSeconds`. */
     maxDurationMs?: number;
-    pollIntervalMs?: number;
     signal?: AbortSignal;
     /** Wall clock, injectable for tests. */
     now?: () => number;

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,2 @@
+export { createValTools, type ValToolsOptions } from "./createValTools.js";
+export type { ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, } from "./types.js";

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

@@ -0,0 +1,116 @@
+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>>;
+};
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * There is deliberately no identity field here, only the credential. In proxy
+ * mode the caller's own personal access token authenticates every downstream
+ * call, so the backend decides who the caller is (`docs/plans/mcp.md` D.2). An
+ * `authorId` alongside it would have to be filled in by the host, and the host
+ * has no way to verify a PAT — so the field would be an unverified claim that
+ * looks like a checked one, which is the confused-deputy shape D.6 rejects.
+ *
+ * `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: {
+        /**
+         * The caller's PAT. Never log this, never put it in a URL, and never let
+         * it reach a tool result.
+         */
+        pat: string;
+    } | null;
+    /** Groups a run of related edits, when the host has such a notion. */
+    sessionId: string | null;
+};
+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 {};