@valbuild/server 0.132.1 → 0.133.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @valbuild/server
 
+## 0.133.0
+
+### Minor Changes
+
+- [#700](https://github.com/valbuild/val/pull/700) [`802412b`](https://github.com/valbuild/val/commit/802412b92c06bc1abbca78c86885e39c8710dd83) Thanks [@freekh](https://github.com/freekh)! - http mode no longer needs a git repository
+
+  A Val app can now run in http mode with no commit and no branch — its content
+  service is the store of record, and git is an optional mirror of the code. This
+  is what `fs` mode has always done: it has never had git, and it works.
+
+  Before this, `VAL_API_KEY` and `VAL_SECRET` were not enough. `VAL_GIT_COMMIT`
+  and `VAL_GIT_BRANCH` were required too, so a deployment with no commit to name
+  either threw at boot or fell through to `fs` mode and reached for a working
+  tree that was not there.
+
+  **Breaking, if you pass `http` options in code.** `gitCommit` and `gitBranch`
+  are replaced by one optional `git`:
+
+  ```diff
+   initValServer(valModules, config, {
+     http: {
+       apiKey,
+       valSecret,
+  -    gitCommit: process.env.VAL_GIT_COMMIT,
+  -    gitBranch: "main",
+  +    // Only for a project whose content is mirrored into a repository.
+  +    // Omit it entirely otherwise.
+  +    git: { commit: process.env.VAL_GIT_COMMIT, branch: "main" },
+     },
+   })
+  ```
+
+  `VAL_GIT_COMMIT` and `VAL_GIT_BRANCH` still work and are still read; they are
+  simply no longer required. Set both or neither — a commit without a branch, or
+  a branch without a commit, is refused at startup with a message naming the
+  missing half, rather than failing later at a publish.
+
+  **What a commit is for, where you have one.** Turning pending patches into new
+  `.val.ts` text means reading the current text first, and that read goes to the
+  content service at that commit. It is the publish path, not the serving path: a
+  committed render reads the source compiled into the build and asks the content
+  service nothing. With no repository there is nothing to write `.val.ts` into,
+  so a publish records the module's data and its schema and skips the file — and
+  that data is what history reads, so nothing is lost.
+
+  **A publish can now be refused by name, before it is attempted.** If a project
+  mirrors its commits into a repository but the running deployment was built
+  before that repository existed, it has no commit to write the mirror against.
+  Publishing anyway would save the content and silently leave the repository
+  behind. The Studio now disables Publish and shows why, and `/save` refuses with
+  a `no-base` code instead of failing partway.
+
+  **Also:** `ValCommit` and `HistoricalCommit` have nullable `parentCommitSha`
+  and `clientCommitSha`, and `/stat`'s `commitSha` is optional. A root commit has
+  no parent, and a publisher with no repository does not report where it was. If
+  you read these fields, handle `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`2b9a51b`](https://github.com/valbuild/val/commit/2b9a51b7dbe2dff53b7686a4f3b7eb9bc5784fae), [`802412b`](https://github.com/valbuild/val/commit/802412b92c06bc1abbca78c86885e39c8710dd83)]:
+  - @valbuild/ui@0.133.0
+  - @valbuild/shared@0.133.0
+
 ## 0.132.1
 
 ### Patch Changes

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

@@ -137,7 +137,8 @@ export declare abstract class ValOps {
         nonce: string;
         baseSha: BaseSha;
         schemaSha: SchemaSha;
-        commitSha: CommitSha;
+        /** Absent for a project with no repository. See `git` on ValApiOptions. */
+        commitSha?: CommitSha;
         sourcesSha: SourcesSha;
         patches: PatchId[];
     } | {
@@ -401,6 +402,42 @@ export declare abstract class ValOps {
     } | {
         errorType: "patch-head-conflict";
     }>>;
+    /**
+     * Why a publish cannot happen here, or `null` when one can.
+     *
+     * Named rather than thrown, and asked BEFORE the click: the Studio shows the
+     * reason and disables the action, instead of letting someone write a commit
+     * message and then meeting a failure from four layers down.
+     *
+     * `no-base` is the only code so far and means what it says: there is nowhere
+     * for this publish's commit to be based. Note which way round that is --
+     * a project whose content service is the store of record always HAS a base
+     * (the service's own chain, which mints its own shas), so the refusal is not
+     * about missing git. It is about a deployment that cannot do what its
+     * project requires.
+     */
+    publishRefusal(): PublishRefusal | null;
+    /**
+     * Whether a commit here produces `.val.ts` TEXT as well as data.
+     *
+     * True everywhere there is somewhere to put it: a working tree in `fs` mode,
+     * a host holding its own source in memory mode, a git repository in `http`
+     * mode. False for an `http` project whose content service is the store of
+     * record and which has no repository attached -- see `git` on
+     * {@link ValApiOptions}.
+     *
+     * WHAT IS NOT AFFECTED, and it is the part worth being sure of:
+     * `moduleVersions` -- what each changed module IS after the commit, with its
+     * schema -- comes from `getSources(analysis)`, which applies the ops to
+     * Source in the stores. It does not go near the file text. So a commit with
+     * no mirror still records everything history and a later `connect-github`
+     * fold need; what it does not record is a rendering of that data as code.
+     *
+     * WHAT IS: the ops are no longer applied to the file text as well, so a
+     * patch that would not fit the `.val.ts` is not reported here. That check
+     * only ever existed for the text being produced, and there is none.
+     */
+    protected readonly mirrorsSourceFiles: boolean;
     /**
      * Take the `.val.ts` text a commit produced as the new committed source.
      *
@@ -624,6 +661,18 @@ export type OpsMetadata<T extends "file" | "image"> = {
     }))[];
 };
 export type BinaryFileType = "file" | "image";
+/**
+ * Why a publish is refused, in a form a person can be shown.
+ *
+ * `code` is for the Studio to branch on and `message` is what it says. Both,
+ * rather than a code and a lookup table on the client: the server knows what
+ * is actually missing -- which branch, which commit -- and a client-side table
+ * could only ever say the generic version.
+ */
+export type PublishRefusal = {
+    code: "no-base";
+    message: string;
+};
 export type PreparedCommit = {
     /**
      * Updated / new source files that are ready to be committed / saved.

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

@@ -1,6 +1,6 @@
 import { type PatchId, type ModuleFilePath, ValModules } from "@valbuild/core";
 import type { Patch as PatchT, ParentRef as ParentRefT } from "@valbuild/core/patch";
-import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
+import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha, type PublishRefusal } from "./ValOps.js";
 import { z } from "zod";
 import type { HistoryError } from "./history/HistoryError.js";
 import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
@@ -23,16 +23,69 @@ export type PatchGroupMutationResult = {
 export declare class ValOpsHttp extends ValOps {
     private readonly contentUrl;
     private readonly project;
-    private readonly commitSha;
-    private readonly branch;
+    /**
+     * The repository this project's commits are mirrored into, or `null`.
+     *
+     * `null` is a project whose content service is the store of record: it
+     * mints its own commit shas, and it knows this project's branch from the
+     * project itself. Every request below that would have carried a branch and
+     * a commit omits them instead, and the service answers from the project's
+     * own chain -- which is where those answers always came from.
+     *
+     * It is NOT a degraded mode. The one thing that genuinely needs a
+     * repository is producing the `.val.ts` text a commit mirrors, and a
+     * project with no repository has nothing to mirror into. See `git` on
+     * {@link ValApiOptions}.
+     */
+    private readonly git;
     private readonly authHeaders;
     private readonly root;
     /** Val's content service owns the store. See {@link ValOps.patchesAreLocal}. */
     readonly patchesAreLocal = false;
     /** See {@link ValOps.requiresAuth}. */
     readonly requiresAuth = true;
-    constructor(contentUrl: string, project: string, commitSha: string, // TODO: CommitSha
-    branch: string, 
+    /**
+     * A commit mirrors into `.val.ts` only when there is a repository.
+     *
+     * See {@link ValOps.mirrorsSourceFiles}. Set in the constructor rather than
+     * as an initialiser because it depends on `git`, and a class field
+     * initialiser runs before the constructor body has assigned it.
+     */
+    protected readonly mirrorsSourceFiles: boolean;
+    /**
+     * What the content service last said this project expects of its publisher.
+     *
+     * `null` until something has asked it, which in practice is the first poll.
+     * It is remembered rather than asked for on demand because the answer is
+     * only wanted on the publish path, and that path already fetches the
+     * patches it is publishing -- so a dedicated request would be a second round
+     * trip for two fields that just arrived.
+     *
+     * It can be one poll out of date, and that is the right amount: the thing it
+     * changes is whether this deployment can mirror commits into a repository,
+     * which changes when a project CONNECTS one -- and a project that has just
+     * connected is one whose builds are about to be replaced anyway.
+     */
+    private projectExpectation;
+    constructor(contentUrl: string, project: string, 
+    /**
+     * The repository this project's commits are mirrored into, or `null`.
+     *
+     * `null` is a project whose content service is the store of record: it
+     * mints its own commit shas, and it knows this project's branch from the
+     * project itself. Every request below that would have carried a branch and
+     * a commit omits them instead, and the service answers from the project's
+     * own chain -- which is where those answers always came from.
+     *
+     * It is NOT a degraded mode. The one thing that genuinely needs a
+     * repository is producing the `.val.ts` text a commit mirrors, and a
+     * project with no repository has nothing to mirror into. See `git` on
+     * {@link ValApiOptions}.
+     */
+    git: {
+        commit: string;
+        branch: string;
+    } | null, 
     /**
      * An api key (how the app itself authenticates) or a personal access token
      * (how the CLI authenticates after `val login`). Same two shapes as
@@ -50,6 +103,29 @@ export declare class ValOpsHttp extends ValOps {
          */
         root?: string;
     });
+    /**
+     * A deployment that cannot mirror a project which expects to be mirrored.
+     *
+     * This is the one shape of "no base" that exists, and it is not the one it
+     * sounds like. A project with no repository is fine: the content service is
+     * the store of record for it and mints its own commit shas, so there is
+     * always somewhere for the commit to go. What is refused is the mismatch --
+     * a project whose commits are mirrored into a repository, being published by
+     * a build that was made before it had one and so has no commit to produce
+     * that mirror against.
+     *
+     * It is a REAL state rather than a defensive check: it is exactly what a
+     * deployment looks like between a project connecting a repository and its
+     * next build going out. Left unchecked, such a publish writes the data and
+     * silently fails to mirror it, and the repository quietly falls behind the
+     * content nobody is told about.
+     *
+     * `null` when the service did not say (see `project` on the response
+     * schema): an older content service is not evidence of anything, and
+     * refusing every publish against one would be a worse failure than not
+     * checking.
+     */
+    publishRefusal(): PublishRefusal | null;
     onInit(): Promise<void>;
     getPresignedAuthNonce(profileId: string, corsOrigin: string): Promise<{
         status: "success";
@@ -80,7 +156,8 @@ export declare class ValOpsHttp extends ValOps {
         baseSha: BaseSha;
         schemaSha: SchemaSha;
         sourcesSha: SourcesSha;
-        commitSha: CommitSha;
+        /** Absent for a project with no repository. See `git` on ValApiOptions. */
+        commitSha?: CommitSha;
         commits: ValCommit[];
         deployments: ValDeployment[];
         patches: PatchId[];

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

@@ -84,21 +84,34 @@ type ValServerOverrides = Partial<{
      */
     patchStore: ValPatchStore;
     /**
-     * Current git commit.
+     * The git commit this code was built from, and the branch a publish mirrors
+     * into -- for a project that HAS a repository.
      *
-     * Required if mode is "proxy".
+     * OPTIONAL, including in http mode, and absent is the normal case for a
+     * project whose content service is the store of record. It used to be
+     * required, which made a repository a precondition for editing anything: a
+     * deployment with no commit to name fell through to `fs` mode and reached
+     * for a working tree that was not there.
      *
-     * @example "e83c5163316f89bfbde7d9ab23ca2e25604af290"
-     */
-    gitCommit: string;
-    /**
-     * Current git branch.
+     * What it is FOR, where there is one: a publish turns pending patches into
+     * new `.val.ts` text, and to patch a file you must first read it. That read
+     * goes to the content service AT THIS COMMIT. Give it a commit the deployed
+     * code did not come from and the publish writes over a different version of
+     * the file than the one the site is running.
      *
-     * Required if mode is "proxy".
+     * It is NOT what a committed render reads -- that reads the source compiled
+     * into the build and asks the content service nothing.
      *
-     * @example "main"
+     * A normal deploy bakes this at build time, because the commit really is a
+     * property of those bytes. `VAL_GIT_COMMIT` / `VAL_GIT_BRANCH` supply it
+     * where a build system sets environment variables instead.
+     *
+     * @example { commit: "e83c5163316f89bfbde7d9ab23ca2e25604af290", branch: "main" }
      */
-    gitBranch: string;
+    git?: {
+        commit: string;
+        branch: string;
+    };
     /**
      * The base url of Val.
      *

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

@@ -121,8 +121,17 @@ export type ValServerConfig = ValServerOptions & ({
     mode: "http";
     apiKey: string;
     project: string;
-    commit: string;
-    branch: string;
+    /**
+     * The repository this project's commits are mirrored into, if any.
+     *
+     * Absent is a project whose content service is the store of record --
+     * which is every project that has not attached a repository, and the
+     * normal case. See `git` on {@link ValApiOptions}.
+     */
+    git?: {
+        commit: string;
+        branch: string;
+    };
     root?: string;
     config: ValConfig;
 }

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

@@ -4,8 +4,10 @@ import type { HistoryError } from "./HistoryError.js";
 /** One commit, as history lists it. */
 export type HistoricalCommit = {
     commitSha: string;
-    parentCommitSha: string;
-    clientCommitSha: string;
+    /** `null` for a root commit. See `ValCommit`. */
+    parentCommitSha: string | null;
+    /** `null` when the publisher did not say where it was. See `ValCommit`. */
+    clientCommitSha: string | null;
     branch: string;
     createdBranch: string | null;
     creator: string | null;