@valbuild/server 0.128.0 → 0.130.0

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

@@ -1,9 +1,9 @@
 import { ValModules, PatchId, ModuleFilePath, ValConfig } from "@valbuild/core";
 import { Api, ServerOf } from "@valbuild/shared/internal";
 import { z } from "zod";
-import { ValOpsFS } from "./ValOpsFS.js";
-import { CommitSha } from "./ValOps.js";
+import { AuthorId, CommitSha, ValOps, type GenericErrorMessage, type PreparedCommit } from "./ValOps.js";
 import { ValOpsHttp } from "./ValOpsHttp.js";
+import { type ValPatchStore } from "./ValOpsMemory.js";
 export type ValServerOptions = {
     route: string;
     valEnableRedirectUrl?: string;
@@ -15,6 +15,72 @@ export type ValServerOptions = {
     apiKey?: string;
     project?: string;
     config: ValConfig;
+    /**
+     * Called after a save has applied its patches, with the files it produced.
+     *
+     * EXPERIMENTAL. The seam a host needs when "commit" does not mean "write to
+     * the working tree and let git take it from here". `patchedSourceFiles` is
+     * already path -> content (null = delete), which is what such a host
+     * publishes, so this hands over the thing that already exists rather than
+     * inventing a format.
+     *
+     * It runs AFTER the files are saved, not instead: the save is what makes the
+     * patches consumed, and a host that also wants them elsewhere is adding a
+     * destination, not replacing one. Throwing here fails the save.
+     */
+    commitPrepared?: (commit: {
+        patchedSourceFiles: Record<string, string | null>;
+    }) => Promise<void>;
+    /**
+     * What a publish DOES, in `http` mode.
+     *
+     * EXPERIMENTAL. By default a publish there is a git commit through the
+     * content API — the content service holds the patches, and publishing means
+     * turning them into a commit on the project's repository. A host whose
+     * "publish" is something else entirely (this one builds the site and flips a
+     * pointer) has no way to say so.
+     *
+     * The default is handed over as {@link CommitContext.commitToGit} rather than
+     * simply skipped, and that is the whole point: it lets a host REPLACE the
+     * commit (never call it) or ADD to it (call it, then do its own work with the
+     * files). Those are two genuinely different products — one where the
+     * repository is the source of truth and one where the build is — and this
+     * seam should not decide which.
+     *
+     * Return what the route should report. Throwing fails the publish, with the
+     * patches left where they were.
+     */
+    publishOverride?: (context: CommitContext) => Promise<CommitResult>;
+};
+/** What {@link ValServerOptions.publishOverride} is given. */
+export type CommitContext = {
+    /** The files this commit produced: `path -> content`, `null` = delete. */
+    patchedSourceFiles: Record<string, string | null>;
+    /** Everything else the commit knows, for a host that needs more. */
+    preparedCommit: PreparedCommit;
+    message: string;
+    authorId: AuthorId;
+    /** The patch group this commit empties, if it empties one. */
+    patchGroupId?: string;
+    /**
+     * The default: a git commit through the content API.
+     *
+     * Call it to publish to the repository as well, or leave it alone to replace
+     * that step. Not calling it means the patches are NOT marked published by the
+     * content API, so a host that replaces the commit owns that too.
+     */
+    commitToGit: () => Promise<CommitResult>;
+};
+/** What a publish reports back, in either shape. */
+export type CommitResult = {
+    isNotFastForward?: boolean;
+    updatedFiles: string[];
+    commit: CommitSha;
+    branch: string;
+    error?: undefined;
+} | {
+    isNotFastForward?: boolean;
+    error: GenericErrorMessage;
 };
 export type ValServerConfig = ValServerOptions & ({
     mode: "fs";
@@ -28,6 +94,25 @@ export type ValServerConfig = ValServerOptions & ({
     branch: string;
     root?: string;
     config: ValConfig;
+}
+/**
+ * EXPERIMENTAL -- a host that holds the project's source itself.
+ *
+ * Neither of the other two fits a host that builds and publishes its own
+ * output: `fs` assumes a working tree it can watch and write, and `http`
+ * assumes Val's content service owns the patch chain and that a commit is a
+ * git commit. See {@link ValOpsMemory}, and `commitPrepared` above for
+ * where the publish goes.
+ */
+ | {
+    mode: "memory";
+    /** The project's source, by path. */
+    sourceFiles: Record<string, string>;
+    /** Where pending patches live. Defaults to memory; see ValPatchStore. */
+    patchStore?: ValPatchStore;
+    /** See ValServerOverrides. Off by default; memory mode authenticates. */
+    unsafelyAllowUnauthenticated?: boolean;
+    config: ValConfig;
 });
 export type ValServer = ServerOf<Api>;
 export declare const ValServer: (valModules: ValModules, options: ValServerConfig, callbacks: ValServerCallbacks) => ServerOf<Api>;
@@ -124,7 +209,7 @@ chain: readonly {
  * `undefined` means "apply everything", which is what every caller that does
  * not ask for scoping gets and must keep getting.
  */
-export declare function resolveOwnPatchScope(serverOps: ValOpsFS | ValOpsHttp, opts: {
+export declare function resolveOwnPatchScope(serverOps: ValOps, opts: {
     /** A caller that named a list already knows what it wants. */
     explicitPatchIds: PatchId[] | undefined;
     ownGroupsOnly: boolean;

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

@@ -10,7 +10,9 @@ export declare function getSettings(projectName: string, auth: {
     pat: string;
 } | {
     apiKey: string;
-}): Promise<{
+}, 
+/** Overrides {@link defaultHost}. See the note there for why this exists. */
+contentUrl?: string): Promise<{
     success: true;
     data: Settings;
 } | {

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

@@ -41,6 +41,7 @@ export type { JsonValuesEntryExtraction } from "./extractJsonValuesEntry.js";
 export type { ModulePathMap } from "./modulePathMap.js";
 export { ValOpsFS } from "./ValOpsFS.js";
 export { ValOpsHttp } from "./ValOpsHttp.js";
+export { ValOpsMemory, InMemoryPatchStore, type ValPatchStore, type StoredPatch, type ValOpsMemoryOptions, } from "./ValOpsMemory.js";
 export { loadValModules, createValModuleFileInspector } from "./loadValModules.js";
 export type { ValModuleFileInspection } from "./loadValModules.js";
 export { formatPatchSourceError } from "./ValOps.js";
@@ -50,6 +51,7 @@ export type { OrderedPatches, PatchAnalysis, PatchSourceError, PreparedCommit, }
 export type { ValOps } from "./ValOps.js";
 export type { AuthorId, BinaryFileType, MetadataOfType, Schemas, Sources, } from "./ValOps.js";
 export type { ValServerConfig } from "./ValServer.js";
+export type { CommitContext, CommitResult } from "./ValServer.js";
 /**
  * The local-dev patch store, exported so the CLI's debug tooling can read a
  * snapshot back with the same code the server uses rather than a second

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

@@ -3,6 +3,7 @@ import type { ValServerConfig } from "./ValServer.js";
 import type { ValApiOptions } from "./ValRouter.js";
 import { ValOpsFS } from "./ValOpsFS.js";
 import { ValOpsHttp } from "./ValOpsHttp.js";
+import { ValOpsMemory } from "./ValOpsMemory.js";
 /**
  * Resolving how Val is configured, and building the data layer from it.
  *
@@ -54,7 +55,7 @@ export declare function initHandlerOptions(route: string, opts: ValApiOptions, c
  * can reach, including the ones the caller cannot. Callers are refused for a
  * missing credential well before this point.
  */
-export declare function createValOps(valModules: ValModules, options: ValServerConfig): ValOpsFS | ValOpsHttp;
+export declare function createValOps(valModules: ValModules, options: ValServerConfig): ValOpsFS | ValOpsHttp | ValOpsMemory;
 /**
  * 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,
@@ -114,7 +115,7 @@ export type ResolveRemoteFileAuthResult = {
     auth: RemoteFileAuth;
 } | {
     status: "error";
-    errorCode: "project-not-configured" | "pat-error";
+    errorCode: "project-not-configured" | "pat-error" | "api-key-missing";
     message: string;
 };
 export declare function resolveRemoteFileAuth(options: ValServerConfig): Promise<ResolveRemoteFileAuthResult>;