@valbuild/server 0.147.0 → 0.148.1

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

@@ -1,10 +1,10 @@
-import { Buffer } from "buffer";
 import { MediaSource, FileMetadata, FileSource, ImageMetadata, ModuleFilePath, PatchId, Schema, SelectorSource, SerializedSchema, Source, SourcePath, ValConfig, ValModules, ValidationError } from "@valbuild/core";
 import { result } from "@valbuild/core/fp";
 import { JSONValue, ParentRef, Patch, PatchError } from "@valbuild/core/patch";
 import type { HistoryError } from "./history/HistoryError.js";
 import type { PlanRefusalErrorT } from "@valbuild/shared/internal";
 import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
+import { type RemoteFilesCheck, type RemoteNetwork } from "./remoteFileCheck.js";
 import type { ValSyntaxError, ValSyntaxErrorTree } from "./patch/ts/syntax.js";
 import { ParentPatchId } from "@valbuild/core";
 import type { ReifiedPreview } from "@valbuild/core";
@@ -383,7 +383,14 @@ export declare abstract class ValOps {
      * are absent. `/sources/~` overlays the two for exactly this reason.
      */
     getSourcesWithPatchesApplied(analysis: PatchAnalysis & OrderedPatches): Promise<Awaited<ReturnType<ValOps["getSources"]>>>;
-    validateSources(schemas: Schemas, sources: Sources, patchesByModule?: PatchAnalysis["patchesByModule"]): Promise<{
+    validateSources(schemas: Schemas, sources: Sources, patchesByModule?: PatchAnalysis["patchesByModule"], 
+    /**
+     * Validate only these modules. The snapshot the cross-module checks read
+     * (a keyOf's keys, a route, a set's directory) is still built from every
+     * module, which is what makes checking one module at a time give the same
+     * answer for it as checking them all. Wins over `patchesByModule`.
+     */
+    onlyModules?: readonly ModuleFilePath[]): Promise<{
         errors: Record<ModuleFilePath, {
             invalidSource?: {
                 message: string;
@@ -393,7 +400,19 @@ export declare abstract class ValOps {
         files: Record<SourcePath, FileSource>;
         remoteFiles: Record<SourcePath, MediaSource>;
     }>;
-    validateRemoteFiles(schemas: Schemas, sources: Sources, remoteFiles: Record<SourcePath, MediaSource>): Promise<Record<SourcePath, ValidationError[]>>;
+    /**
+     * The remote values `validateSources` set aside, checked: is each ref
+     * sound, and does its host serve it. See `checkRemoteFiles`.
+     *
+     * `fileLastUpdatedByPatchId` names the refs whose bytes are still in a
+     * pending patch, which the host will not have until publish.
+     */
+    validateRemoteFiles(schemas: Schemas, sources: Sources, remoteFiles: Record<SourcePath, MediaSource>, fileLastUpdatedByPatchId?: PatchAnalysis["fileLastUpdatedByPatchId"], network?: RemoteNetwork): Promise<RemoteFilesCheck>;
+    /**
+     * Is a remote file's bytes in a pending patch? `not-pending` when no patch
+     * wrote it; `missing` when one did and its bytes are not there.
+     */
+    pendingBytesOf(fileLastUpdatedByPatchId: PatchAnalysis["fileLastUpdatedByPatchId"]): (ref: string) => Promise<"present" | "missing" | "not-pending">;
     validateFiles(schemas: Schemas, sources: Sources, files: Record<SourcePath, FileSource>, fileLastUpdatedByPatchId?: PatchAnalysis["fileLastUpdatedByPatchId"]): Promise<Record<SourcePath, ValidationError[]>>;
     /**
      * Applies the pending patches to the source files so they can be committed.
@@ -641,13 +660,13 @@ export declare abstract class ValOps {
      * gets this for free; a backend that can take bytes straight through should
      * override it.
      */
-    saveBinaryFileFromPatch(filePath: string, parentRef: ParentRef, patchId: PatchId, bytes: Buffer, mimeType: string, type: "file" | "image", metadata: MetadataOfType<"file" | "image"> | undefined): Promise<WithGenericError<{
+    saveBinaryFileFromPatch(filePath: string, parentRef: ParentRef, patchId: PatchId, bytes: Uint8Array, mimeType: string, type: "file" | "image", metadata: MetadataOfType<"file" | "image"> | undefined): Promise<WithGenericError<{
         patchId: PatchId;
         filePath: string;
     }>>;
-    abstract getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Buffer | null>;
+    abstract getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Uint8Array | null>;
     protected abstract getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, remote: boolean): Promise<OpsMetadata<T>>;
-    abstract getBinaryFile(filePathOrRef: string): Promise<Buffer | null>;
+    abstract getBinaryFile(filePathOrRef: string): Promise<Uint8Array | null>;
     /**
      * A file's bytes as something a `Range` request can be answered from
      * without reading the rest: a video is seeked in by many small ranges, and
@@ -710,7 +729,7 @@ export declare abstract class ValOps {
     /** Which files the commit touched, and how. Names them; does not fetch them. */
     abstract getCommitAffectedFiles(commitSha: string): Promise<result.Result<AffectedFile[], HistoryError>>;
     /** One file's bytes as they were at one commit. */
-    abstract getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Buffer, HistoryError>>;
+    abstract getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Uint8Array, HistoryError>>;
     /**
      * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
      *
@@ -1019,13 +1038,15 @@ export type OrderedPatchesMetadata = {
     networkError?: boolean;
 };
 export declare function getFieldsForType<T extends BinaryFileType>(type: T): (keyof MetadataOfType<T> & string)[];
-export declare function createMetadataFromBuffer<T extends BinaryFileType>(type: BinaryFileType, mimeType: string, buffer: Buffer): OpsMetadata<T>;
+export declare function createMetadataFromBuffer<T extends BinaryFileType>(type: BinaryFileType, mimeType: string, buffer: Uint8Array): OpsMetadata<T>;
 export declare function guessMimeTypeFromPath(filePath: string): string | null;
-export declare function bufferFromDataUrl(dataUrl: string): Buffer | undefined;
+export declare function bufferFromDataUrl(dataUrl: string, 
+/** Node passes `Buffer`'s, which is faster: this is a whole upload. */
+decodeBase64?: (base64: string) => Uint8Array): Uint8Array | undefined;
 /** A file of known size whose bytes are read a range at a time. */
 export type BinaryFileReader = {
     readonly size: number;
     /** Bytes `start` to `end`, both inclusive, as an HTTP range is. */
-    read(start: number, end: number): Promise<Buffer>;
+    read(start: number, end: number): Promise<Uint8Array>;
 };
-export declare function bufferReader(buffer: Buffer): BinaryFileReader;
+export declare function bufferReader(buffer: Uint8Array): BinaryFileReader;

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

@@ -34,7 +34,7 @@ export type StoredFile = {
      * has resolved that before it asks.
      */
     filePath: string;
-    data: Buffer;
+    data: Uint8Array;
     metadata: MetadataOfType<"file" | "image"> | undefined;
 };
 /**
@@ -294,9 +294,9 @@ export declare class ValOpsMemory extends ValOps {
         patchId: PatchId;
         filePath: string;
     }>>;
-    getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, _remote?: boolean): Promise<Buffer | null>;
+    getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, _remote?: boolean): Promise<Uint8Array | null>;
     protected getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, _remote?: boolean): Promise<OpsMetadata<T>>;
-    getBinaryFile(_filePathOrRef: string): Promise<Buffer | null>;
+    getBinaryFile(_filePathOrRef: string): Promise<Uint8Array | null>;
     protected getBinaryFileMetadata<T extends "file" | "image">(_filePath: string, _type: T): Promise<OpsMetadata<T>>;
     listCommits(): Promise<result.Result<CommitPage, HistoryError>>;
     getCommitPatches(): Promise<result.Result<{
@@ -308,7 +308,7 @@ export declare class ValOpsMemory extends ValOps {
         complete: boolean;
     }, HistoryError>>;
     getCommitAffectedFiles(): Promise<result.Result<AffectedFile[], HistoryError>>;
-    getFileAtCommit(): Promise<result.Result<Buffer, HistoryError>>;
+    getFileAtCommit(): Promise<result.Result<Uint8Array, HistoryError>>;
     gitPathOfModule(_moduleFilePath: ModuleFilePath): result.Result<string, HistoryError>;
 }
 /** Kept exported so a host can name the error shape it may get back. */

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

@@ -1,4 +1,3 @@
-import { Buffer } from "buffer";
 import type { ValContentVersion, ValProposal } from "./proposal.js";
 import { ValModules, ValConfig } from "@valbuild/core";
 import { Api, ServerOf } from "@valbuild/shared/internal";
@@ -197,7 +196,7 @@ export declare const ENABLE_COOKIE_VALUE: {
         readonly sameSite: "lax";
     };
 };
-export declare function bufferToReadableStream(buffer: Buffer): ReadableStream<any>;
+export declare function bufferToReadableStream(buffer: Uint8Array): ReadableStream<any>;
 export declare function getRedirectUrl(query: {
     redirect_to?: string | undefined;
 }, overrideHost: string | undefined): string | {

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

@@ -1,5 +1,16 @@
 import { FileMetadata, ImageMetadata, SerializedFileSchema, SerializedImageSchema } from "@valbuild/core";
-export declare function checkRemoteRef(remoteHost: string, ref: string, projectRoot: string, schema: SerializedImageSchema | SerializedFileSchema, metadata: Record<string, unknown> | undefined): Promise<{
+export declare function checkRemoteRef(
+/**
+ * Unused: a re-derived ref keeps the host it already names (see below).
+ * Kept so the exported signature does not change.
+ */
+_remoteHost: string, ref: string, projectRoot: string, schema: SerializedImageSchema | SerializedFileSchema, metadata: Record<string, unknown> | undefined, 
+/**
+ * Where the bytes come from when the ref has to be re-derived. Defaults to
+ * a download cached under `projectRoot`; the Studio passes one that keeps
+ * nothing on disk (`FixFiles.readRemoteFile`).
+ */
+readRemote?: ReadRemoteFile): Promise<{
     status: "success";
 } | {
     status: "fix-required";
@@ -11,10 +22,37 @@ export declare function checkRemoteRef(remoteHost: string, ref: string, projectR
 }>;
 export declare function getCachedRemoteFileDir(projectRoot: string): string;
 export declare function getCachedRemoteFilePath(fileExt: string, currentFileHash: string, remoteFileCacheDir: string): string;
-export declare function downloadFileFromRemote(ref: string, filePath: string): Promise<{
+/**
+ * A remote file's bytes, and the hash they actually have — which is the one a
+ * re-derived ref is made from, whatever hash the old ref claimed.
+ */
+export type ReadRemoteFile = (ref: string, fileExt: string, expectedFileHash: string) => Promise<{
+    status: "success";
+    fileBuffer: Buffer;
+    fileHash: string;
+    /** Where a download was kept, when it was kept: for error messages. */
+    cachedFilePath?: string;
+} | {
+    status: "error";
+    error: string;
+}>;
+export declare function getFileBufferFromRemote(ref: string, fileExt: string, currentFileHash: string, projectRoot: string): ReturnType<ReadRemoteFile>;
+/**
+ * Download a remote file to `filePath`, from where its ref says -- and, for a
+ * platform ref whose host fails, from the same file on the project's own
+ * `valstart.dev` address, which always serves it (`fallbackRefOf`). The bytes
+ * from the fallback are checked against the ref's file hash before they are
+ * kept: a different host answering is only safe because of that check.
+ *
+ * Rejects with the FIRST host's error when both fail: that is the one the ref
+ * names, and the one a person can recognise.
+ */
+export declare function downloadFileFromRemote(ref: string, filePath: string): ReturnType<typeof downloadFromUrl>;
+declare function downloadFromUrl(ref: string, filePath: string): Promise<{
     status: "success";
     filePath: string;
 } | {
     status: "error";
     error: string;
 }>;
+export {};

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

@@ -1,5 +1,7 @@
 import { FileMetadata, ImageMetadata, VideoMetadata, SerializedSchema, Source, SourcePath, ValidationError } from "@valbuild/core";
 import { JSONValue, Patch } from "@valbuild/core/patch";
+import { type AskHostProject } from "./remoteHostCheck.js";
+import { FixFiles } from "./fixFiles.js";
 export type FixPatchRemainingError = ValidationError & {
     sourcePath?: SourcePath;
 };
@@ -17,6 +19,16 @@ export declare function mediaValue(path: string, metadata: unknown): Record<stri
 export declare function createFixPatch(config: {
     projectRoot: string;
     remoteHost: string;
+    /**
+     * Where a fix reads a file's bytes and puts a downloaded one. Defaults to
+     * the disk under `projectRoot`; see {@link FixFiles}.
+     */
+    files?: FixFiles;
+    /**
+     * How a platform ref's host is asked which project it serves. Defaults
+     * to `GET <host>/_val/project`; tests replace it.
+     */
+    askHostProject?: AskHostProject;
 }, apply: boolean, sourcePath: SourcePath, validationError: ValidationError, remoteFiles: {
     [sourcePath: SourcePath]: {
         ref: string;
@@ -27,6 +39,16 @@ export declare function createFixPatch(config: {
     patch: Patch;
     remainingErrors: FixPatchRemainingError[];
 } | undefined>;
-export declare function getVideoMetadata(projectRoot: string, fileRef: string): Promise<VideoMetadata>;
-export declare function getImageMetadata(projectRoot: string, validationError: ValidationError): Promise<ImageMetadata>;
-export declare function getFileMetadata(projectRoot: string, validationError: ValidationError): Promise<FileMetadata>;
+export declare function getVideoMetadata(files: FixFiles, fileRef: string): Promise<VideoMetadata>;
+export declare function getImageMetadata(files: FixFiles, validationError: ValidationError): Promise<ImageMetadata>;
+export declare function getFileMetadata(files: FixFiles, validationError: ValidationError): Promise<FileMetadata>;
+/**
+ * What an image or file directory's entry records that its bytes disagree
+ * with, as `[field, recorded, actual]`. The one comparison: the CLI's
+ * `*:check-all-files` fix and the Studio's full check both ask it.
+ */
+export declare function mediaDirEntryMismatches(type: "images" | "files", stored: Record<string, unknown>, actual: {
+    width?: number;
+    height?: number;
+    mimeType?: string;
+}): [field: string, recorded: unknown, actual: unknown][];

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

@@ -0,0 +1,42 @@
+import { VideoMetadata } from "@valbuild/core";
+import { type ReadRemoteFile } from "./checkRemoteRef.js";
+/**
+ * Where `createFixPatch` reads a project file's bytes, and where it puts a
+ * remote file it was asked to download.
+ *
+ * Every path is the file's path from the project root, the way a source names
+ * it: `/public/val/logo.png`, never an absolute path on some disk. That is the
+ * point: a project in http mode, or one the platform serves from a Worker, has
+ * no disk to join a path onto, and a fix that reads a file has to work there
+ * too. `diskFixFiles` is the one the CLI and the language server use, and does
+ * exactly what `createFixPatch` did with `fs` before this existed.
+ *
+ * Not yet covered, and still read from `projectRoot` directly: the CLI's
+ * listing of a media directory for files it does not track, and
+ * `videos:check-all-files` (`videosetCheckAllFilesPatch`), which lists one.
+ * See `docs/plans/studio-validate.md`.
+ */
+export type FixFiles = {
+    /** A project file's bytes. Rejects when it cannot be read. */
+    readFile(filePath: string): Promise<Buffer>;
+    /**
+     * A project video's size, length and mime type. Its own method rather than
+     * `readFile` because a video is mostly frames, and the disk reader reads
+     * only the headers.
+     */
+    readVideoMetadata(filePath: string): Promise<VideoMetadata>;
+    /**
+     * A remote file's bytes, for re-deriving a stale ref (`*:check-remote`).
+     * Nothing is stored in the project.
+     */
+    readRemoteFile: ReadRemoteFile;
+    /** Downloads `url` and stores it in the project at `filePath`. */
+    saveRemoteFile(url: string, filePath: string): Promise<{
+        status: "success";
+    } | {
+        status: "error";
+        error: string;
+    }>;
+};
+/** {@link FixFiles} over a project on disk. */
+export declare function diskFixFiles(projectRoot: string): FixFiles;

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

@@ -44,6 +44,8 @@ export type IValRemote = {
             remoteFileBuckets: {
                 bucket: string;
             }[];
+            /** See `getSettings`: the host new refs name. */
+            remoteHost?: string;
         };
     } | {
         success: false;
@@ -134,12 +136,16 @@ export type ValidationEvent = {
     sourcePath: string;
     message: string;
     keyError?: boolean;
+    /** See `isRepairedOnSave`: the Studio would not hold a publish for it. */
+    repairedOnSave?: boolean;
 } | {
     type: "validation-fixable-error";
     sourcePath: string;
     message: string;
     fixable: boolean;
     keyError?: boolean;
+    /** See `isRepairedOnSave`: the Studio would not hold a publish for it. */
+    repairedOnSave?: boolean;
 } | {
     type: "unknown-fix";
     sourcePath: string;
@@ -246,6 +252,14 @@ export declare function handleJsonValuesExtractEntry(ctx: FixHandlerContext): Pr
  * exists to send it there, and to say what `--fix` would do when it is off.
  */
 export declare function handleViewCheckModule(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `remote:rewrite-host`: a platform ref whose host no longer serves its
+ * project. The server's full check reports it, and so does `createFixPatch`'s
+ * `image:check-remote` branch, which is how `val validate` finds it: that
+ * branch asks the host first. Either way the patch is `createFixPatch`'s, and
+ * needs nothing but the ref -- the new host is derived from it.
+ */
+export declare function handleRemoteRewriteHost(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleExternalUpload(): Promise<FixHandlerResult>;
 export declare const currentFixHandlers: Record<Exclude<ValidationFix, "keyof:check-keys" | "image:check-gallery" | "file:check-gallery" | "video:check-gallery" | "router:check-route" | "locale:check-locale" | "router:check-locale-param" | "record:fill-keys">, FixHandler>;
 export declare const fixHandlers: Record<string, FixHandler>;

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

@@ -4,6 +4,7 @@ declare const SettingsSchema: z.ZodObject<{
     remoteFileBuckets: z.ZodArray<z.ZodObject<{
         bucket: z.ZodString;
     }, z.core.$strip>>;
+    remoteHost: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type Settings = z.infer<typeof SettingsSchema>;
 export declare function getSettings(projectName: string, auth: {

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

@@ -19,6 +19,7 @@ export { formatSyntaxErrorTree } from "./patch/ts/syntax.js";
 export { analyzeValModule } from "./patch/ts/valModule.js";
 export type { ValModuleAnalysis } from "./patch/ts/valModule.js";
 export { createFixPatch } from "./createFixPatch.js";
+export { askOncePerHost } from "./remoteHostCheck.js";
 export { fixHandlers, currentFixHandlers, createDefaultValFSHost, handleFileMetadata, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleRemoteFileDownload, handleRemoteFileCheck, handleUniqueFolderCheck, handleCheckAllFiles, handleJsonValuesExtractEntry, handleExternalUpload, } from "./fixHandlers.js";
 export { handleVideosetMetadata, handleVideosetUploadRemote, handleVideosetCheckRemote, handleVideosetCheckAllFiles, videosetEntryVideoSchema, filesOfVideosetEntry, } from "./videosetFixes.js";
 export type { FixHandler, ModulePatch, FixHandlerContext, FixHandlerResult, IValRemote, ValidationEvent, ValidationError, ValModule, } from "./fixHandlers.js";

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

@@ -6,6 +6,7 @@ import type { ValServerConfig } from "./ValServer.js";
 import type { ResolveRemoteFileAuthResult } from "./valServerConfig.js";
 import type { JwtResult } from "./jwt.js";
 import type { ProbeResult } from "./linkCheck/probeUrl.js";
+import type { checkModuleForStudio, fixForStudio } from "./studioValidation.js";
 /**
  * What `ValServer` needs from the machine it runs on.
  *
@@ -32,8 +33,23 @@ export type ValServerPlatform = {
         encodeJwt: (payload: object, sessionKey: string) => string;
         getExpire: () => number;
     };
+    /**
+     * `bytes` as base64. For the paths that encode every file a publish commits:
+     * Node's `Buffer` is ten times faster than `btoa`, and a browser has only
+     * `btoa` (`bytesToBase64` in `bytes.ts`). Same answer either way.
+     */
+    bytesToBase64: (bytes: Uint8Array) => string;
     /** The developer's `val login` token. See `readValLoginToken`. */
     readValLoginToken: (options: ValServerConfig) => Promise<string | null>;
     /** Which credential talks to the content host. See `resolveRemoteFileAuth`. */
     resolveRemoteFileAuth: (options: ValServerConfig) => Promise<ResolveRemoteFileAuthResult>;
+    /**
+     * The Studio's full check (`/validate`, `/validate/fix`). It reads files'
+     * bytes and asks remote hosts, so it needs Node; absent in a browser, where
+     * both routes answer that it is not available.
+     */
+    studioValidation?: {
+        checkModuleForStudio: typeof checkModuleForStudio;
+        fixForStudio: typeof fixForStudio;
+    };
 };

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

@@ -0,0 +1,116 @@
+import { MediaSource, SerializedSchema, SourcePath, ValidationError } from "@valbuild/core";
+import { type AskHostProject } from "./remoteHostCheck.js";
+/**
+ * Does the host a remote ref names still serve it?
+ *
+ * `found` and `missing` are the host's answer. `unreachable` is no answer at
+ * all — a timeout, a refused connection, a 5xx — and says nothing about the
+ * file, only about the host.
+ */
+export type RemoteFileAnswer = {
+    status: "found";
+} | {
+    status: "missing";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+};
+export type HeadRemoteFile = (url: string) => Promise<RemoteFileAnswer>;
+/**
+ * How the remote check reaches the network: what it asks a host about a file,
+ * and which project a platform host serves. Both default to the real thing;
+ * tests replace them.
+ */
+export type RemoteNetwork = {
+    head?: HeadRemoteFile;
+    askHostProject?: AskHostProject;
+};
+/**
+ * A HEAD, falling back to the first byte of a GET for a host that does not
+ * answer HEAD (405, 501): either way no file is downloaded to learn that it is
+ * there.
+ */
+export declare const headRemoteFile: HeadRemoteFile;
+/** For tests: forget every answer. */
+export declare function clearRemoteFileAnswers(): void;
+/** A host that did not serve the refs of a module it was asked about. */
+export type RemoteHostProblem = {
+    /** `https://remote.val.build`, as the ref names it. */
+    host: string;
+    status: "missing" | "unreachable";
+    /** What the host answered, for "Details": never the row's sentence. */
+    details: string;
+    /** Every ref on that host in the module, checked or vouched for. */
+    sourcePaths: SourcePath[];
+};
+export type RemoteFilesCheck = {
+    /** Wrong refs, one by one: each has its own row. */
+    errors: Record<SourcePath, ValidationError[]>;
+    /** Hosts that failed: one row each, however many refs they cover. */
+    hosts: RemoteHostProblem[];
+};
+export type RemoteFilesCheckInput = {
+    /** What `validateSources` set aside as remote: every remote media value. */
+    remoteFiles: Record<SourcePath, MediaSource>;
+    /** The serialized schema at a path, or undefined when it does not resolve. */
+    schemaAt: (sourcePath: SourcePath) => SerializedSchema | undefined;
+    /**
+     * Does this ref have its bytes in a pending patch? They go to the remote
+     * host at publish, so until then asking the host for it is asking a
+     * question whose answer is "not yet".
+     */
+    pendingBytes: (ref: string) => Promise<"present" | "missing" | "not-pending">;
+    /**
+     * Is this value's ref the one already published at this path? Only those
+     * may be vouched for by another ref on the same host; see `sampleByHost`.
+     */
+    isPublished: (sourcePath: SourcePath, ref: string) => boolean;
+    /**
+     * Ask one published ref per host and take its answer for the rest.
+     *
+     * Right for a managed project, whose refs are only ever written by the
+     * Studio and whose host changes for every ref at once. Wrong for a connected
+     * one, where a developer can edit any single ref by hand. See
+     * `docs/plans/studio-validate.md`, "Remote refs in the full check".
+     */
+    sampleByHost: boolean;
+    /**
+     * Ask only whether the host serves each ref. For the keys of a media
+     * directory: what is recorded about the file is the entry, not a value at
+     * the path, and the ref's hash was made from a schema the directory
+     * synthesizes for it, so there is no schema here to judge it by.
+     */
+    existenceOnly?: boolean;
+    head?: HeadRemoteFile;
+    /** How a platform ref's host is asked which project it serves. */
+    askHostProject?: AskHostProject;
+};
+/**
+ * The remote half of the Studio's full check, for one module's remote values.
+ *
+ * Four questions, cheapest first, and a ref stops at the first one it fails:
+ *
+ * 1. **Is it a ref at all?** `splitRemoteRef` parses it.
+ * 2. **Does the ref agree with what is recorded about it?** A ref carries a
+ *    hash of the schema's options, the file's extension and its width, height
+ *    and mime type. When the value or the schema changed and the ref did not,
+ *    the ref is stale, and **Fix** (`image:check-remote`) re-reads the file and
+ *    writes the ref it should have. Computed with the ref's OWN core version:
+ *    the CLI also re-derives every ref after a Val upgrade, and listing every
+ *    remote image in the project after each upgrade would bury the rows that
+ *    matter. Nothing here downloads.
+ * 3. **Does its host still serve its project?** Only for a platform ref
+ *    (`…/_val/file/…`) that is not on the project's own `valstart.dev`
+ *    address: one `GET <host>/_val/project` per host. A host that dropped the
+ *    project gets a **Fix** (`remote:rewrite-host`) that points the ref at
+ *    `<public id>.valstart.dev`. See `remoteHostCheck.ts`.
+ * 4. **Does the host have it?** A HEAD.
+ *
+ * Neither host question is asked of a ref whose bytes are in a pending patch,
+ * which the host will not have until publish: there the question is whether
+ * the patch still has them.
+ */
+export declare function checkRemoteFiles(input: RemoteFilesCheckInput): Promise<RemoteFilesCheck>;
+/** `www.acme.no`, from `https://www.acme.no`: how a person names a host. */
+export declare function hostName(host: string): string;

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

@@ -0,0 +1,101 @@
+/**
+ * Does the host a platform ref names still serve the project the ref names?
+ *
+ * A ref served by the platform loader names the project's host at the time
+ * the file was added: `https://www.acme.no/_val/file/p/3f9a2c1/…`. When the
+ * project drops `www.acme.no`, the bytes are still there, at
+ * `3f9a2c1.valstart.dev`, but every ref that names the old domain points at a
+ * host that no longer serves them. This is the question that finds those refs,
+ * and `rewriteRefHost` is what the fix (`remote:rewrite-host`) does about it.
+ * See valbuild/home `docs/remote-files-on-platform.md`, "Rewriting refs after a
+ * domain is removed", and `docs/plans/studio-validate.md`, step 6.
+ *
+ * Asked of the host itself (`GET <host>/_val/project`), not of content: the
+ * host's answer covers DNS, the certificate and the loader's mapping in one,
+ * it needs no credential, and it works for a ref that names a project other
+ * than this one -- a project seeded from a template has refs naming the
+ * template's.
+ */
+/** The domain every platform project is always served at, by its public id. */
+export declare const PLATFORM_SITES_DOMAIN = "valstart.dev";
+/**
+ * The host every platform ref of `publicProjectId` can always be pointed at:
+ * `<public id>.valstart.dev` is permanent (decision 4 of the remote-files
+ * plan), and the loader serves a project's files there whatever else it has.
+ */
+export declare function fallbackRemoteHost(publicProjectId: string): string;
+/**
+ * Only a platform ref is asked about. `remote.val.build` is not a platform
+ * host and is not going away, and a ref already on the project's own
+ * `valstart.dev` address is on the fallback, which always serves it.
+ */
+export declare function needsHostCheck(remoteHost: string, projectId: string): boolean;
+/** `ref` with its host part replaced, and everything else as it was. */
+export declare function rewriteRefHost(ref: string, remoteHost: string): string | null;
+/**
+ * - `serves`: the host answered for the project the ref names.
+ * - `other-project`: it answered, for another one -- the domain was moved to
+ *   a different project, and decision 5 means it will not serve these files.
+ * - `no-site`: it answered, but serves no project at all (the loader's 404 for
+ *   a domain nobody has mapped any more).
+ * - `unreachable`: no answer. A domain whose DNS was removed looks like this,
+ *   and so does a host that is down for a minute, which is why the row says
+ *   which it saw.
+ */
+export type HostServes = {
+    status: "serves";
+} | {
+    status: "other-project";
+    publicProjectId: string;
+} | {
+    status: "no-site";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+};
+export type AskHostProject = (remoteHost: string) => Promise<{
+    status: "answered";
+    publicProjectId: string;
+} | {
+    status: "no-site";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+}>;
+/** `GET <host>/_val/project`, answered by the platform loader. */
+export declare const askHostProject: AskHostProject;
+export declare function clearHostAnswers(): void;
+export declare function hostServes(remoteHost: string, projectId: string, ask?: AskHostProject): Promise<HostServes>;
+/**
+ * `ask`, asking each host once for as long as the returned function is kept:
+ * one check, not the life of the server. A check walks its refs in order, so
+ * without it every ref on a host that does not answer waits out its own
+ * timeout -- 150 images on a dead domain is 20 minutes. Kept per check rather
+ * than in {@link hostServes}'s cache because a host that did not answer has
+ * to be asked again by the next one.
+ */
+export declare function askOncePerHost(ask?: AskHostProject): AskHostProject;
+/** `www.acme.no`, from `https://www.acme.no/_val`: how a person names a host. */
+export declare function hostNameOfRemoteHost(remoteHost: string): string;
+/**
+ * Where a platform ref has to move to, when its host no longer serves the
+ * project it names; `undefined` when it does not have to (or is not a
+ * platform ref). `why` and `to` are for the caller's sentence: what can be
+ * done about it differs by caller (a Studio **Fix**, `val validate --fix`, or
+ * nothing yet).
+ */
+export declare function movedRemoteHost(ref: string, ask?: AskHostProject): Promise<{
+    ref: string;
+    why: string;
+    to: string;
+} | undefined>;
+/**
+ * Where else a ref's file can be downloaded from: the same file on the
+ * project's own `valstart.dev` address, for a platform ref on any other host.
+ * `null` when there is nowhere else -- a `remote.val.build` ref, or one already
+ * on the fallback. See valbuild/home `docs/remote-files-on-platform.md`,
+ * "Tooling: the fallback".
+ */
+export declare function fallbackRefOf(ref: string): string | null;