@valbuild/shared 0.136.10 → 0.137.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @valbuild/shared
 
+## 0.137.0
+
+### Minor Changes
+
+- [#676](https://github.com/valbuild/val/pull/676) [`48ac9f0`](https://github.com/valbuild/val/commit/48ac9f06dd59a5b4ca60232b1ef198cf42f23aa6) Thanks [@freekh](https://github.com/freekh)! - A link-check endpoint, so the Studio can find out whether an external page is
+  still there.
+
+  `POST /external-urls/check` opens up to twenty URLs and reports what answered:
+  the final status after redirects, where it ended up, and how long it took. The
+  Studio's Check button in the external pages dialog is the only caller, and it
+  cannot do this itself — a cross-origin `fetch` from a browser cannot read a
+  response status without CORS headers no ordinary site sends.
+
+  It is an endpoint that makes outbound requests to addresses your content
+  supplies, so it is built as one:
+
+  - It is behind the same session check as every other authenticated route —
+    which, in fs mode, means the same anonymous access every other route allows
+    on a developer's own machine. It is not a new way in; it is the same door.
+  - It refuses to connect to anything that is not a public internet address —
+    loopback, link-local, the private ranges, the carrier-grade NAT range, and
+    the cloud metadata service that hands out instance credentials. The check is
+    on the RESOLVED address rather than the hostname, so a name that resolves to
+    `127.0.0.1` is refused, and it runs again at every redirect hop.
+  - It answers with one generic message for anything it refused, so the endpoint
+    cannot be used to find out what a hostname resolves to from inside your
+    network. The reason is logged on the server.
+  - `HEAD` first, `GET` only where a site answers 405 or 501 to it, and no
+    connection reuse between targets.
+
+- [#746](https://github.com/valbuild/val/pull/746) [`e2bfc0e`](https://github.com/valbuild/val/commit/e2bfc0e40383fe25d3ec0473d1032f6264a8939f) Thanks [@freekh](https://github.com/freekh)! - A site hosted on Val (a managed project, with no repository of its own) can now be updated from the Studio. **Settings → Updates** says whether a newer version of the software the site runs on is available, lists the packages that move and their versions, and offers **Update site**.
+
+  Updating rebuilds the site in the browser on the new versions and publishes it through the ordinary publish, so it is checked before it goes live: if the updated site does not render, nothing changes and the site keeps running the old versions. Unpublished changes are kept and are **not** published by an update. After it goes live, reload the Studio to use the new one.
+
+  In Safari, which cannot build the site in the Studio's own page, Update site opens a tab that builds and publishes it, the same way a publish does there, and the Studio follows its progress.
+
+  A Studio that was opened before the site was updated no longer publishes: pressing Publish asks you to reload first, and nothing is saved until you do. Your unpublished changes are kept. Without this, a Studio left open from before an update would have built the site with the previous version of itself.
+
+  The versions come from the template the project was made from, as the platform last built it. A project whose code lives in a repository is not offered this; its dependencies are updated there.
+
+  For hosts: `@valbuild/server` forwards `GET` and `POST /api/val/publish-api/update-target` to the content service, beside `/build-target` and `/project-source`.
+
+### Patch Changes
+
+- [#748](https://github.com/valbuild/val/pull/748) [`beda04b`](https://github.com/valbuild/val/commit/beda04bd326cbab18ed103e8d43917b16f43bd8c) Thanks [@freekh](https://github.com/freekh)! - A save is no longer refused once because an older answer from the server arrived after a newer one. The content service now reports a version of its list of changes, which goes up with every save, discard and publish. The Studio ignores any answer older than one it already has, including the answer to its own last save, discard or publish, so a discarded change can no longer briefly come back, and a published one can no longer briefly show as unpublished.
+- Updated dependencies [[`43b58f2`](https://github.com/valbuild/val/commit/43b58f2962840883badf91950da2c51b89d1c7cb)]:
+  - @valbuild/core@0.137.0
+
 ## 0.136.10
 
 ### Patch Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -440,6 +440,7 @@ export declare const Api: {
                     appliedPatches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
                     headCommitSha: z.ZodOptional<z.ZodString>;
                     headPatchId: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
                     commits: z.ZodArray<z.ZodObject<{
                         commitSha: z.ZodString;
                         clientCommitSha: z.ZodNullable<z.ZodString>;
@@ -567,6 +568,55 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    /**
+     * Open a batch of external URLs and report what answered.
+     *
+     * A batch rather than one URL because the client checks a list, and a POST
+     * rather than a GET because the list is the input and does not belong in a
+     * URL or a cache.
+     *
+     * The server makes outbound requests to addresses this body supplies, which
+     * is SSRF by construction - see `linkCheck/addressGuard.ts` for the deny
+     * list that makes it safe, and `docs/plans/external-page-link-checks.md` for
+     * why it is a deny list on the RESOLVED address.
+     */
+    "/external-urls/check": {
+        POST: {
+            req: {
+                body: z.ZodObject<{
+                    urls: z.ZodArray<z.ZodString>;
+                }, z.core.$strip>;
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    results: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodLiteral<"answered">;
+                        code: z.ZodNumber;
+                        finalUrl: z.ZodString;
+                        ms: z.ZodNumber;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"unreachable">;
+                        message: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"timeout">;
+                        ms: z.ZodNumber;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"skipped">;
+                        message: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/direct-file-upload-settings": {
         POST: {
             req: {
@@ -608,6 +658,7 @@ export declare const Api: {
                 };
                 body: z.ZodOptional<z.ZodObject<{
                     unstagePatchIds: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    reportHeadVersion: z.ZodOptional<z.ZodLiteral<true>>;
                 }, z.core.$strip>>;
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
@@ -632,7 +683,10 @@ export declare const Api: {
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
-                json: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                json: z.ZodUnion<readonly [z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>, z.ZodObject<{
+                    deleted: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
         PUT: {
@@ -692,6 +746,7 @@ export declare const Api: {
                         patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
                     }, z.core.$strip>]>;
                     patchGroupId: z.ZodOptional<z.ZodString>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
@@ -1131,6 +1186,7 @@ export declare const Api: {
                         moduleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
                         message: z.ZodString;
                     }, z.core.$strip>>>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<403>;

package/dist/declarations/src/internal/publish/protocol.d.ts

@@ -115,6 +115,84 @@ declare const projectSourceResponse: z.ZodObject<{
     publicPaths: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 export type ProjectSourceResponse = z.infer<typeof projectSourceResponse>;
+/**
+ * Whether a managed project can be updated onto its template's current seed,
+ * and -- when it is asked with `POST`, the press -- what to build against.
+ *
+ * An update rebuilds the site as it is on newer dependencies. The loader
+ * decides whether there is one; content adds whether the project is managed at
+ * all, and the branch head the rebuild is wired at, because an update
+ * publishes no content of its own.
+ *
+ * `target` is a `/build-target` answer whose project half is the SEED's
+ * dependency layer, already copied into the project so a publish can name it.
+ * Only a `POST` carries it.
+ */
+declare const dependencyChange: z.ZodObject<{
+    name: z.ZodString;
+    section: z.ZodEnum<{
+        dependencies: "dependencies";
+        devDependencies: "devDependencies";
+    }>;
+    from: z.ZodNullable<z.ZodString>;
+    to: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const updateTargetResponse: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"current">;
+    template: z.ZodString;
+    layerRev: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    template: z.ZodString;
+    changes: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        section: z.ZodEnum<{
+            dependencies: "dependencies";
+            devDependencies: "devDependencies";
+        }>;
+        from: z.ZodNullable<z.ZodString>;
+        to: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    layerRev: z.ZodObject<{
+        from: z.ZodNullable<z.ZodString>;
+        to: z.ZodString;
+    }, z.core.$strip>;
+    packageJson: z.ZodString;
+    commit: z.ZodNullable<z.ZodString>;
+    branch: z.ZodString;
+    target: z.ZodOptional<z.ZodObject<{
+        base: z.ZodObject<{
+            rev: z.ZodString;
+            shellRev: z.ZodString;
+            rscShellRev: z.ZodString;
+            modules: z.ZodRecord<z.ZodString, z.ZodString>;
+            rscModules: z.ZodRecord<z.ZodString, z.ZodString>;
+            paths: z.ZodObject<{
+                baseFromProject: z.ZodString;
+                projectVendorDir: z.ZodString;
+                rscVendorBase: z.ZodString;
+                rscRuntimeSpecifier: z.ZodString;
+                rscRuntimePath: z.ZodString;
+                flightServer: z.ZodString;
+                serverFnBase: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        project: z.ZodObject<{
+            rev: z.ZodNullable<z.ZodString>;
+            rsc: z.ZodBoolean;
+            modules: z.ZodRecord<z.ZodString, z.ZodString>;
+            css: z.ZodRecord<z.ZodString, z.ZodString>;
+            workerOnly: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>], "status">;
+export type UpdateTargetResponse = z.infer<typeof updateTargetResponse>;
+export type DependencyChange = z.infer<typeof dependencyChange>;
+export declare const parseUpdateTarget: (body: unknown) => UpdateTargetResponse;
 export declare const parseBuildTarget: (body: unknown) => BuildTargetResponse;
 export declare const parseProjectSource: (body: unknown) => ProjectSourceResponse;
 /**

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -1503,6 +1503,28 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * What answered when one URL was opened.
+ *
+ * The one place the Studio's `ExternalUrlProbeResult` and the server's
+ * `ProbeResult` meet, so the two cannot drift without this failing to parse.
+ */
+var ExternalUrlProbeResult = zod.z.union([zod.z.object({
+  kind: zod.z.literal("answered"),
+  code: zod.z.number(),
+  finalUrl: zod.z.string(),
+  ms: zod.z.number()
+}), zod.z.object({
+  kind: zod.z.literal("unreachable"),
+  message: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("timeout"),
+  ms: zod.z.number()
+}), zod.z.object({
+  kind: zod.z.literal("skipped"),
+  message: zod.z.string()
+})]);
+
 /**
  * Why a publish cannot happen, in a form the Studio can show.
  *
@@ -1991,6 +2013,13 @@ var Api = {
            * content service that predates it sends nothing.
            */
           headPatchId: PatchId.nullable().optional(),
+          /**
+           * The version of the chain `headPatchId` was read at, bumped by
+           * every write and delete. `/stat` has more than one caller, so
+           * answers can land out of order; a client keeps the head with the
+           * highest version. Optional, for the same reason `headPatchId` is.
+           */
+          headVersion: zod.z.number().optional(),
           commits: zod.z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2144,6 +2173,42 @@ var Api = {
       })])
     }
   },
+  /**
+   * Open a batch of external URLs and report what answered.
+   *
+   * A batch rather than one URL because the client checks a list, and a POST
+   * rather than a GET because the list is the input and does not belong in a
+   * URL or a cache.
+   *
+   * The server makes outbound requests to addresses this body supplies, which
+   * is SSRF by construction - see `linkCheck/addressGuard.ts` for the deny
+   * list that makes it safe, and `docs/plans/external-page-link-checks.md` for
+   * why it is a deny list on the RESOLVED address.
+   */
+  "/external-urls/check": {
+    POST: {
+      req: {
+        body: zod.z.object({
+          /*
+           * Capped, and the cap is the point rather than a formality: each URL
+           * is an outbound connection, and a body is not allowed to ask this
+           * server to open a thousand of them. The client sends ten at a time.
+           */
+          urls: zod.z.array(zod.z.string()).min(1).max(20)
+        }),
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          /** Keyed by the URL exactly as it was asked about. */
+          results: zod.z.record(zod.z.string(), ExternalUrlProbeResult)
+        })
+      })])
+    }
+  },
   "/direct-file-upload-settings": {
     POST: {
       req: {
@@ -2195,7 +2260,14 @@ var Api = {
            * groups, and a client that predates this is deleting correctly,
            * just not repairing.
            */
-          unstagePatchIds: zod.z.array(PatchId).optional()
+          unstagePatchIds: zod.z.array(PatchId).optional(),
+          /*
+           * Answer with `{ deleted, headVersion }` rather than the bare id
+           * array. Asked for rather than always sent, because the array is
+           * what a Studio bundle from before this parses — and a tab left
+           * open across a deploy still runs one.
+           */
+          reportHeadVersion: zod.z.literal(true).optional()
         }).optional(),
         cookies: {
           val_session: zod.z.string().optional()
@@ -2209,7 +2281,16 @@ var Api = {
         })
       }), zod.z.object({
         status: zod.z.literal(200),
-        json: zod.z.array(PatchId)
+        json: zod.z.union([zod.z.array(PatchId), zod.z.object({
+          deleted: zod.z.array(PatchId),
+          /**
+           * The chain version this delete moved the branch to. Absent when
+           * it moved nothing, or the content service does not version its
+           * chain. Compared with `headVersion` on `/stat`: an answer read
+           * before the delete would put the deleted head back.
+           */
+          headVersion: zod.z.number().optional()
+        })])
       })])
     },
     PUT: {
@@ -2257,7 +2338,14 @@ var Api = {
         json: zod.z.object({
           newPatchIds: zod.z.array(PatchId),
           parentRef: ParentRef,
-          patchGroupId: zod.z.string().optional()
+          patchGroupId: zod.z.string().optional(),
+          /**
+           * The chain version the last of these patches made, comparable with
+           * `headVersion` on `/stat`. A client keeps the highest version, so a
+           * stat read before this write does not put its parent back behind
+           * it. Absent in `fs` mode and from an older content service.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     },
@@ -2692,7 +2780,14 @@ var Api = {
             patchId: PatchId,
             moduleFilePath: ModuleFilePath,
             message: zod.z.string()
-          })).optional()
+          })).optional(),
+          /**
+           * The chain version this publish moved the branch to, where the
+           * content service versions its chain and the publish applied
+           * anything. See `headVersion` on `/stat`: a `/stat` answer read
+           * before the publish would put its patches back to pending.
+           */
+          headVersion: zod.z.number().optional()
         })
       }),
       /*
@@ -7365,6 +7460,54 @@ var projectSourceResponse = zod.z.object({
    */
   publicPaths: zod.z.array(zod.z.string()).nullable().optional()
 });
+/**
+ * Whether a managed project can be updated onto its template's current seed,
+ * and -- when it is asked with `POST`, the press -- what to build against.
+ *
+ * An update rebuilds the site as it is on newer dependencies. The loader
+ * decides whether there is one; content adds whether the project is managed at
+ * all, and the branch head the rebuild is wired at, because an update
+ * publishes no content of its own.
+ *
+ * `target` is a `/build-target` answer whose project half is the SEED's
+ * dependency layer, already copied into the project so a publish can name it.
+ * Only a `POST` carries it.
+ */
+var dependencyChange = zod.z.object({
+  name: zod.z.string(),
+  section: zod.z["enum"](["dependencies", "devDependencies"]),
+  /** `null` for a dependency the template added. */
+  from: zod.z.string().nullable(),
+  /** `null` for a dependency the template dropped: it leaves `package.json`. */
+  to: zod.z.string().nullable()
+});
+var updateTargetResponse = zod.z.discriminatedUnion("status", [zod.z.object({
+  status: zod.z.literal("current"),
+  template: zod.z.string(),
+  layerRev: zod.z.string()
+}), zod.z.object({
+  status: zod.z.literal("available"),
+  template: zod.z.string(),
+  /** Empty when only the dependency layer moved, and no version did. */
+  changes: zod.z.array(dependencyChange),
+  layerRev: zod.z.object({
+    from: zod.z.string().nullable(),
+    to: zod.z.string()
+  }),
+  /** The project's `package.json`, rewritten to the seed's versions. */
+  packageJson: zod.z.string(),
+  /** The branch head to build at; `null` for a project with no commits. */
+  commit: zod.z.string().nullable(),
+  branch: zod.z.string(),
+  target: buildTargetResponse.optional()
+}), zod.z.object({
+  status: zod.z.literal("unavailable"),
+  reason: zod.z.string(),
+  message: zod.z.string()
+})]);
+var parseUpdateTarget = function parseUpdateTarget(body) {
+  return parse(updateTargetResponse, body, "/v1/update-target");
+};
 var parseBuildTarget = function parseBuildTarget(body) {
   return parse(buildTargetResponse, body, "GET /v1/build-target");
 };
@@ -7534,6 +7677,7 @@ exports.parseProjectSource = parseProjectSource;
 exports.parsePromote = parsePromote;
 exports.parsePublishToken = parsePublishToken;
 exports.parseStatus = parseStatus;
+exports.parseUpdateTarget = parseUpdateTarget;
 exports.parseVerify = parseVerify;
 exports.partitionValidationErrors = partitionValidationErrors;
 exports.performSearch = performSearch;

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -1503,6 +1503,28 @@ var GenericError = zod.z.object({
   message: zod.z.string()
 });
 
+/**
+ * What answered when one URL was opened.
+ *
+ * The one place the Studio's `ExternalUrlProbeResult` and the server's
+ * `ProbeResult` meet, so the two cannot drift without this failing to parse.
+ */
+var ExternalUrlProbeResult = zod.z.union([zod.z.object({
+  kind: zod.z.literal("answered"),
+  code: zod.z.number(),
+  finalUrl: zod.z.string(),
+  ms: zod.z.number()
+}), zod.z.object({
+  kind: zod.z.literal("unreachable"),
+  message: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("timeout"),
+  ms: zod.z.number()
+}), zod.z.object({
+  kind: zod.z.literal("skipped"),
+  message: zod.z.string()
+})]);
+
 /**
  * Why a publish cannot happen, in a form the Studio can show.
  *
@@ -1991,6 +2013,13 @@ var Api = {
            * content service that predates it sends nothing.
            */
           headPatchId: PatchId.nullable().optional(),
+          /**
+           * The version of the chain `headPatchId` was read at, bumped by
+           * every write and delete. `/stat` has more than one caller, so
+           * answers can land out of order; a client keeps the head with the
+           * highest version. Optional, for the same reason `headPatchId` is.
+           */
+          headVersion: zod.z.number().optional(),
           commits: zod.z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2144,6 +2173,42 @@ var Api = {
       })])
     }
   },
+  /**
+   * Open a batch of external URLs and report what answered.
+   *
+   * A batch rather than one URL because the client checks a list, and a POST
+   * rather than a GET because the list is the input and does not belong in a
+   * URL or a cache.
+   *
+   * The server makes outbound requests to addresses this body supplies, which
+   * is SSRF by construction - see `linkCheck/addressGuard.ts` for the deny
+   * list that makes it safe, and `docs/plans/external-page-link-checks.md` for
+   * why it is a deny list on the RESOLVED address.
+   */
+  "/external-urls/check": {
+    POST: {
+      req: {
+        body: zod.z.object({
+          /*
+           * Capped, and the cap is the point rather than a formality: each URL
+           * is an outbound connection, and a body is not allowed to ask this
+           * server to open a thousand of them. The client sends ten at a time.
+           */
+          urls: zod.z.array(zod.z.string()).min(1).max(20)
+        }),
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          /** Keyed by the URL exactly as it was asked about. */
+          results: zod.z.record(zod.z.string(), ExternalUrlProbeResult)
+        })
+      })])
+    }
+  },
   "/direct-file-upload-settings": {
     POST: {
       req: {
@@ -2195,7 +2260,14 @@ var Api = {
            * groups, and a client that predates this is deleting correctly,
            * just not repairing.
            */
-          unstagePatchIds: zod.z.array(PatchId).optional()
+          unstagePatchIds: zod.z.array(PatchId).optional(),
+          /*
+           * Answer with `{ deleted, headVersion }` rather than the bare id
+           * array. Asked for rather than always sent, because the array is
+           * what a Studio bundle from before this parses — and a tab left
+           * open across a deploy still runs one.
+           */
+          reportHeadVersion: zod.z.literal(true).optional()
         }).optional(),
         cookies: {
           val_session: zod.z.string().optional()
@@ -2209,7 +2281,16 @@ var Api = {
         })
       }), zod.z.object({
         status: zod.z.literal(200),
-        json: zod.z.array(PatchId)
+        json: zod.z.union([zod.z.array(PatchId), zod.z.object({
+          deleted: zod.z.array(PatchId),
+          /**
+           * The chain version this delete moved the branch to. Absent when
+           * it moved nothing, or the content service does not version its
+           * chain. Compared with `headVersion` on `/stat`: an answer read
+           * before the delete would put the deleted head back.
+           */
+          headVersion: zod.z.number().optional()
+        })])
       })])
     },
     PUT: {
@@ -2257,7 +2338,14 @@ var Api = {
         json: zod.z.object({
           newPatchIds: zod.z.array(PatchId),
           parentRef: ParentRef,
-          patchGroupId: zod.z.string().optional()
+          patchGroupId: zod.z.string().optional(),
+          /**
+           * The chain version the last of these patches made, comparable with
+           * `headVersion` on `/stat`. A client keeps the highest version, so a
+           * stat read before this write does not put its parent back behind
+           * it. Absent in `fs` mode and from an older content service.
+           */
+          headVersion: zod.z.number().optional()
         })
       })])
     },
@@ -2692,7 +2780,14 @@ var Api = {
             patchId: PatchId,
             moduleFilePath: ModuleFilePath,
             message: zod.z.string()
-          })).optional()
+          })).optional(),
+          /**
+           * The chain version this publish moved the branch to, where the
+           * content service versions its chain and the publish applied
+           * anything. See `headVersion` on `/stat`: a `/stat` answer read
+           * before the publish would put its patches back to pending.
+           */
+          headVersion: zod.z.number().optional()
         })
       }),
       /*
@@ -7365,6 +7460,54 @@ var projectSourceResponse = zod.z.object({
    */
   publicPaths: zod.z.array(zod.z.string()).nullable().optional()
 });
+/**
+ * Whether a managed project can be updated onto its template's current seed,
+ * and -- when it is asked with `POST`, the press -- what to build against.
+ *
+ * An update rebuilds the site as it is on newer dependencies. The loader
+ * decides whether there is one; content adds whether the project is managed at
+ * all, and the branch head the rebuild is wired at, because an update
+ * publishes no content of its own.
+ *
+ * `target` is a `/build-target` answer whose project half is the SEED's
+ * dependency layer, already copied into the project so a publish can name it.
+ * Only a `POST` carries it.
+ */
+var dependencyChange = zod.z.object({
+  name: zod.z.string(),
+  section: zod.z["enum"](["dependencies", "devDependencies"]),
+  /** `null` for a dependency the template added. */
+  from: zod.z.string().nullable(),
+  /** `null` for a dependency the template dropped: it leaves `package.json`. */
+  to: zod.z.string().nullable()
+});
+var updateTargetResponse = zod.z.discriminatedUnion("status", [zod.z.object({
+  status: zod.z.literal("current"),
+  template: zod.z.string(),
+  layerRev: zod.z.string()
+}), zod.z.object({
+  status: zod.z.literal("available"),
+  template: zod.z.string(),
+  /** Empty when only the dependency layer moved, and no version did. */
+  changes: zod.z.array(dependencyChange),
+  layerRev: zod.z.object({
+    from: zod.z.string().nullable(),
+    to: zod.z.string()
+  }),
+  /** The project's `package.json`, rewritten to the seed's versions. */
+  packageJson: zod.z.string(),
+  /** The branch head to build at; `null` for a project with no commits. */
+  commit: zod.z.string().nullable(),
+  branch: zod.z.string(),
+  target: buildTargetResponse.optional()
+}), zod.z.object({
+  status: zod.z.literal("unavailable"),
+  reason: zod.z.string(),
+  message: zod.z.string()
+})]);
+var parseUpdateTarget = function parseUpdateTarget(body) {
+  return parse(updateTargetResponse, body, "/v1/update-target");
+};
 var parseBuildTarget = function parseBuildTarget(body) {
   return parse(buildTargetResponse, body, "GET /v1/build-target");
 };
@@ -7534,6 +7677,7 @@ exports.parseProjectSource = parseProjectSource;
 exports.parsePromote = parsePromote;
 exports.parsePublishToken = parsePublishToken;
 exports.parseStatus = parseStatus;
+exports.parseUpdateTarget = parseUpdateTarget;
 exports.parseVerify = parseVerify;
 exports.partitionValidationErrors = partitionValidationErrors;
 exports.performSearch = performSearch;

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1496,6 +1496,28 @@ var GenericError = z.object({
   message: z.string()
 });
 
+/**
+ * What answered when one URL was opened.
+ *
+ * The one place the Studio's `ExternalUrlProbeResult` and the server's
+ * `ProbeResult` meet, so the two cannot drift without this failing to parse.
+ */
+var ExternalUrlProbeResult = z.union([z.object({
+  kind: z.literal("answered"),
+  code: z.number(),
+  finalUrl: z.string(),
+  ms: z.number()
+}), z.object({
+  kind: z.literal("unreachable"),
+  message: z.string()
+}), z.object({
+  kind: z.literal("timeout"),
+  ms: z.number()
+}), z.object({
+  kind: z.literal("skipped"),
+  message: z.string()
+})]);
+
 /**
  * Why a publish cannot happen, in a form the Studio can show.
  *
@@ -1984,6 +2006,13 @@ var Api = {
            * content service that predates it sends nothing.
            */
           headPatchId: PatchId.nullable().optional(),
+          /**
+           * The version of the chain `headPatchId` was read at, bumped by
+           * every write and delete. `/stat` has more than one caller, so
+           * answers can land out of order; a client keeps the head with the
+           * highest version. Optional, for the same reason `headPatchId` is.
+           */
+          headVersion: z.number().optional(),
           commits: z.array(ValCommit),
           /**
            * The publishes the content service knows about.
@@ -2137,6 +2166,42 @@ var Api = {
       })])
     }
   },
+  /**
+   * Open a batch of external URLs and report what answered.
+   *
+   * A batch rather than one URL because the client checks a list, and a POST
+   * rather than a GET because the list is the input and does not belong in a
+   * URL or a cache.
+   *
+   * The server makes outbound requests to addresses this body supplies, which
+   * is SSRF by construction - see `linkCheck/addressGuard.ts` for the deny
+   * list that makes it safe, and `docs/plans/external-page-link-checks.md` for
+   * why it is a deny list on the RESOLVED address.
+   */
+  "/external-urls/check": {
+    POST: {
+      req: {
+        body: z.object({
+          /*
+           * Capped, and the cap is the point rather than a formality: each URL
+           * is an outbound connection, and a body is not allowed to ask this
+           * server to open a thousand of them. The client sends ten at a time.
+           */
+          urls: z.array(z.string()).min(1).max(20)
+        }),
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, z.object({
+        status: z.literal(200),
+        json: z.object({
+          /** Keyed by the URL exactly as it was asked about. */
+          results: z.record(z.string(), ExternalUrlProbeResult)
+        })
+      })])
+    }
+  },
   "/direct-file-upload-settings": {
     POST: {
       req: {
@@ -2188,7 +2253,14 @@ var Api = {
            * groups, and a client that predates this is deleting correctly,
            * just not repairing.
            */
-          unstagePatchIds: z.array(PatchId).optional()
+          unstagePatchIds: z.array(PatchId).optional(),
+          /*
+           * Answer with `{ deleted, headVersion }` rather than the bare id
+           * array. Asked for rather than always sent, because the array is
+           * what a Studio bundle from before this parses — and a tab left
+           * open across a deploy still runs one.
+           */
+          reportHeadVersion: z.literal(true).optional()
         }).optional(),
         cookies: {
           val_session: z.string().optional()
@@ -2202,7 +2274,16 @@ var Api = {
         })
       }), z.object({
         status: z.literal(200),
-        json: z.array(PatchId)
+        json: z.union([z.array(PatchId), z.object({
+          deleted: z.array(PatchId),
+          /**
+           * The chain version this delete moved the branch to. Absent when
+           * it moved nothing, or the content service does not version its
+           * chain. Compared with `headVersion` on `/stat`: an answer read
+           * before the delete would put the deleted head back.
+           */
+          headVersion: z.number().optional()
+        })])
       })])
     },
     PUT: {
@@ -2250,7 +2331,14 @@ var Api = {
         json: z.object({
           newPatchIds: z.array(PatchId),
           parentRef: ParentRef,
-          patchGroupId: z.string().optional()
+          patchGroupId: z.string().optional(),
+          /**
+           * The chain version the last of these patches made, comparable with
+           * `headVersion` on `/stat`. A client keeps the highest version, so a
+           * stat read before this write does not put its parent back behind
+           * it. Absent in `fs` mode and from an older content service.
+           */
+          headVersion: z.number().optional()
         })
       })])
     },
@@ -2685,7 +2773,14 @@ var Api = {
             patchId: PatchId,
             moduleFilePath: ModuleFilePath,
             message: z.string()
-          })).optional()
+          })).optional(),
+          /**
+           * The chain version this publish moved the branch to, where the
+           * content service versions its chain and the publish applied
+           * anything. See `headVersion` on `/stat`: a `/stat` answer read
+           * before the publish would put its patches back to pending.
+           */
+          headVersion: z.number().optional()
         })
       }),
       /*
@@ -7358,6 +7453,54 @@ var projectSourceResponse = z.object({
    */
   publicPaths: z.array(z.string()).nullable().optional()
 });
+/**
+ * Whether a managed project can be updated onto its template's current seed,
+ * and -- when it is asked with `POST`, the press -- what to build against.
+ *
+ * An update rebuilds the site as it is on newer dependencies. The loader
+ * decides whether there is one; content adds whether the project is managed at
+ * all, and the branch head the rebuild is wired at, because an update
+ * publishes no content of its own.
+ *
+ * `target` is a `/build-target` answer whose project half is the SEED's
+ * dependency layer, already copied into the project so a publish can name it.
+ * Only a `POST` carries it.
+ */
+var dependencyChange = z.object({
+  name: z.string(),
+  section: z["enum"](["dependencies", "devDependencies"]),
+  /** `null` for a dependency the template added. */
+  from: z.string().nullable(),
+  /** `null` for a dependency the template dropped: it leaves `package.json`. */
+  to: z.string().nullable()
+});
+var updateTargetResponse = z.discriminatedUnion("status", [z.object({
+  status: z.literal("current"),
+  template: z.string(),
+  layerRev: z.string()
+}), z.object({
+  status: z.literal("available"),
+  template: z.string(),
+  /** Empty when only the dependency layer moved, and no version did. */
+  changes: z.array(dependencyChange),
+  layerRev: z.object({
+    from: z.string().nullable(),
+    to: z.string()
+  }),
+  /** The project's `package.json`, rewritten to the seed's versions. */
+  packageJson: z.string(),
+  /** The branch head to build at; `null` for a project with no commits. */
+  commit: z.string().nullable(),
+  branch: z.string(),
+  target: buildTargetResponse.optional()
+}), z.object({
+  status: z.literal("unavailable"),
+  reason: z.string(),
+  message: z.string()
+})]);
+var parseUpdateTarget = function parseUpdateTarget(body) {
+  return parse(updateTargetResponse, body, "/v1/update-target");
+};
 var parseBuildTarget = function parseBuildTarget(body) {
   return parse(buildTargetResponse, body, "GET /v1/build-target");
 };
@@ -7386,4 +7529,4 @@ function parse(schema, body, call) {
   return parsed.data;
 }
 
-export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, ValCommit, ValDeployment, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseDeclare, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseStatus, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchGroup, PatchId, PatchJSON, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, ValCommit, ValDeployment, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, explainIncompatible, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, indexModule, isMimeTypeAccepted, isRemoteSchema, isSchemaSourceFixError, isSkippedSource, keyOfRecordPath, levenshtein, localeAt, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseDeclare, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseStatus, parseUpdateTarget, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextToRemirror, safeParsePatch, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.136.10",
+  "version": "0.137.0",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {
@@ -37,7 +37,7 @@
     "flexsearch": "^0.8.212",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.136.8"
+    "@valbuild/core": "0.137.0"
   },
   "files": [
     "CHANGELOG.md",