@valbuild/server 0.141.0 → 0.142.0

package/dist/valbuild-server.cjs.dev.js

@@ -2498,6 +2498,24 @@ function defineExternal(definition) {
   throw new Error("defineExternal is not implemented yet: phase 0 lands the contract, the registry that executes it arrives with the read endpoints.");
 }
 
+/**
+ * Does saving this commit upload a file to Val's remote host?
+ *
+ * The question `/save` asks before it reads remote credentials. It used to ask
+ * the SCHEMAS instead -- "is any of them remote?" -- and with
+ * `files: { remote: true }` every media schema is, so every save needed a
+ * `val login` token or an api key: a corrected typo included. Only a remote
+ * FILE is uploaded, so only a commit carrying one needs credentials.
+ */
+function commitCarriesRemoteFiles(preparedCommit) {
+  return Object.values(preparedCommit.patchedBinaryFilesDescriptors).some(descriptor => descriptor.remote);
+}
+
+/** Does this commit carry any file at all, remote or local? */
+function commitCarriesFiles(preparedCommit) {
+  return Object.keys(preparedCommit.patchedBinaryFilesDescriptors).length > 0;
+}
+
 const JwtPayloadSchema = z.z.object({
   sub: z.z.string(),
   exp: z.z.number(),
@@ -2698,18 +2716,41 @@ function encodeJwt(payload, sessionKey) {
  * error somebody had to answer instead of a default that silently applied.
  */
 function clientConfig(options) {
+  const config = withResolvedProject(options.config, options.project);
   if (options.mode !== "http" || options.git === undefined) {
-    return options.config;
+    return config;
   }
-  if (options.config.gitBranch !== undefined) {
-    return options.config;
+  if (config.gitBranch !== undefined) {
+    return config;
   }
   return {
-    ...options.config,
+    ...config,
     gitBranch: options.git.branch
   };
 }
 
+/**
+ * The project, filled in the same way and for the same reason as the branch.
+ *
+ * `project` may come from `VAL_PROJECT` rather than from `val.config`, and the
+ * server talks to that project either way. The Studio decides from
+ * `config.project` whether there is an assistant to offer at all (`wsEnabled`
+ * in `ValProvider`), so a project named only in the environment would have
+ * had it hidden while the server behind it was ready to serve it.
+ *
+ * `val.config` wins, as it does for the branch, and every mode gets it: unlike
+ * a branch, a project means the same thing in fs mode as in http mode.
+ */
+function withResolvedProject(config, project) {
+  if (config.project !== undefined || project === undefined) {
+    return config;
+  }
+  return {
+    ...config,
+    project
+  };
+}
+
 /**
  * Which IP addresses this server may open a connection to.
  *
@@ -3583,6 +3624,12 @@ class ValOps {
    * hash. Re-folding with the wrong list changes the base SHA for no reason.
    */
   shaModuleErrors;
+  /**
+   * The SITE's Source for the modules a proposal's snapshot replaced: what the
+   * bundle evaluated to before the snapshot went over it. Kept for
+   * {@link siteSourcesUnderSnapshot}, and only where there is a snapshot.
+   */
+  siteSourcesBeforeSnapshot = null;
   /**
    * What a save has told us each `.jsonValues()` entry now holds.
    *
@@ -3629,6 +3676,7 @@ class ValOps {
   // #region initTree
   async initSources() {
     if (this.baseSha === null || this.sourcesSha === null || this.configSha === null || this.schemaSha === null || this.sources === null || this.schemas === null || this.modulesErrors === null) {
+      var _this$options;
       const extracted = await core.extractValModules(this.valModules);
       const moduleErrors = extracted.moduleErrors.concat(findNestedJsonValuesModuleErrors(extracted.schemas));
       this.sources = extracted.sources;
@@ -3640,12 +3688,29 @@ class ValOps {
       this.modulesErrors = moduleErrors;
       this.shaEntries = extracted.shaEntries;
       this.shaModuleErrors = extracted.moduleErrors;
+      /*
+       * The snapshot, over what the modules evaluated to. Through the same
+       * door a save uses, so the SHAs move with it: they describe the Source
+       * being served, and a base SHA that still described the bundle would
+       * say the snapshot's content was the bundle's.
+       */
+      if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.snapshotSources) {
+        const site = {};
+        for (const moduleFilePath of Object.keys(this.options.snapshotSources)) {
+          const source = extracted.sources[moduleFilePath];
+          if (source !== undefined) {
+            site[moduleFilePath] = source;
+          }
+        }
+        this.siteSourcesBeforeSnapshot = site;
+        this.promoteCommittedSources(this.options.snapshotSources);
+      }
       return {
         baseSha: this.baseSha,
         schemaSha: this.schemaSha,
         sourcesSha: this.sourcesSha,
         configSha: this.configSha,
-        sources: extracted.sources,
+        sources: this.sources,
         schemas: extracted.schemas,
         moduleErrors
       };
@@ -3661,6 +3726,19 @@ class ValOps {
     };
   }
 
+  /**
+   * In a proposal: the SITE's Source for every module the proposal has saved,
+   * as the build it is based on evaluated it -- what the proposal is compared
+   * against, and what merging it changes. Every other module is the same in
+   * both, so it is not sent. `null` anywhere that is not a proposal.
+   */
+  async siteSourcesUnderSnapshot() {
+    var _this$options2;
+    if (!((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.snapshotSources)) return null;
+    await this.initSources();
+    return this.siteSourcesBeforeSnapshot;
+  }
+
   /**
    * These patches are on disk now: adopt what they produced as the committed
    * sources.
@@ -5257,9 +5335,9 @@ class ValOps {
         // https://github.com/microsoft/TypeScript/issues/36174
         let sourceFileText = null;
         if (tsChanged) {
-          var _this$options;
+          var _this$options3;
           sourceFileText = unescape(tsSourceFile.getText(tsSourceFile).replace(/\\u/g, "%u"));
-          if ((_this$options = this.options) !== null && _this$options !== void 0 && _this$options.formatter) {
+          if ((_this$options3 = this.options) !== null && _this$options3 !== void 0 && _this$options3.formatter) {
             try {
               sourceFileText = await this.options.formatter(sourceFileText, path);
             } catch (err) {
@@ -5271,13 +5349,13 @@ class ValOps {
         }
         const extraFiles = {};
         for (const [jsonPath, content] of Array.from(jsonEntryContents)) {
-          var _this$options2;
+          var _this$options4;
           if (content === null) {
             extraFiles[jsonPath] = null;
             continue;
           }
           let jsonText = JSON.stringify(content, null, 2);
-          if ((_this$options2 = this.options) !== null && _this$options2 !== void 0 && _this$options2.formatter) {
+          if ((_this$options4 = this.options) !== null && _this$options4 !== void 0 && _this$options4.formatter) {
             try {
               jsonText = await this.options.formatter(jsonText, jsonPath);
             } catch (err) {
@@ -5593,6 +5671,30 @@ class ValOps {
     };
   }
 
+  /**
+   * The proposal this server runs at the address of, or `null` on the site --
+   * and always in `fs` and memory mode, which have no proposals. See
+   * `ValProposal`.
+   */
+  currentProposal() {
+    return null;
+  }
+
+  /**
+   * The content service's proposals API, for the Studio's switcher, list and
+   * dialogs. Refused here for the reason {@link publishApi} is: there is no
+   * content service to forward to. `profileId` is the person asking.
+   */
+  async proposalsApi(_path, _init, _profileId) {
+    return {
+      status: 501,
+      contentType: "application/json",
+      body: JSON.stringify({
+        message: "This Val server has no content service, so it has no proposals."
+      })
+    };
+  }
+
   /**
    * Whether a commit here produces `.val.ts` TEXT as well as data.
    *
@@ -8796,6 +8898,111 @@ function computePatchesToDrop(prepared) {
   return dropped;
 }
 
+/**
+ * A proposal this server runs at the address of: an editor-managed branch of
+ * the project's content, served from its own copy of the content the
+ * proposal has saved -- the **snapshot**. valbuild/home `docs/proposals.md`,
+ * "Saving".
+ *
+ * A third place Source can come from, beside the two Val already has:
+ *
+ * | source provider | Source comes from                      |
+ * | --------------- | -------------------------------------- |
+ * | committed       | the bundle                             |
+ * | draft           | content, pending patches applied       |
+ * | snapshot        | the proposal's saves                   |
+ *
+ * The snapshot REPLACES the bundle's Source for the modules the proposal has
+ * saved and nothing else, on every read: a committed render, the draft a page
+ * starts from, the Studio's tree, validation and the next save's prepare. The
+ * proposal's pending patches apply on top of it, as the site's apply on top of
+ * the bundle.
+ *
+ * Handed over by the platform that serves the address, per isolate: the
+ * snapshot only changes with a save, and a save is a new isolate.
+ */
+
+/**
+ * The proposal a platform describes in its runtime env, or `undefined` when
+ * this is not a proposal's address.
+ *
+ * `VAL_PROPOSAL` and `VAL_BRANCH` name it; `VAL_OVERLAY` is the snapshot as
+ * JSON (`{ commit, modules, files }`). Throws on a snapshot that does not
+ * parse rather than serving the base build as though it were the proposal: a
+ * reviewer would be looking at the wrong content and nothing would say so.
+ */
+function proposalFromEnv(env) {
+  const name = env.VAL_PROPOSAL;
+  const branch = env.VAL_BRANCH;
+  if (!name || !branch) {
+    return undefined;
+  }
+  let parsed = {};
+  if (env.VAL_OVERLAY) {
+    try {
+      parsed = JSON.parse(env.VAL_OVERLAY);
+    } catch (err) {
+      throw new Error(`Val: proposal ${name}: VAL_OVERLAY is not JSON (${err instanceof Error ? err.message : String(err)})`, {
+        cause: err
+      });
+    }
+  }
+  if (!isObject$1(parsed)) {
+    throw new Error(`Val: proposal ${name}: VAL_OVERLAY is not an object`);
+  }
+  const modulesIn = parsed["modules"] ?? {};
+  const filesIn = parsed["files"] ?? {};
+  const commit = parsed["commit"] ?? null;
+  if (!isObject$1(modulesIn) || !isObject$1(filesIn)) {
+    throw new Error(`Val: proposal ${name}: VAL_OVERLAY's modules and files must be objects`);
+  }
+  if (commit !== null && typeof commit !== "string") {
+    throw new Error(`Val: proposal ${name}: VAL_OVERLAY's commit must be a string or null`);
+  }
+  const files = {};
+  for (const [path, text] of Object.entries(filesIn)) {
+    if (typeof text === "string") {
+      files[path] = text;
+    }
+  }
+  return {
+    name,
+    branch,
+    commit,
+    modules: modulesIn,
+    files
+  };
+}
+
+/**
+ * The proposal's saved Source, as Source: every module whose value is JSON.
+ * One place, so the server and the readers that render without it agree on
+ * what the snapshot holds.
+ */
+function proposalSnapshot(proposal) {
+  const snapshot = {};
+  for (const [path, source] of Object.entries(proposal.modules)) {
+    if (isJsonValue(source)) {
+      snapshot[path] = source;
+    }
+  }
+  return snapshot;
+}
+function isObject$1(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** What `JSON.parse` can produce, checked rather than assumed. */
+function isJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  return isObject$1(value) && Object.values(value).every(isJsonValue);
+}
+
 const textEncoder$2 = new TextEncoder();
 const PatchId = z.z.string().refine(s => !!s); // TODO: validate
 const CommitSha = z.z.string().refine(s => !!s); // TODO: validate
@@ -9149,6 +9356,8 @@ class ValOpsHttp extends ValOps {
   publishJob;
   /** See `publishBuild` on {@link ValApiOptions}; sent with every position. */
   publishBuild;
+  /** See `proposal` on {@link ValApiOptions}; `null` on the site. */
+  proposal;
 
   /** Did the host hand over the running build's source? See `projectSource`. */
   embedsSource() {
@@ -9221,7 +9430,10 @@ class ValOpsHttp extends ValOps {
    * getSettings / uploadRemoteFile / getPresignedAuthNonce.
    */
   auth, valModules, options) {
-    super(valModules, options);
+    super(valModules, options !== null && options !== void 0 && options.proposal ? {
+      ...options,
+      snapshotSources: proposalSnapshot(options.proposal)
+    } : options);
     this.contentUrl = contentUrl;
     this.project = project;
     this.git = git;
@@ -9231,7 +9443,15 @@ class ValOpsHttp extends ValOps {
       Authorization: `Bearer ${auth.apiKey}`
     };
     this.root = (options === null || options === void 0 ? void 0 : options.root) ?? "";
-    this.projectSource = (options === null || options === void 0 ? void 0 : options.projectSource) ?? null;
+    this.proposal = (options === null || options === void 0 ? void 0 : options.proposal) ?? null;
+    /*
+     * In a proposal, the text its saves wrote over the text the build was made
+     * from: the next save patches the last one's `.val.ts`, not the base's.
+     */
+    this.projectSource = this.proposal !== null ? {
+      ...((options === null || options === void 0 ? void 0 : options.projectSource) ?? {}),
+      ...this.proposal.files
+    } : (options === null || options === void 0 ? void 0 : options.projectSource) ?? null;
     this.publishJob = (options === null || options === void 0 ? void 0 : options.publishJob) ?? null;
     this.publishBuild = (options === null || options === void 0 ? void 0 : options.publishBuild) ?? null;
     this.mirrorsSourceFiles = git !== null || this.projectSource !== null;
@@ -9260,7 +9480,8 @@ class ValOpsHttp extends ValOps {
    */
   publishRefusal() {
     var _this$projectExpectat;
-    if (this.git !== null) {
+    // A save in a proposal mirrors nothing: it reaches git by merging.
+    if (this.git !== null || this.proposal !== null) {
       return null;
     }
     /*
@@ -9297,6 +9518,13 @@ class ValOpsHttp extends ValOps {
    */
   sourceMode() {
     var _this$projectExpectat2;
+    /*
+     * Not reported in a proposal, whatever the project is. The Studio reads
+     * `managed` as "I am the deployer" and follows a commit with a build it
+     * publishes to the SITE -- and a proposal's commit is a Save, which its
+     * address serves without any build at all.
+     */
+    if (this.proposal !== null) return null;
     return ((_this$projectExpectat2 = this.projectExpectation) === null || _this$projectExpectat2 === void 0 ? void 0 : _this$projectExpectat2.sourceMode) ?? null;
   }
 
@@ -9331,6 +9559,8 @@ class ValOpsHttp extends ValOps {
     }).catch(() => undefined);
   }
   publishesAsJobs() {
+    // A proposal's Save is a commit on its branch; its merge is the publish.
+    if (this.proposal !== null) return false;
     const expected = this.projectExpectation;
     if (expected === null) return false;
     return expected.publishJobs ?? expected.sourceMode === "managed";
@@ -9450,6 +9680,10 @@ class ValOpsHttp extends ValOps {
    * segment gets through.
    */
   static publishApiPathAllowed(path) {
+    // A merge's prepare is content's own, from the proposal's last save.
+    if (/^\/publish-jobs\/[A-Za-z0-9_-]{1,100}\/merge-prepare$/.test(path)) {
+      return true;
+    }
     if (path === "/build-target" || path === "/project-source" || path === "/update-target" || path === "/publish" ||
     // Where "View run" goes, for a connected build CI reported failed.
     // Read only: reporting a run is CI's, with its own token.
@@ -9472,6 +9706,20 @@ class ValOpsHttp extends ValOps {
     return /^\/publish\/[A-Za-z0-9_-]+(\/(artifacts|verify|promote))?$/.test(path);
   }
   async publishApi(path, init) {
+    /*
+     * Nothing is published from a proposal's address: its way to the site is
+     * a merge. The publish API reaches the SITE's builds and jobs, so a
+     * Studio there that asked would be publishing over the site.
+     */
+    if (this.proposal !== null && !ValOpsHttp.mergeApiPathAllowed(init.method, path)) {
+      return {
+        status: 403,
+        contentType: "application/json",
+        body: JSON.stringify({
+          message: "This is a proposal's address: nothing is published from here. " + "A proposal reaches the site by being merged."
+        })
+      };
+    }
     if (!ValOpsHttp.publishApiPathAllowed(path)) {
       return {
         status: 403,
@@ -9483,6 +9731,82 @@ class ValOpsHttp extends ValOps {
     }
     return this.callPublishApi(path, init);
   }
+  currentProposal() {
+    return this.proposal === null ? null : {
+      name: this.proposal.name,
+      branch: this.proposal.branch
+    };
+  }
+
+  /**
+   * Which proposal calls the browser may make, by method and the path after
+   * `/proposals`: list and open, read and rename one, and close, reopen and
+   * retry its setup. Not `/save` -- the Studio saves through `/save`, which
+   * prepares the commit here -- and not `/patches`, which moves the site's
+   * changes into a proposal and has no screen yet.
+   */
+  static proposalsApiAllowed(method, path) {
+    if (path === "") return method === "GET" || method === "POST";
+    const one = /^\/[0-9a-f]{20}$/.test(path);
+    if (one) return method === "GET" || method === "PATCH";
+    if (method === "GET") return /^\/[0-9a-f]{20}\/merge-checks$/.test(path);
+    return method === "POST" && /^\/[0-9a-f]{20}\/(close|reopen|setup\/retry|merge)$/.test(path);
+  }
+
+  /**
+   * What a proposal's address may reach of the publish API: building ITS OWN
+   * merge, and nothing that publishes the site's changes. The merge's prepare
+   * (content's, from the proposal's last save), the build it needs -- the
+   * site's build target and source, declaring and uploading the build -- and
+   * the job's own steps. Not a press of the site's Publish, not `next` (which
+   * would hand this tab a site job), and not the site job's prepare.
+   */
+  static mergeApiPathAllowed(method, path) {
+    if (path === "/build-target" || path === "/project-source" || path === "/publish") {
+      return true;
+    }
+    if (/^\/publish\/[A-Za-z0-9_-]+\/artifacts$/.test(path)) return true;
+    // Where its press is -- read only: a POST there is the site's Try again.
+    if (method === "GET" && path !== "/publish-requests/try-again" && /^\/publish-requests\/[A-Za-z0-9_-]{1,100}$/.test(path)) return true;
+    return /^\/publish-jobs\/[A-Za-z0-9_-]{1,100}\/(merge-prepare|steps|renew|cancel)$/.test(path);
+  }
+  async proposalsApi(path, init, profileId) {
+    const json = "application/json";
+    if (!ValOpsHttp.proposalsApiAllowed(init.method, path)) {
+      return {
+        status: 403,
+        contentType: json,
+        body: JSON.stringify({
+          message: `'${init.method} ${path}' is not part of the proposals API.`
+        })
+      };
+    }
+    const res = await fetch(`${this.contentUrl}/v1/${this.project}/proposals${path}`, {
+      method: init.method,
+      headers: {
+        ...this.authHeaders,
+        /*
+         * WHO is asking, as for a commit: the app's key names the project,
+         * and a proposal is opened, renamed and closed by a person -- content
+         * refuses those writes from a credential that names nobody.
+         */
+        ...(profileId !== null ? {
+          "x-val-profile-id": profileId
+        } : {}),
+        ...(init.body === undefined ? {} : {
+          "Content-Type": json
+        })
+      },
+      ...(init.body === undefined ? {} : {
+        body: init.body
+      })
+    });
+    return {
+      status: res.status,
+      body: await res.text(),
+      contentType: res.headers.get("Content-Type") ?? json
+    };
+  }
 
   /**
    * A publish job's prepare, sent to content: the job's sources, archived
@@ -9783,6 +10107,42 @@ class ValOpsHttp extends ValOps {
       } : {})
     };
   }
+
+  /**
+   * Where this server sits in the content service's chain, as every request
+   * that asks about a position says it.
+   *
+   * In a proposal: its branch, and the save its snapshot is (none before the
+   * first). The content service then answers with what came after that save
+   * and nothing else -- never the site's position, which would replay the
+   * proposal's own saves over a snapshot that already holds them. Otherwise
+   * the commit this build was made from, or, for a build a tab made, its job.
+   */
+  position() {
+    if (this.proposal !== null) {
+      return {
+        branch: this.proposal.branch,
+        ...(this.proposal.commit !== null ? {
+          commit: this.proposal.commit
+        } : {})
+      };
+    }
+    if (this.git) {
+      return {
+        branch: this.git.branch,
+        commit: this.git.commit
+      };
+    }
+    return this.publishJob !== null ? {
+      job: this.publishJob
+    } : {};
+  }
+
+  /** The branch this server's patches are on, where it knows it. */
+  ownBranch() {
+    var _this$proposal, _this$git;
+    return ((_this$proposal = this.proposal) === null || _this$proposal === void 0 ? void 0 : _this$proposal.branch) ?? ((_this$git = this.git) === null || _this$git === void 0 ? void 0 : _this$git.branch);
+  }
   async getWebSocketNonce(profileId) {
     return fetch(`${this.contentUrl}/v1/${this.project}/websocket/nonces`, {
       method: "POST",
@@ -9794,12 +10154,24 @@ class ValOpsHttp extends ValOps {
          * 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
-        } : this.publishJob !== null ? {
-          job: this.publishJob
-        } : {}),
+        ...(() => {
+          const {
+            branch,
+            commit,
+            job
+          } = this.position();
+          return {
+            ...(branch !== undefined ? {
+              branch
+            } : {}),
+            ...(commit !== undefined ? {
+              commitSha: commit
+            } : {}),
+            ...(job !== undefined ? {
+              job
+            } : {})
+          };
+        })(),
         // Which build is asking, beside what it says about itself.
         ...(this.publishBuild !== null ? {
           build: this.publishBuild
@@ -9981,12 +10353,10 @@ class ValOpsHttp extends ValOps {
      * 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]);
-    } else if (this.publishJob !== null) {
-      // A build a tab made has no commit, and says which job it was made for.
-      params.push(["job", this.publishJob]);
+    // A build a tab made has no commit, and says which job it was made for;
+    // a proposal says its branch and its save. See `position`.
+    for (const [key, value] of Object.entries(this.position())) {
+      if (value !== undefined) params.push([key, value]);
     }
     /*
      * And WHICH build this is, when the platform running it says: the only
@@ -10259,6 +10629,23 @@ class ValOpsHttp extends ValOps {
    * cache: a second render a second later asks again.
    */
   patchGroupsCache = null;
+
+  /**
+   * Forget the remembered group list, after a write through this server.
+   *
+   * A write changes membership -- a save joins its author's group, a delete or
+   * an unstage leaves it -- and the window above is long enough for the next
+   * render to be served the list from before it: an editor who saved and
+   * reloaded inside a second was shown their draft without the change they had
+   * just made. Called once the write has answered, so a read that started
+   * while it was in flight cannot leave the old list behind it.
+   *
+   * Only this instance's writes. Another instance's write is still seen at
+   * most one window late, which is what the window is for.
+   */
+  forgetPatchGroups() {
+    this.patchGroupsCache = null;
+  }
   async getPatchGroups(options) {
     const now = Date.now();
     if ((options === null || options === void 0 ? void 0 : options.fresh) !== true && this.patchGroupsCache !== null && now - this.patchGroupsCache.at < PATCH_GROUPS_CACHE_MS) {
@@ -10290,6 +10677,17 @@ class ValOpsHttp extends ValOps {
     return res;
   }
   async fetchPatchGroups() {
+    /*
+     * A proposal has no patch groups: its changes are one unit, saved
+     * together, and the content service answers 404 for groups on its branch.
+     * "Unsupported" is exactly that answer, and it is what makes a draft in a
+     * proposal show all of the proposal's changes rather than one person's.
+     */
+    if (this.proposal !== null) {
+      return {
+        status: "unsupported"
+      };
+    }
     try {
       /*
        * `branch` is REQUIRED by the endpoint, which answers 400 without it.
@@ -10298,7 +10696,8 @@ 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(this.git ? [["branch", this.git.branch]] : []);
+      const branch = this.ownBranch();
+      const params = new URLSearchParams(branch !== undefined ? [["branch", branch]] : []);
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/patch-groups?${params}`, {
         headers: this.authHeaders
       });
@@ -10349,8 +10748,9 @@ class ValOpsHttp extends ValOps {
    * Without one the content API uses the project's own, as it does for reads.
    */
   ownGroupBranch() {
-    return this.git ? {
-      branch: this.git.branch
+    const branch = this.ownBranch();
+    return branch !== undefined ? {
+      branch
     } : {};
   }
   async mutatePatchGroup(method, path, body,
@@ -10373,6 +10773,22 @@ class ValOpsHttp extends ValOps {
    * on its own there and this adds nothing.
    */
   authorId) {
+    if (this.proposal !== null) {
+      return {
+        status: 409,
+        patchIds: [],
+        error: {
+          message: "A proposal's changes are saved together, so there is nothing to stage or unstage in one."
+        }
+      };
+    }
+    try {
+      return await this.mutatePatchGroupRequest(method, path, body, authorId);
+    } finally {
+      this.forgetPatchGroups();
+    }
+  }
+  async mutatePatchGroupRequest(method, path, body, authorId) {
     try {
       const res = await fetch(`${this.contentUrl}/v1/${this.project}/${path}`, {
         method,
@@ -10465,7 +10881,13 @@ class ValOpsHttp extends ValOps {
         patchId,
         parentPatchId: parentRef.type === "patch" ? parentRef.patchId : null,
         baseSha,
-        ...(this.git ? {
+        /*
+         * In a proposal, its branch alone: the content service files the
+         * patch there, and only for an open proposal.
+         */
+        ...(this.proposal !== null ? {
+          branch: this.proposal.branch
+        } : this.git ? {
           commit: this.git.commit,
           branch: this.git.branch
         } : {}),
@@ -10542,7 +10964,7 @@ class ValOpsHttp extends ValOps {
         errorType: "other",
         message: `Could save source file patch (connection error?): ${e instanceof Error ? e.message : e.toString()}`
       });
-    });
+    }).finally(() => this.forgetPatchGroups());
   }
 
   /**
@@ -10834,12 +11256,11 @@ class ValOpsHttp extends ValOps {
       if (res.ok) {
         const parsed = DeletePatchesResponse.safeParse(await res.json());
         if (parsed.success) {
-          var _this$git;
           const errors = {};
           for (const err of parsed.data.errors || []) {
             errors[err.patchId] = err;
           }
-          const headVersion = ownBranchVersion(parsed.data.headVersions, (_this$git = this.git) === null || _this$git === void 0 ? void 0 : _this$git.branch);
+          const headVersion = ownBranchVersion(parsed.data.headVersions, this.ownBranch());
           const version = headVersion !== undefined ? {
             headVersion
           } : {};
@@ -10872,7 +11293,7 @@ class ValOpsHttp extends ValOps {
           message: `Could not delete patches (connection error?): ${e instanceof Error ? e.message : e.toString()}`
         }
       };
-    });
+    }).finally(() => this.forgetPatchGroups());
   }
   async commit(prepared, message, committer, filesDirectory, newBranch,
   /**
@@ -10892,7 +11313,13 @@ class ValOpsHttp extends ValOps {
   patchGroupId) {
     try {
       var _res$headers$get3;
-      const res = await fetch(`${this.contentUrl}/v1/${this.project}/commit`, {
+      /*
+       * A save in a proposal is a commit on the proposal's branch, at its own
+       * route: the site's `/commit` refuses a proposal's patches, which is
+       * the line that keeps them off the site until a merge.
+       */
+      const commitUrl = this.proposal !== null ? `${this.contentUrl}/v1/${this.project}/proposals/${this.proposal.name}/save` : `${this.contentUrl}/v1/${this.project}/commit`;
+      const res = await fetch(commitUrl, {
         method: "POST",
         headers: {
           ...this.authHeaders,
@@ -12957,6 +13384,9 @@ async function initHandlerOptions(route, opts, config) {
       ...(opts.publishBuild !== undefined ? {
         publishBuild: opts.publishBuild
       } : {}),
+      ...(opts.proposal !== undefined ? {
+        proposal: opts.proposal
+      } : {}),
       project: maybeValProject,
       valEnableRedirectUrl,
       valDisableRedirectUrl,
@@ -13032,6 +13462,9 @@ function createValOps(valModules, options) {
       } : {}),
       ...(options.publishBuild !== undefined ? {
         publishBuild: options.publishBuild
+      } : {}),
+      ...(options.proposal !== undefined ? {
+        proposal: options.proposal
       } : {})
     });
   }
@@ -13630,6 +14063,32 @@ const ValServer = (valModules, options, callbacks) => {
       };
     }
   };
+
+  /** The person a session names, or `null` for an anonymous one. */
+  const profileOf = auth => "id" in auth && auth.id ? auth.id : null;
+
+  /** One proposals-API call, carried as `proxyPublishApi` carries one. */
+  const proxyProposalsApi = async (path, method, profileId, body) => {
+    const answer = await serverOps.proposalsApi(path ?? "", {
+      method,
+      ...(body === undefined ? {} : {
+        body
+      })
+    }, profileId);
+    try {
+      return {
+        status: answer.status,
+        json: JSON.parse(answer.body)
+      };
+    } catch {
+      return {
+        status: answer.status,
+        json: {
+          message: answer.body.trim() === "" ? `The proposals API answered ${answer.status} with no body.` : `The proposals API answered ${answer.status}: ${answer.body.slice(0, 300)}`
+        }
+      };
+    }
+  };
   return {
     "/draft/enable": {
       GET: async req => {
@@ -14063,6 +14522,8 @@ const ValServer = (valModules, options, callbacks) => {
          * shows one story to a project that lives by the other.
          */
         const sourceMode = serverOps.sourceMode();
+        // Spread like the two above: absent is "on the site".
+        const proposal = serverOps.currentProposal();
         return {
           status: 200,
           json: {
@@ -14078,6 +14539,9 @@ const ValServer = (valModules, options, callbacks) => {
             ...(sourceMode ? {
               publishJobs: serverOps.publishesAsJobs()
             } : {}),
+            ...(proposal ? {
+              proposal
+            } : {}),
             // Not `options.config` verbatim: in proxy mode the branch the
             // server resolved is filled in where the file did not name one.
             // See `clientConfig`.
@@ -14127,6 +14591,78 @@ const ValServer = (valModules, options, callbacks) => {
         return proxyPublishApi(req.path, "POST", req.body === undefined ? undefined : JSON.stringify(req.body));
       }
     },
+    /**
+     * The content service's proposals API, reached through this deployment --
+     * the switcher, the list and the dialogs. The session is checked and its
+     * profile sent along, because a proposal is changed by a person; see
+     * `ValOpsHttp.proposalsApi` for what may be reached.
+     */
+    "/proposals-api": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        return proxyProposalsApi(req.path, "GET", profileOf(auth));
+      },
+      POST: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        return proxyProposalsApi(req.path, "POST", profileOf(auth), JSON.stringify(req.body ?? {}));
+      },
+      PATCH: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        return proxyProposalsApi(req.path, "PATCH", profileOf(auth), JSON.stringify(req.body ?? {}));
+      }
+    },
+    "/proposal-site-sources": {
+      GET: async req => {
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const modules = await serverOps.siteSourcesUnderSnapshot();
+        if (modules === null) {
+          return {
+            status: 404,
+            json: {
+              message: "This is not a proposal's address."
+            }
+          };
+        }
+        return {
+          status: 200,
+          json: {
+            modules
+          }
+        };
+      }
+    },
     "/upload/patches": {
       POST: async req => {
         if (serverOps instanceof ValOpsHttp) {
@@ -15105,9 +15641,23 @@ const ValServer = (valModules, options, callbacks) => {
               patchIds: undefined,
               excludePatchOps: false
             });
+            /*
+             * Membership from THIS response when it carries one, not from the
+             * group list `resolveOwnPatchScope` read.
+             *
+             * That list is a separate request, remembered for a second
+             * (`ValOpsHttp.getPatchGroups`), so it can be older than the chain
+             * fetched here: an editor who saved and reloaded at once was
+             * rendered without the patch they had just written, because the
+             * list still had their group without it. The content service reads
+             * the chain and each patch's groups in one transaction, and
+             * `fetchPatches` folds that onto `patchGroups` -- so the patches
+             * and who owns them come from the same moment.
+             */
+            const own = ownPatchScopeFor(all, "id" in auth && auth.id || undefined, ownPatchIds);
             patchOps = {
               ...all,
-              patches: scopedPatches(all.patches, ownPatchIds)
+              patches: scopedPatches(all.patches, own)
             };
           } else if (requestedPatchIds !== undefined && requestedPatchIds.length === 0) {
             /*
@@ -15732,7 +16282,13 @@ const ValServer = (valModules, options, callbacks) => {
            * tree; a store with no working tree does only the push.
            */
           if (serverOps instanceof ValOpsMemory) {
-            const isRemoteRequired = getIsRemoteRequired(await serverOps.getSchemas());
+            /*
+             * A commit with no files uploads nothing and needs no credentials;
+             * see `commitCarriesRemoteFiles`. One with a LOCAL file still goes
+             * through `uploadRemoteFiles` where the project is remote, because
+             * that is where a local file is refused rather than dropped.
+             */
+            const isRemoteRequired = commitCarriesRemoteFiles(preparedCommit) || commitCarriesFiles(preparedCommit) && getIsRemoteRequired(await serverOps.getSchemas());
             if (isRemoteRequired) {
               const authRes = await getRemoteFileAuth();
               if (authRes.status !== 200) {
@@ -15755,7 +16311,9 @@ const ValServer = (valModules, options, callbacks) => {
           }
           if (serverOps instanceof ValOpsFS) {
             var _remoteFileAuthRes;
-            const isRemoteRequired = getIsRemoteRequired(await serverOps.getSchemas());
+            // Credentials when THIS save uploads a remote file, not whenever
+            // the project has a remote schema. See `commitCarriesRemoteFiles`.
+            const isRemoteRequired = commitCarriesRemoteFiles(preparedCommit);
             let mode;
             let remoteFileAuthRes;
             if (isRemoteRequired) {
@@ -17072,6 +17630,24 @@ chain, deleted, requested) {
  * `undefined` means "apply everything", which is what every caller that does
  * not ask for scoping gets and must keep getting.
  */
+/** The patches in this author's OPEN groups: what a scoped draft shows. */
+function ownPatchIdsIn(patchGroups, authorId) {
+  return patchGroups.filter(group => group.publishedAt === null && group.authorId === authorId).flatMap(group => group.patchIds);
+}
+
+/**
+ * Whose pending patches a scoped draft shows, taken from the SAME response as
+ * the patches when it says, and from the list read beforehand only when not.
+ *
+ * See the call in `/sources/~`: the list read beforehand can be older than the
+ * chain, and the response's membership cannot be.
+ */
+function ownPatchScopeFor(fetched, authorId, remembered) {
+  if (fetched.patchGroups === undefined || authorId === undefined) {
+    return remembered;
+  }
+  return ownPatchIdsIn(fetched.patchGroups, authorId);
+}
 async function resolveOwnPatchScope(
 /*
  * `ValOps`, not the two concrete stores: the one thing this needs is whether
@@ -17126,7 +17702,7 @@ serverOps, opts) {
          * nothing, and base is the honest answer. Distinct from the
          * case above, which is why the two are not one expression.
          */
-        ownPatchIds = groupsRes.patchGroups.filter(group => group.publishedAt === null && group.authorId === opts.authorId).flatMap(group => group.patchIds);
+        ownPatchIds = ownPatchIdsIn(groupsRes.patchGroups, opts.authorId);
         /*
          * Scoping applies to PENDING work only. Anything already
          * committed is part of everyone's view.
@@ -23229,6 +23805,8 @@ exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;
 exports.persistPersonalAccessToken = persistPersonalAccessToken;
 exports.planJsonValuesEntryExtraction = planJsonValuesEntryExtraction;
+exports.proposalFromEnv = proposalFromEnv;
+exports.proposalSnapshot = proposalSnapshot;
 exports.readCapturedReport = readCapturedReport;
 exports.readPatchStore = readPatchStore;
 exports.rebaseContentOp = rebaseContentOp;