@valbuild/server 0.115.0 → 0.116.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,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";

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 {};