@valbuild/server 0.132.1 → 0.133.0

package/dist/valbuild-server.esm.js

@@ -4313,7 +4313,25 @@ class ValOps {
       };
     };
     const patchedJsonEntries = {};
-    const allResults = await Promise.all(Object.entries(patchesByModule).map(([path, patches]) => applySourceFilePatches(path, patches)));
+    /*
+     * Patching the FILE TEXT, for a store that has somewhere to put it.
+     *
+     * Where there is nowhere -- an http project with no repository -- the
+     * patches are still all applied, because they are: `getSources(analysis)`
+     * below applies them to Source, and that is what the commit records and
+     * what every reader of this project sees. What is skipped is rendering
+     * that data back out as `.val.ts` and `*.val.json`, which would be a
+     * mirror with no repository to mirror into -- and which cannot even be
+     * attempted, because producing it starts by READING the current text from
+     * the repository that is not there.
+     */
+    const allResults = await Promise.all(Object.entries(patchesByModule).map(([path, patches]) => this.mirrorsSourceFiles ? applySourceFilePatches(path, patches) : Promise.resolve({
+      path: path,
+      appliedPatches: patches.map(p => p.patchId),
+      result: null,
+      extraFiles: {},
+      jsonEntries: {}
+    })));
     let hasErrors = false;
     const sourceFilePatchErrors = {};
     const appliedPatches = {};
@@ -4488,6 +4506,46 @@ class ValOps {
     });
   }
 
+  /**
+   * 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() {
+    return 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.
+   */
+  mirrorsSourceFiles = true;
+
   /**
    * Take the `.val.ts` text a commit produced as the new committed source.
    *
@@ -4652,6 +4710,16 @@ function formatPatchSourceError(error) {
     return "Unknown patch source error: " + JSON.stringify(_exhaustiveCheck);
   }
 }
+
+/**
+ * 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.
+ */
+
 /**
  * The patches a json entry render should apply, out of the whole chain.
  *
@@ -7491,8 +7559,14 @@ const GetApplicablePatches = z.object({
   })),
   commits: z.array(z.object({
     commitSha: z.string(),
-    clientCommitSha: z.string(),
-    parentCommitSha: z.string(),
+    /*
+     * Nullable since the content service mints its own commit shas: a
+     * root commit has no parent, and a publisher that did not say where
+     * it was has no client sha. Parsed rather than trusted, so a service
+     * that sends null gets null here instead of failing the whole poll.
+     */
+    clientCommitSha: z.string().nullable(),
+    parentCommitSha: z.string().nullable(),
     commitMessage: z.string().nullable(),
     branch: z.string(),
     creator: z.string(),
@@ -7508,7 +7582,21 @@ const GetApplicablePatches = z.object({
     // `ValDeployment`: this is the only source for a deployment that Val
     // did not publish, and zod would otherwise strip it here.
     commitMessage: z.string().nullable().optional()
-  })).optional()
+  })).optional(),
+  /**
+   * What the project EXPECTS of whoever publishes it.
+   *
+   * Optional because a content service that predates it sends nothing, and
+   * absent means "not reported" -- never "managed". The difference decides
+   * whether a publish is refused, so guessing either way would be worse than
+   * not checking: guessing `managed` would let a deployment publish a
+   * connected project it cannot mirror, and guessing `connected` would refuse
+   * every publish against an older service.
+   */
+  project: z.object({
+    sourceMode: z.union([z.literal("managed"), z.literal("connected")]),
+    branch: z.string()
+  }).optional()
 });
 const FilesResponse = z.object({
   files: z.array(z.union([z.object({
@@ -7581,8 +7669,10 @@ const CommitResponse = z.object({
 // commit changed nothing", which is indistinguishable from a real answer.
 const HistoricalCommitResponse = z.object({
   commitSha: z.string(),
-  parentCommitSha: z.string(),
-  clientCommitSha: z.string(),
+  /** `null` for a root commit; see the note on the applicable-patches schema. */
+  parentCommitSha: z.string().nullable(),
+  /** `null` when the publisher did not say where it was. */
+  clientCommitSha: z.string().nullable(),
   branch: z.string(),
   createdBranch: z.string().nullable(),
   creator: z.string().nullable(),
@@ -7600,8 +7690,8 @@ const CommitPatchesResponse = z.object({
   commitSha: z.string(),
   commit: z.object({
     commitSha: z.string(),
-    parentCommitSha: z.string(),
-    clientCommitSha: z.string(),
+    parentCommitSha: z.string().nullable(),
+    clientCommitSha: z.string().nullable(),
     branch: z.string(),
     createdBranch: z.string().nullable(),
     creator: z.string().nullable(),
@@ -7701,9 +7791,45 @@ class ValOpsHttp extends ValOps {
   patchesAreLocal = false;
   /** See {@link ValOps.requiresAuth}. */
   requiresAuth = true;
-  constructor(contentUrl, project, commitSha,
-  // TODO: CommitSha
-  branch,
+  /**
+   * 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.
+   */
+  mirrorsSourceFiles;
+  /**
+   * 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.
+   */
+  projectExpectation = null;
+  constructor(contentUrl, project,
+  /**
+   * 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,
   /**
    * An api key (how the app itself authenticates) or a personal access token
    * (how the CLI authenticates after `val login`). Same two shapes as
@@ -7713,14 +7839,49 @@ class ValOpsHttp extends ValOps {
     super(valModules, options);
     this.contentUrl = contentUrl;
     this.project = project;
-    this.commitSha = commitSha;
-    this.branch = branch;
+    this.git = git;
     this.authHeaders = "pat" in auth ? {
       "x-val-pat": auth.pat
     } : {
       Authorization: `Bearer ${auth.apiKey}`
     };
     this.root = (options === null || options === void 0 ? void 0 : options.root) ?? "";
+    this.mirrorsSourceFiles = git !== null;
+  }
+  /**
+   * 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() {
+    var _this$projectExpectat;
+    if (this.git !== null) {
+      return null;
+    }
+    if (((_this$projectExpectat = this.projectExpectation) === null || _this$projectExpectat === void 0 ? void 0 : _this$projectExpectat.sourceMode) !== "connected") {
+      return null;
+    }
+    return {
+      code: "no-base",
+      message: `This project mirrors its content into a git repository (branch ` + `'${this.projectExpectation.branch}'), but this deployment was not ` + "built from one, so it does not know which commit to write that " + "mirror against. Publishing would save the content and silently " + "leave the repository behind. Deploy this project again from its " + "repository, and publishing will work from that build on."
+    };
   }
   async onInit() {
     // TODO: unused for now. Implement or remove
@@ -7911,16 +8072,31 @@ class ValOpsHttp extends ValOps {
        * decided against.
        */
       headCommitSha: newestCommitSha(allPatchData.commits) ?? undefined,
-      commitSha: this.commitSha
+      /*
+       * Spread: a project with no repository has no such commit, and saying
+       * so by leaving the key out is different from sending an empty string
+       * the Studio would try to show.
+       */
+      ...(this.git ? {
+        commitSha: this.git.commit
+      } : {})
     };
   }
   async getWebSocketNonce(profileId) {
     return fetch(`${this.contentUrl}/v1/${this.project}/websocket/nonces`, {
       method: "POST",
       body: JSON.stringify({
-        branch: this.branch,
         profileId,
-        commitSha: this.commitSha
+        /*
+         * Omitted when there is no repository, like every other request here.
+         * The content service knows this project's branch -- it is a column on
+         * the project -- and a nonce is scoped to the project and the person,
+         * not to a position in a chain.
+         */
+        ...(this.git ? {
+          branch: this.git.branch,
+          commitSha: this.git.commit
+        } : {})
       }),
       headers: {
         ...this.authHeaders,
@@ -8068,8 +8244,20 @@ class ValOpsHttp extends ValOps {
   }
   async fetchPatchesInternal(filters) {
     const params = [];
-    params.push(["branch", this.branch]);
-    params.push(["commit", this.commitSha]);
+    /*
+     * A position in the chain, WHEN THIS BUILD HAS ONE.
+     *
+     * `commit` tells the content service where this deployment sits, so it can
+     * answer with the commits at or after that point. A build with no
+     * repository has no such commit baked into it, and asking the service to
+     * resolve the position itself is strictly better than inventing one: it
+     * holds the chain, and for a project it is the only publisher of, the
+     * position IS the head.
+     */
+    if (this.git) {
+      params.push(["branch", this.git.branch]);
+      params.push(["commit", this.git.commit]);
+    }
     if (filters.patchIds) {
       for (const patchId of filters.patchIds) {
         params.push(["patch_id", patchId]);
@@ -8090,6 +8278,17 @@ class ValOpsHttp extends ValOps {
         if (parsed.success) {
           const errors = [];
           const data = parsed.data;
+          /*
+           * What the project expects of its publisher, remembered.
+           *
+           * Recorded here rather than returned because every caller of this
+           * already has what it needs and only the publish path asks the
+           * question -- and that path calls this first. See
+           * {@link publishRefusal}.
+           */
+          if (data.project) {
+            this.projectExpectation = data.project;
+          }
           for (const patchesRes of data.patches) {
             var _patchesRes$applied;
             patches.push({
@@ -8310,7 +8509,7 @@ class ValOpsHttp extends ValOps {
        * `saveSourceFilePatch`): groups are per branch, so a request without one
        * is not merely under-specified, it is rejected.
        */
-      const params = new URLSearchParams([["branch", this.branch]]);
+      const params = new URLSearchParams(this.git ? [["branch", this.git.branch]] : []);
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/patch-groups?${params}`, {
         headers: this.authHeaders
       });
@@ -8462,8 +8661,10 @@ class ValOpsHttp extends ValOps {
         patchId,
         parentPatchId: parentRef.type === "patch" ? parentRef.patchId : null,
         baseSha,
-        commit: this.commitSha,
-        branch: this.branch,
+        ...(this.git ? {
+          commit: this.git.commit,
+          branch: this.git.branch
+        } : {}),
         coreVersion: Internal.VERSION.core,
         /*
          * Group membership in the SAME request as the patch.
@@ -8629,11 +8830,28 @@ class ValOpsHttp extends ValOps {
     });
   }
   async getSourceFile(path) {
+    /*
+     * There is no file to read without a repository to read it from.
+     *
+     * Reachable only through the CLI's debug snapshot now: the publish path
+     * does not call this for such a project at all -- see
+     * {@link ValOps.mirrorsSourceFiles} -- because there is nothing for it to
+     * produce. It is an error rather than an empty string because an empty
+     * `.val.ts` would be patched successfully and committed as a module that
+     * had lost all its content.
+     */
+    if (!this.git) {
+      return {
+        error: {
+          message: `Cannot read the source of ${path}: this project has no ` + "repository, so there is no `.val.ts` to read. Its content lives " + "in Val's content service, which is the store of record for it."
+        }
+      };
+    }
     const filesRes = await this.getHttpFiles([{
       filePath: path,
       location: "repo",
       root: this.root,
-      commitSha: this.commitSha
+      commitSha: this.git.commit
     }]);
     if (filesRes.error) {
       return filesRes;
@@ -8653,11 +8871,22 @@ class ValOpsHttp extends ValOps {
   async getBinaryFile(filePath) {
     // We could also just get this from public/ on the running server. Current approach feels more clean, but will be slower / puts more server load... We might want to change this
     const requestFiles = [];
+    if (!this.git) {
+      /*
+       * A published binary lives in the repository, and there is none.
+       *
+       * `null` is this method's existing "not found", which is what a caller
+       * already handles: the Studio falls back to the patch's own copy, which
+       * is where a managed project's files stay. See the note on local files
+       * in the content service's commit handler.
+       */
+      return null;
+    }
     requestFiles.push({
       filePath: filePath,
       location: "repo",
       root: this.root,
-      commitSha: this.commitSha
+      commitSha: this.git.commit
     });
     const filesRes = await this.getHttpFiles(requestFiles);
     if (filesRes.error) {
@@ -8836,7 +9065,6 @@ class ValOpsHttp extends ValOps {
   patchGroupId) {
     try {
       var _res$headers$get3;
-      const existingBranch = this.branch;
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/commit`, {
         method: "POST",
         headers: {
@@ -8880,13 +9108,29 @@ class ValOpsHttp extends ValOps {
            * moved on.
            */
           modules: prepared.moduleVersions,
-          commit: this.commitSha,
+          /*
+           * WHERE THIS BUILD THOUGHT IT WAS -- and only for a project with a
+           * repository, which is the only thing that still reads it.
+           *
+           * The content service mints its own commit shas, so this is no
+           * longer the parent, and it never was the concurrency check: that is
+           * `expectedHeadCommitSha` against `newestCommitSha(patches.commits)`,
+           * which `/save` runs before it gets here. What is left is the git
+           * fast-forward check, which needs to know the commit this build read
+           * the branch at to tell whether the branch has moved under it.
+           *
+           * The branch goes with it. The project's branch is a column on the
+           * project, so a build asserting one could only ever disagree with
+           * the project it is publishing to.
+           */
+          ...(this.git ? {
+            commit: this.git.commit
+          } : {}),
           root: this.root,
           filesDirectory,
           baseSha: await this.getBaseSha(),
           committer,
           message,
-          existingBranch,
           newBranch,
           ...(patchGroupId !== undefined ? {
             patchGroupId
@@ -10635,7 +10879,7 @@ async function initHandlerOptions(route, opts, config) {
     valContentUrl
   });
   if (isProxyMode) {
-    var _opts$versions, _opts$versions2;
+    var _opts$git, _opts$git2, _opts$versions, _opts$versions2;
     /*
      * Why this app is in http mode, in the message that says what is missing.
      *
@@ -10648,13 +10892,30 @@ async function initHandlerOptions(route, opts, config) {
     if (!maybeApiKey || !maybeValSecret) {
       throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode" + because);
     }
-    const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
-    if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode" + because);
-    }
-    const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
-    if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode" + because);
+    /*
+     * A COMMIT IS NOT WHAT PUTS AN APP IN HTTP MODE. Credentials are.
+     *
+     * Both of these used to be required here, and the requirement was a
+     * repository disguised as a configuration check: a deployment with no
+     * commit to name -- one whose content service owns its content, which is
+     * now the normal case -- threw at boot, or, worse, never reached this
+     * branch at all and fell through to `fs` mode, looking for a working tree
+     * that was not there.
+     *
+     * Absent is a project with no repository to mirror commits into. The
+     * content service mints its own commit shas and is the store of record for
+     * content, so there is nothing missing: see `git` on {@link ValApiOptions}
+     * for what a commit is still FOR where there is one.
+     *
+     * Taken together or not at all. A commit without a branch names a point
+     * with no line of work to publish to, and a branch without a commit names
+     * a line with no position in it; either alone would be a half-configured
+     * repository that fails later, at a publish, rather than here.
+     */
+    const maybeGitCommit = ((_opts$git = opts.git) === null || _opts$git === void 0 ? void 0 : _opts$git.commit) || process.env.VAL_GIT_COMMIT;
+    const maybeGitBranch = ((_opts$git2 = opts.git) === null || _opts$git2 === void 0 ? void 0 : _opts$git2.branch) || process.env.VAL_GIT_BRANCH;
+    if (!!maybeGitCommit !== !!maybeGitBranch) {
+      throw new Error(`Val is configured with a git ${maybeGitCommit ? "commit" : "branch"} ` + `but no ${maybeGitCommit ? "branch" : "commit"}. Set both (the ` + "`git` option, or VAL_GIT_COMMIT and VAL_GIT_BRANCH) for a project " + "whose content is mirrored into a repository, or neither for one " + "whose content service is the store of record." + because);
     }
     if (!maybeValProject) {
       throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set." + because);
@@ -10672,8 +10933,19 @@ async function initHandlerOptions(route, opts, config) {
       route,
       apiKey: maybeApiKey,
       valSecret: maybeValSecret,
-      commit: maybeGitCommit,
-      branch: maybeGitBranch,
+      /*
+       * Spread, so a project with no repository has no `git` key at all rather
+       * than one holding undefined. `ValOpsHttp` asks `git === null` to decide
+       * whether to send a branch and a commit with every request, and a key
+       * that is present-but-undefined is one more thing for that check to get
+       * wrong.
+       */
+      ...(maybeGitCommit && maybeGitBranch ? {
+        git: {
+          commit: maybeGitCommit,
+          branch: maybeGitBranch
+        }
+      } : {}),
       root: opts.root,
       project: maybeValProject,
       valEnableRedirectUrl,
@@ -10736,7 +11008,7 @@ function createValOps(valModules, options) {
     });
   }
   if (options.mode === "http") {
-    return new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, {
+    return new ValOpsHttp(options.valContentUrl, options.project, options.git ?? null, {
       apiKey: options.apiKey
     }, valModules, {
       formatter: options.formatter,
@@ -10942,6 +11214,7 @@ async function resolveRemoteFileAuth(options) {
 /** What a publish reports back, in either shape. */
 
 const ValServer = (valModules, options, callbacks) => {
+  var _options$git;
   const AIContentBlock = z.union([z.object({
     type: z.literal("text"),
     text: z.string()
@@ -10973,7 +11246,7 @@ const ValServer = (valModules, options, callbacks) => {
     url.searchParams.set("state", token);
     return url.toString();
   };
-  const commit = options.mode === "http" ? options.commit : undefined;
+  const commit = options.mode === "http" ? (_options$git = options.git) === null || _options$git === void 0 ? void 0 : _options$git.commit : undefined;
   const getAppErrorUrl = error => {
     if (!options.project) {
       throw new Error("Project is not set");
@@ -11570,12 +11843,24 @@ const ValServer = (valModules, options, callbacks) => {
          * start against a server that was working.
          */
         const mode = serverOps.patchesAreLocal ? "fs" : "http";
+        /*
+         * Why publishing is unavailable, so the Studio can say so.
+         *
+         * Spread rather than set to null, so a server that can publish sends
+         * no such key at all: the Studio's "can I publish" is then the
+         * presence of the field, and there is no null to mistake for a reason
+         * it failed to compute.
+         */
+        const publishRefusal = serverOps.publishRefusal();
         return {
           status: 200,
           json: {
             ...currentStat,
             profileId: profileId ?? null,
             mode,
+            ...(publishRefusal ? {
+              publishRefusal
+            } : {}),
             config: options.config
           }
         };
@@ -12764,6 +13049,29 @@ const ValServer = (valModules, options, callbacks) => {
           patchIds,
           excludePatchOps: false
         });
+        /*
+         * Can this deployment publish this project AT ALL?
+         *
+         * After the fetch above, deliberately: that call is what tells the
+         * data layer what the project expects, and asking before it would be
+         * asking a question nothing has answered yet. It is still before
+         * anything is written, which is the part that matters.
+         *
+         * The Studio already knows -- `/stat` carries the same refusal, so the
+         * action is disabled with the reason shown. This is the second half of
+         * that: a stat can be stale by a poll, and nothing may reach `prepare`
+         * on a project it cannot mirror.
+         */
+        const refusal = serverOps.publishRefusal();
+        if (refusal) {
+          return {
+            status: 409,
+            json: {
+              message: refusal.message,
+              publishRefusal: refusal
+            }
+          };
+        }
         /*
          * Exactly the patches this request consumes, and the ONLY ones it may
          * delete afterwards.

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.132.1",
+  "version": "0.133.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/shared": "0.130.0",
-    "@valbuild/ui": "0.132.1",
-    "@valbuild/core": "0.130.0"
+    "@valbuild/core": "0.130.0",
+    "@valbuild/shared": "0.133.0",
+    "@valbuild/ui": "0.133.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22"