@valbuild/cli 0.132.1 → 0.134.0

package/cli/dist/valbuild-cli-cli.esm.js

@@ -11,6 +11,10 @@ import fs from 'fs';
 import ts from 'typescript';
 import JSZip from 'jszip';
 import readline from 'readline';
+import crypto from 'crypto';
+import zlib from 'zlib';
+import { z } from 'zod';
+import { fromError } from 'zod-validation-error';
 
 function error(message) {
   console.error(chalk.red("❌Error: ") + message);
@@ -1164,7 +1168,10 @@ async function createDebugContext(options) {
       authKind: "pat" in auth ? "pat" : "api-key",
       contentUrl,
       filesDirectory,
-      serverOps: new ValOpsHttp(contentUrl, project, commit, branch, auth, valModules, {
+      serverOps: new ValOpsHttp(contentUrl, project, {
+        commit,
+        branch
+      }, auth, valModules, {
         root: config.root,
         config
       })
@@ -2010,6 +2017,1374 @@ function confirm(question) {
   });
 }
 
+/**
+ * Where an artifact's bytes are, and what it is called on the wire.
+ *
+ * The key namespace is flat and is content's: `server`, `client`, `css`,
+ * `rsc`, `layer`, and paths under `chunk/server/`, `chunk/client/`,
+ * `chunk/rsc/`, `asset/` and `public/`. Content validates it and answers with
+ * every problem at once, so this does not re-implement the rules - a second,
+ * slightly different copy of them here is how a CLI comes to refuse a publish
+ * the service would have taken.
+ */
+
+/**
+ * The artifacts to publish, read from a directory laid out by key.
+ *
+ * The path under the directory IS the artifact key: a file at `public/app.css`
+ * is the artifact `public/app.css`, and `server` is the server bundle. Nothing
+ * is renamed on the way - an asset is addressed by the path the built code
+ * imports it at, so a normalised name produces a bundle whose imports resolve
+ * to nothing, at runtime, in the isolate.
+ *
+ * **This is the seam with the build.** `val publish` uploads artifacts; it does
+ * not produce them. Whatever builds the project - today the platform's own
+ * builder, which is where the wire, rolldown and dependency-layer steps live -
+ * writes this directory, and this reads it.
+ */
+async function collectArtifacts(dir) {
+  const artifacts = [];
+  const skipped = [];
+  let totalBytes = 0;
+  const walk = async current => {
+    const entries = await fs.promises.readdir(current, {
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      const absolute = path.join(current, entry.name);
+      const key = path.relative(dir, absolute).split(path.sep).join("/");
+      if (entry.isDirectory()) {
+        await walk(absolute);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        // A symlinked file is published as its bytes; a symlinked directory is
+        // not walked, because one usually comes with a cycle, and a publisher
+        // that hangs is worse than one that says what it left out.
+        const stat = await fs.promises.stat(absolute).catch(() => null);
+        if (stat === null) {
+          skipped.push(`${key} (broken symlink)`);
+          continue;
+        }
+        if (!stat.isFile()) {
+          skipped.push(`${key} (symlink to a ${stat.isDirectory() ? "directory" : "special file"})`);
+          continue;
+        }
+      } else if (!entry.isFile()) {
+        skipped.push(`${key} (not a regular file)`);
+        continue;
+      }
+      const {
+        sha256,
+        bytes
+      } = await hashFile(absolute);
+      artifacts.push({
+        key,
+        sha256,
+        bytes,
+        file: absolute
+      });
+      totalBytes += bytes;
+    }
+  };
+  await walk(dir);
+  // Sorted so two publishes of one build declare the same list in the same
+  // order, which is what makes the build hash below reproducible.
+  artifacts.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+  return {
+    artifacts,
+    totalBytes,
+    skipped
+  };
+}
+async function hashFile(absolute) {
+  const hash = crypto.createHash("sha256");
+  let bytes = 0;
+  // Streamed: an artifact may be 128 MB, and reading one into a Buffer to hash
+  // it is a needless way to run a CI runner out of memory.
+  const stream = fs.createReadStream(absolute);
+  await new Promise((resolve, reject) => {
+    stream.on("data", chunk => {
+      hash.update(chunk);
+      bytes += chunk.length;
+    });
+    stream.on("end", resolve);
+    stream.on("error", reject);
+  });
+  return {
+    sha256: hash.digest("hex"),
+    bytes
+  };
+}
+
+/**
+ * The build's own hash, when the build did not say.
+ *
+ * Content uses it for idempotency - declaring the same `buildHash` twice
+ * returns the same publish, which is what makes a retried CI job resume rather
+ * than start again - so it has to be a function of the build and nothing else.
+ * Every artifact's key and hash, in order: two runs of one build agree, and
+ * any change to any artifact is a different publish.
+ */
+function buildHashOf(artifacts) {
+  const hash = crypto.createHash("sha256");
+  for (const artifact of artifacts) {
+    hash.update(`${artifact.key} ${artifact.sha256}\n`);
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * Which dependency layer this build was built against.
+ *
+ * A layer is sent or named, never neither: the loader reads the head's layer
+ * by rev, and a publish that declares no layer at all loses every dependency
+ * on the next render. When the layer is being uploaded, its rev is inside it -
+ * it is gzipped JSON with a `rev` - so there is nothing to ask the caller for.
+ * When it is not, the build knows which stored layer it used, and says so with
+ * `--layer-rev`.
+ */
+async function layerRevOf(artifacts) {
+  const layer = artifacts.find(artifact => artifact.key === "layer");
+  if (!layer) {
+    return {
+      status: "ok",
+      layerRev: null
+    };
+  }
+  const bytes = await fs.promises.readFile(layer.file);
+  let parsed;
+  try {
+    parsed = JSON.parse(zlib.gunzipSync(bytes).toString("utf-8"));
+  } catch (err) {
+    return {
+      status: "error",
+      message: `The layer artifact is not gzipped JSON: ${err instanceof Error ? err.message : String(err)}\n\n` + "A layer is `{ rev, worker, browser, ... }`, gzipped. Pass --layer-rev to\n" + "name a layer content already holds instead of sending one."
+    };
+  }
+  const rev = typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "rev") : undefined;
+  if (typeof rev !== "string" || rev === "") {
+    return {
+      status: "error",
+      message: "The layer artifact has no rev, and a layer that is sent has to say which\n" + "it is: that is the name the loader stores and later reuses it by."
+    };
+  }
+  return {
+    status: "ok",
+    layerRev: rev
+  };
+}
+
+/** Where the artifacts are, if the caller did not say. */
+const DEFAULT_ARTIFACTS_DIR = ".val/publish";
+function resolveArtifactsDir(options) {
+  const named = options.dir ?? DEFAULT_ARTIFACTS_DIR;
+  const dir = path.resolve(options.root, named);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return {
+      status: "error",
+      message: `No artifacts to publish: ${dir} is not a directory.\n\n` + "Build the project first, then point at what it produced:\n\n" + "    npx val publish --artifacts <directory>\n\n" + "The path of each file under it is its artifact key - `server`, `client`,\n" + "`public/...`, `chunk/client/...`, `layer`."
+    };
+  }
+  return {
+    status: "ok",
+    dir
+  };
+}
+
+/**
+ * The one host `val publish` talks to.
+ *
+ * Not a flag, and not several: publishing is a conversation with
+ * content.val.build, which holds the operator relationship with whatever
+ * actually serves the site and calls it on our behalf. A second host here
+ * would be a second thing to configure in every repository that publishes,
+ * and a second place for a credential to go.
+ *
+ * `VAL_CONTENT_URL` overrides it, as it does everywhere else in Val, so a
+ * test can point the CLI at a fake and a developer at a local content service.
+ */
+function getContentHost(env = process.env) {
+  const configured = env.VAL_CONTENT_URL;
+  if (!configured) {
+    return DEFAULT_CONTENT_HOST;
+  }
+  // A trailing slash turns every path below into a double slash, which some
+  // routers answer with a redirect and others with a 404.
+  return configured.replace(/\/+$/, "");
+}
+
+/**
+ * A refusal from content, carrying the status so a caller can tell "your
+ * credential is no good" (401/403) from "content is down" (5xx) and say
+ * something different about each.
+ */
+class ContentHostError extends Error {
+  statusCode;
+  /**
+   * Whatever was in `details`, unread.
+   *
+   * The publish routes put a `PublishProblem[]` there - every problem with a
+   * declaration rather than the first - and the older routes put a sentence.
+   * Keeping it unparsed here lets each caller read the one it expects without
+   * this file having to know about either.
+   */
+  details;
+  /**
+   * The whole answer.
+   *
+   * Some refusals carry a field of their own beside the message - a stale
+   * pointer answers with the `head` the branch is at now, which is the one
+   * thing that tells a publisher what happened - so the body is kept rather
+   * than reduced to two strings on the way past.
+   */
+  body;
+  constructor(statusCode, message, details, body) {
+    super(message);
+    this.name = "ContentHostError";
+    this.statusCode = statusCode;
+    this.details = details;
+    this.body = body;
+  }
+}
+
+/** The `details` of a refusal, when it is a sentence rather than a list. */
+function detailText(details) {
+  return typeof details === "string" && details !== "" ? details : null;
+}
+
+/** GET JSON from content. Same envelope, same failures, one less body. */
+async function getJson(options) {
+  return requestJson({
+    method: "GET",
+    ...options
+  });
+}
+
+/**
+ * POST JSON to content and read JSON back.
+ *
+ * Content answers an error as `{ statusCode, message, details? }` (its
+ * `sendResult`), so the message a user sees is the one the service wrote
+ * rather than a status code they then have to look up. A body that is not
+ * that shape - a proxy's HTML error page, say - still has to produce a
+ * sentence, hence the fallback.
+ */
+async function postJson(options) {
+  return requestJson({
+    method: "POST",
+    ...options
+  });
+}
+async function requestJson(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await fetchImpl(options.url, {
+      method: options.method,
+      headers: options.method === "GET" ? options.headers : {
+        "Content-Type": "application/json",
+        ...options.headers
+      },
+      ...(options.method === "GET" ? {} : {
+        body: JSON.stringify(options.body ?? {})
+      })
+    });
+  } catch (err) {
+    // No status at all: DNS, TLS, a dropped connection. 0 is the shape the
+    // rest of this file expects, and it is never a status a server sends.
+    throw new ContentHostError(0, `Could not reach ${options.url}`, err instanceof Error ? err.message : String(err));
+  }
+  const text = await res.text();
+  let parsed = undefined;
+  if (text !== "") {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = undefined;
+    }
+  }
+  if (!res.ok) {
+    throw new ContentHostError(res.status, errorMessageOf(parsed) ?? `${res.status} ${res.statusText}`, errorDetailsOf(parsed), parsed);
+  }
+  return parsed;
+}
+function errorMessageOf(body) {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const message = body.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+  }
+  return undefined;
+}
+function errorDetailsOf(body) {
+  if (typeof body === "object" && body !== null && "details" in body) {
+    return body.details;
+  }
+  return undefined;
+}
+
+/**
+ * Reading what content answers.
+ *
+ * Every type here comes from `contentApi.ts`, which is a copy of the
+ * service's own `Api.ts` - so the shapes are not re-derived from what this end
+ * wishes it received, and a copy brought up to date fails to compile wherever
+ * this CLI has not caught up.
+ *
+ * The schemas are the runtime half, and they are needed as well as the types:
+ * what arrives is JSON over HTTP from a service that versions separately, so a
+ * type alone asserts a shape rather than checking one. Each schema is
+ * annotated with the copied type it must produce (`z.ZodType<DeclareResponse>`
+ * and so on), which is what ties the two halves together - a schema that drifts
+ * from the copy does not compile, and an answer that drifts from the schema
+ * does not parse. `ValOpsHttp` in `@valbuild/server` reads every other content
+ * route the same way.
+ *
+ * Nothing here is laxer than the copy. An optional field is optional because
+ * the service says so; making a required one optional here would hide exactly
+ * the drift this file exists to catch.
+ */
+
+/** An artifact, as it is declared: by key, by hash, by size. */
+
+/** Permission to write one artifact's bytes to object storage. */
+
+const publishState = z.enum(["awaiting-artifacts", "ready", "verified", "live", "failed", "expired"]);
+const publishProblem = z.object({
+  code: z.string(),
+  message: z.string(),
+  hint: z.string().optional(),
+  keys: z.array(z.string()).optional()
+});
+const uploadSlot = z.object({
+  key: z.string(),
+  url: z.string(),
+  method: z.literal("PUT"),
+  headers: z.record(z.string(), z.string()),
+  expiresAt: z.string()
+});
+const declareResponse = z.object({
+  publishId: z.string(),
+  state: publishState,
+  project: z.object({
+    publicProjectId: z.string(),
+    siteUrl: z.string().nullable()
+  }),
+  uploads: z.array(uploadSlot),
+  have: z.array(z.string())
+});
+const artifactsResponse = z.object({
+  state: publishState,
+  problems: z.array(publishProblem)
+});
+const verifyResponse = z.object({
+  state: publishState,
+  ok: z.boolean(),
+  previewUrl: z.string().nullable(),
+  problems: z.array(publishProblem)
+});
+const promoteResponse = z.object({
+  state: publishState,
+  url: z.string().nullable(),
+  commit: z.string().nullable()
+});
+const statusResponse = z.object({
+  publishId: z.string(),
+  state: publishState,
+  buildHash: z.string(),
+  missing: z.array(z.string()),
+  problems: z.array(publishProblem)
+});
+const publishTokenResponse = z.object({
+  token: z.string(),
+  expiresAt: z.string().nullable(),
+  publicProjectId: z.string(),
+  productionUrl: z.string().nullable()
+});
+
+/**
+ * Content answered, and the answer was not one this CLI can act on.
+ *
+ * Separate from a refusal, which is content saying no in a sentence meant for
+ * a person. This is two programs disagreeing - the copy in `contentApi.ts` and
+ * the service that has moved on from it - and the two want opposite things
+ * said about them.
+ */
+class PublishProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PublishProtocolError";
+  }
+}
+const parseDeclare = body => parse(declareResponse, body, "POST /v1/publish");
+const parseArtifacts = body => parse(artifactsResponse, body, "POST /v1/publish/{id}/artifacts");
+const parseVerify = body => parse(verifyResponse, body, "POST /v1/publish/{id}/verify");
+const parsePromote = body => parse(promoteResponse, body, "POST /v1/publish/{id}/promote");
+const parseStatus = body => parse(statusResponse, body, "GET /v1/publish/{id}");
+const parsePublishToken = (body, call) => parse(publishTokenResponse, body, call);
+
+/**
+ * The `details` of a refusal, when it carries a list of problems.
+ *
+ * Every non-2xx is `{ statusCode, message, details? }`, and the publish routes
+ * put `PublishProblem[]` in `details` - a declaration is answered with EVERY
+ * problem rather than the first, because finding them one round trip at a time
+ * is how a publish takes six attempts. Anything else in there is somebody
+ * else's `details` and is left to the caller's own message.
+ */
+function parseProblems(details) {
+  const parsed = z.array(publishProblem).safeParse(details);
+  return parsed.success ? parsed.data : [];
+}
+function parse(schema, body, call) {
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    throw new PublishProtocolError(`${call} answered with something this CLI cannot read: ${fromError(parsed.error).toString()}`);
+  }
+  return parsed.data;
+}
+
+function createPublishClient(options) {
+  const {
+    host,
+    token
+  } = options;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  // Every call, and nothing else: not a cookie, not the project's api key, not
+  // a personal access token.
+  const headers = {
+    Authorization: `Bearer ${token}`
+  };
+  const publishUrl = (publishId, step) => `${host}/v1/publish/${encodeURIComponent(publishId)}${step ? `/${step}` : ""}`;
+  return {
+    declare: async body => parseDeclare(await postJson({
+      url: `${host}/v1/publish`,
+      headers,
+      body,
+      fetchImpl
+    })),
+    confirmArtifacts: async publishId => parseArtifacts(await postJson({
+      url: publishUrl(publishId, "artifacts"),
+      headers,
+      fetchImpl
+    })),
+    verify: async publishId => parseVerify(await postJson({
+      url: publishUrl(publishId, "verify"),
+      headers,
+      fetchImpl
+    })),
+    promote: async publishId => parsePromote(await postJson({
+      url: publishUrl(publishId, "promote"),
+      headers,
+      fetchImpl
+    })),
+    status: async publishId => parseStatus(await getJson({
+      url: publishUrl(publishId),
+      headers,
+      fetchImpl
+    })),
+    upload: (slot, file) => putArtifact(slot, file, fetchImpl)
+  };
+}
+
+/** Object storage refused the bytes, or could not be reached. */
+class UploadError extends Error {
+  statusCode;
+  key;
+  constructor(statusCode, key, message) {
+    super(message);
+    this.name = "UploadError";
+    this.statusCode = statusCode;
+    this.key = key;
+  }
+}
+
+/**
+ * A slot's permission to write has run out.
+ *
+ * Not a failed publish: declaring again mints fresh slots and the publish
+ * carries on from where it was, which is why this is its own kind of failure
+ * rather than an error message.
+ */
+function isExpiredSlot(err) {
+  return err.statusCode === 403 || err.statusCode === 401;
+}
+async function putArtifact(slot, file, fetchImpl) {
+  /*
+   * Read, rather than streamed.
+   *
+   * `ContentLength` is signed into the slot's URL, so the store rejects a body
+   * of a different size - and a streamed body goes out chunked, which is a
+   * different size as far as the signature is concerned. An artifact is capped
+   * at 128 MB by the API, which is the bound this trades against.
+   */
+  const body = await fs.promises.readFile(file);
+  let res;
+  try {
+    res = await fetchImpl(slot.url, {
+      method: slot.method,
+      headers: slot.headers,
+      body
+    });
+  } catch (err) {
+    throw new UploadError(0, slot.key, `${slot.key}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!res.ok) {
+    // The store answers XML, and a whole error document in a CI log buries the
+    // line that matters. The status is the actionable half.
+    throw new UploadError(res.status, slot.key, `${slot.key}: object storage answered ${res.status} ${res.statusText}`);
+  }
+}
+
+/**
+ * Run `worker` over `items`, `limit` at a time.
+ *
+ * A project can have hundreds of small artifacts, so one at a time is minutes
+ * of latency and all at once is hundreds of open sockets on a CI runner. The
+ * first failure stops the pool: there is no point uploading the rest of a
+ * publish that is not going to be promoted.
+ */
+async function pool(items, limit, worker) {
+  let next = 0;
+  let failure = undefined;
+  const run = async () => {
+    for (;;) {
+      if (failure !== undefined) {
+        return;
+      }
+      const index = next++;
+      if (index >= items.length) {
+        return;
+      }
+      try {
+        await worker(items[index]);
+      } catch (err) {
+        failure = err;
+        return;
+      }
+    }
+  };
+  await Promise.all(Array.from({
+    length: Math.min(limit, items.length)
+  }, () => run()));
+  if (failure !== undefined) {
+    throw failure;
+  }
+}
+
+/**
+ * The credential `val publish` presents to content, and where it came from.
+ *
+ * Whatever the publisher started with, this is a *project* token: it can do one
+ * thing to one project. A personal access token is a person's credential -
+ * org-wide, read and write on every project they can reach - so it never
+ * travels further than val.build, which exchanges it for one of these.
+ */
+
+const NO_CREDENTIAL = "Publishing needs a credential.\n\n" + "  In CI:           set VAL_PROJECT_TOKEN as a repository secret.\n" + "  On your machine: run\n\n" + "      npx val login\n\n" + "Neither is a command line flag, deliberately: an argument is visible to\n" + "anyone who can list processes, and it is kept in shell history and in the\n" + "log of every CI job that echoes its command line.";
+
+/**
+ * The credential, in the order the publisher should prefer them.
+ *
+ * 1. `VAL_PROJECT_TOKEN` from the environment - used as it is, no exchange.
+ *    This is what a repository created by `/new` holds, and the only secret it
+ *    needs: the token names its project, so content can answer *where* to
+ *    publish as well as *whether*.
+ * 2. The `val login` token in `<root>/.val/pat.json` - exchanged first, because
+ *    what publishes must be a project token. The exchange is addressed by org
+ *    and project, since a personal access token does not name one; that is why
+ *    this way needs `project` and the first does not.
+ * 3. Neither, which is not an error we can guess our way out of.
+ *
+ * Returns a result rather than throwing: "no credential" is one of the things a
+ * publisher has to say well, and the sentence differs by which half was missing.
+ */
+async function resolvePublishCredential(options) {
+  var _env$VAL_PROJECT_TOKE;
+  const env = options.env ?? process.env;
+  // An unset secret reaches a CI job as the empty string rather than as absent,
+  // and an empty credential presented to content is a 401 that reads as "your
+  // token is bad" instead of "you never set one".
+  const projectToken = (_env$VAL_PROJECT_TOKE = env.VAL_PROJECT_TOKEN) === null || _env$VAL_PROJECT_TOKE === void 0 ? void 0 : _env$VAL_PROJECT_TOKE.trim();
+  if (projectToken) {
+    if (looksLikePersonalAccessToken(projectToken)) {
+      return {
+        status: "error",
+        message: "VAL_PROJECT_TOKEN looks like a personal access token, not a project\n" + "token. A project token begins with `val_pt_` and is made for one\n" + "project; a personal access token belongs to a person and cannot\n" + "publish. Mint a project token on the project's settings page."
+      };
+    }
+    return {
+      status: "ok",
+      credential: {
+        token: projectToken,
+        origin: "VAL_PROJECT_TOKEN",
+        // A standing token need not expire, and nothing here has been told
+        // otherwise. Content is where an expiry would come from.
+        expiresAt: null
+      }
+    };
+  }
+  const pat = readPersonalAccessToken(options.root);
+  if (pat.status === "error") {
+    return pat;
+  }
+  if (pat.status === "none") {
+    var _ref;
+    /*
+     * The old names, still read.
+     *
+     * This is where the api key used to be passed, and this platform's own CI
+     * still passes it: a rename that breaks the publisher is a rename that gets
+     * reverted. It will not be accepted for long - publishing is being taken
+     * out of what an api key may do - and content says so in its own words
+     * when it refuses one, which is a better sentence than a guess here.
+     */
+    const legacy = (_ref = env.VAL_APP_TOKEN ?? env.PLATFORM_TOKEN) === null || _ref === void 0 ? void 0 : _ref.trim();
+    if (legacy) {
+      return {
+        status: "ok",
+        credential: {
+          token: legacy,
+          origin: "VAL_APP_TOKEN",
+          expiresAt: null
+        }
+      };
+    }
+    return {
+      status: "error",
+      message: NO_CREDENTIAL
+    };
+  }
+  if (!options.project) {
+    return {
+      status: "error",
+      message: "You are logged in, but nothing says which project to publish.\n\n" + 'Set `project` ("<org>/<project>") in val.config, or the VAL_PROJECT\n' + "environment variable.\n\n" + "A `val login` token belongs to you rather than to a project, so it\n" + "cannot say which one you are standing in."
+    };
+  }
+  const parts = options.project.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    return {
+      status: "error",
+      message: `Invalid project: "${options.project}". Expected "<org>/<project>".`
+    };
+  }
+  const [orgName, projectName] = parts;
+  return exchangePersonalAccessToken({
+    pat: pat.pat,
+    orgName,
+    projectName,
+    env,
+    ...(options.fetchImpl ? {
+      fetchImpl: options.fetchImpl
+    } : {})
+  });
+}
+
+/**
+ * Trade the token you have for the token that may publish.
+ *
+ * Ten minutes, one project, one scope. The person's identity survives the
+ * exchange even though the credential will not outlive the command, which is
+ * what gives "who published this" an answer afterwards.
+ */
+async function exchangePersonalAccessToken(options) {
+  const host = getContentHost(options.env);
+  const url = `${host}/v1/${encodeURIComponent(options.orgName)}/${encodeURIComponent(options.projectName)}/publish-token`;
+  let body;
+  try {
+    body = await postJson({
+      url,
+      headers: {
+        "x-val-pat": options.pat
+      },
+      ...(options.fetchImpl ? {
+        fetchImpl: options.fetchImpl
+      } : {})
+    });
+  } catch (err) {
+    if (err instanceof ContentHostError) {
+      return {
+        status: "error",
+        message: exchangeFailureMessage(err, options)
+      };
+    }
+    throw err;
+  }
+  let exchanged;
+  try {
+    exchanged = parsePublishToken(body, `POST ${url}`);
+  } catch (err) {
+    if (err instanceof PublishProtocolError) {
+      return {
+        status: "error",
+        message: err.message
+      };
+    }
+    throw err;
+  }
+  return {
+    status: "ok",
+    credential: {
+      token: exchanged.token,
+      origin: "val login",
+      expiresAt: exchanged.expiresAt
+    }
+  };
+}
+function exchangeFailureMessage(err, options) {
+  const project = `${options.orgName}/${options.projectName}`;
+  if (err.statusCode === 401) {
+    return "Your Val login is no longer valid - it may have expired. Log in again:\n\n" + "    npx val login";
+  }
+  if (err.statusCode === 403) {
+    return `Your Val account may not publish ${project}: ${err.message}`;
+  }
+  if (err.statusCode === 404) {
+    return `No project ${project}. Check \`project\` in val.config (or VAL_PROJECT):\n` + "it is the org and project as val.build names them, not the repository.";
+  }
+  return `Could not get a publish token for ${project}: ${err.message}` + (err.details ? `\n${err.details}` : "");
+}
+
+/** A personal access token is 32 random bytes as hex, and carries no prefix. */
+function looksLikePersonalAccessToken(token) {
+  return /^[0-9a-f]{64}$/i.test(token);
+}
+function readPersonalAccessToken(root) {
+  const patFile = getPersonalAccessTokenPath(root);
+  if (!fs.existsSync(patFile)) {
+    return {
+      status: "none"
+    };
+  }
+  const parsed = parsePersonalAccessTokenFile(fs.readFileSync(patFile, "utf-8"));
+  if (!parsed.success) {
+    return {
+      status: "error",
+      message: `Could not read the Val login at ${patFile}: ${parsed.error}.\n` + "Log in again:\n\n    npx val login"
+    };
+  }
+  return {
+    status: "ok",
+    pat: parsed.data.pat
+  };
+}
+
+/** How many artifacts go up at once, and how often a lost one is retried. */
+const UPLOAD_CONCURRENCY = 6;
+const UPLOAD_ATTEMPTS = 3;
+/**
+ * How many times the publish is declared before giving up.
+ *
+ * A round ends by declaring again, and there are two reasons to: a slot's hour
+ * ran out mid-upload, or content re-hashed what landed and something did not
+ * arrive as declared. Both are fixed by fresh slots and sending again. A third
+ * round that still does not confirm is not a slow network.
+ */
+const DECLARE_ROUNDS = 3;
+/**
+ * Publish a build through content.val.build.
+ *
+ * Declare what the build is made of, upload the artifacts content does not
+ * already hold, confirm, let content build and render a canary, and only then
+ * ask it to promote. Every decision in that sequence is content's; this
+ * carries bytes and reports back.
+ *
+ * Content is also the only host it talks to. Content holds the operator
+ * relationship with the build platform and calls it during verify and promote,
+ * which is what lets a repository publish with a token that can do nothing
+ * else - there is no loader address here, no project id, and no credential
+ * that could reach either.
+ */
+async function runPublish(options) {
+  const env = options.env ?? process.env;
+  const log = options.log ?? (line => console.log(line));
+  const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  const root = options.root ? path.resolve(options.root) : process.cwd();
+  const dir = resolveArtifactsDir({
+    root,
+    ...(options.artifacts ? {
+      dir: options.artifacts
+    } : {})
+  });
+  if (dir.status === "error") {
+    return {
+      status: "error",
+      message: dir.message
+    };
+  }
+  const collected = await collectArtifacts(dir.dir);
+  for (const skipped of collected.skipped) {
+    log(`Skipped ${skipped}`);
+  }
+  if (collected.artifacts.length === 0) {
+    return {
+      status: "error",
+      message: `There is nothing in ${dir.dir}. Build the project before publishing it.`
+    };
+  }
+  const layer = await layerRevOf(collected.artifacts);
+  if (layer.status === "error") {
+    return {
+      status: "error",
+      message: layer.message
+    };
+  }
+  const layerRev = options.layerRev ?? layer.layerRev;
+  const git = await resolveGit({
+    root,
+    options,
+    env
+  });
+  if (git.status === "error") {
+    return git;
+  }
+  const config = await findAndEvalValConfigFile(root).catch(() => null);
+  const credential = await resolvePublishCredential({
+    root,
+    project: (config === null || config === void 0 ? void 0 : config.project) ?? env.VAL_PROJECT ?? null,
+    env,
+    ...(options.fetchImpl ? {
+      fetchImpl: options.fetchImpl
+    } : {})
+  });
+  if (credential.status === "error") {
+    return {
+      status: "error",
+      message: credential.message
+    };
+  }
+  const client = createPublishClient({
+    host: getContentHost(env),
+    token: credential.credential.token,
+    ...(options.fetchImpl ? {
+      fetchImpl: options.fetchImpl
+    } : {})
+  });
+  const buildHash = options.buildHash ?? buildHashOf(collected.artifacts);
+  log(`${count(collected.artifacts.length, "artifact")}, ${formatBytes(collected.totalBytes)}` + `, at ${git.commit.slice(0, 7)} on ${git.branch}`);
+  try {
+    return await publishDeclaredBuild({
+      client,
+      log,
+      sleep,
+      artifacts: collected.artifacts,
+      totalBytes: collected.totalBytes,
+      body: {
+        buildHash,
+        commit: git.commit,
+        branch: git.branch,
+        layerRev,
+        linksOwnCss: options.linksOwnCss ?? null,
+        artifacts: collected.artifacts.map(({
+          key,
+          sha256,
+          bytes
+        }) => ({
+          key,
+          sha256,
+          bytes
+        }))
+      },
+      dryRun: options.dryRun === true
+    });
+  } catch (err) {
+    return errorFrom(err);
+  }
+}
+async function publishDeclaredBuild(args) {
+  const {
+    client,
+    log,
+    sleep,
+    artifacts,
+    body,
+    dryRun
+  } = args;
+  const fileOf = new Map(artifacts.map(artifact => [artifact.key, artifact.file]));
+  const bytesOf = new Map(artifacts.map(artifact => [artifact.key, artifact.bytes]));
+  const uploadedKeys = new Set();
+  let uploadedBytes = 0;
+  let publishId = null;
+  let confirmed = false;
+  for (let round = 1; round <= DECLARE_ROUNDS && !confirmed; round++) {
+    const declared = await declare(client, body);
+    if (declared.status === "refused") {
+      return {
+        status: "failed",
+        publishId,
+        state: null,
+        message: declared.message,
+        problems: declared.problems,
+        previewUrl: null
+      };
+    }
+    publishId = declared.response.publishId;
+    if (declared.response.state === "live") {
+      /*
+       * Already published, and not re-opened - re-declaring would mint slots
+       * to overwrite the bytes of a build that is currently serving. A CI job
+       * re-run after a successful publish lands here, and it is a success.
+       */
+      log("This build is already live.");
+      return {
+        status: "live",
+        publishId: declared.response.publishId,
+        url: declared.response.project.siteUrl,
+        commit: body.commit,
+        artifacts: artifacts.length,
+        uploaded: uploadedKeys.size,
+        uploadedBytes,
+        previewUrl: null
+      };
+    }
+    const slots = declared.response.uploads;
+    if (slots.length > 0) {
+      const bytes = slots.reduce((sum, slot) => sum + (bytesOf.get(slot.key) ?? 0), 0);
+      log(round === 1 ? `Uploading ${count(slots.length, "artifact")}, ${formatBytes(bytes)}` + ` (${declared.response.have.length} already held)` : `Uploading ${count(slots.length, "artifact")} again`);
+      const outcome = await uploadAll({
+        client,
+        slots,
+        fileOf,
+        sleep
+      });
+      for (const key of outcome.uploaded) {
+        if (!uploadedKeys.has(key)) {
+          uploadedKeys.add(key);
+          uploadedBytes += bytesOf.get(key) ?? 0;
+        }
+      }
+      if (outcome.status === "expired") {
+        // The hour on the slots ran out while we were using them. Declaring
+        // again mints fresh ones; nothing about the publish has failed.
+        log("Upload slots expired. Declaring again for fresh ones.");
+        continue;
+      }
+    }
+    const confirmation = await confirmArtifacts(client, declared.response.publishId);
+    if (confirmation.status === "mismatch") {
+      log(`Content did not receive ${count(confirmation.problems.length, "artifact")} as declared. Declaring again.`);
+      if (round === DECLARE_ROUNDS) {
+        return {
+          status: "failed",
+          publishId,
+          state: null,
+          message: "Some artifacts did not arrive as declared.",
+          problems: confirmation.problems,
+          previewUrl: null
+        };
+      }
+      continue;
+    }
+    if (confirmation.state !== "ready") {
+      return {
+        status: "failed",
+        publishId,
+        state: confirmation.state,
+        message: `Content left this publish in "${confirmation.state}" after confirming the artifacts.`,
+        problems: confirmation.problems,
+        previewUrl: null
+      };
+    }
+    confirmed = true;
+  }
+  if (!confirmed || publishId === null) {
+    return {
+      status: "failed",
+      publishId,
+      state: null,
+      message: `The artifacts were not confirmed after ${DECLARE_ROUNDS} attempts.`,
+      problems: [],
+      previewUrl: null
+    };
+  }
+  log("Verifying: content is building and rendering this as a canary");
+  let verified;
+  try {
+    verified = await client.verify(publishId);
+  } catch (err) {
+    verified = await recoverWithStatus(err, client, publishId);
+  }
+  const summary = {
+    publishId,
+    artifacts: artifacts.length,
+    uploaded: uploadedKeys.size,
+    uploadedBytes,
+    previewUrl: "previewUrl" in verified ? verified.previewUrl : null
+  };
+  const verifiedOk = "ok" in verified ? verified.ok : verified.state === "verified";
+  if (!verifiedOk) {
+    return {
+      status: "failed",
+      publishId,
+      state: verified.state,
+      message: "The canary did not build and render, so nothing was promoted.",
+      problems: verified.problems,
+      previewUrl: summary.previewUrl
+    };
+  }
+  if (dryRun) {
+    log("Verified. Stopping here: --dry-run does not move the pointer.");
+    return {
+      status: "verified",
+      ...summary
+    };
+  }
+  const promoted = await promote(client, publishId);
+  if (promoted.status === "stale") {
+    return {
+      status: "failed",
+      publishId,
+      state: null,
+      message: promoted.message,
+      problems: promoted.problems,
+      previewUrl: summary.previewUrl
+    };
+  }
+  if (promoted.response.state !== "live") {
+    return {
+      status: "failed",
+      publishId,
+      state: promoted.response.state,
+      message: `The pointer was not moved: this publish is "${promoted.response.state}".`,
+      problems: [],
+      previewUrl: summary.previewUrl
+    };
+  }
+  return {
+    status: "live",
+    url: promoted.response.url,
+    commit: promoted.response.commit,
+    ...summary
+  };
+}
+async function declare(client, body) {
+  try {
+    return {
+      status: "ok",
+      response: await client.declare(body)
+    };
+  } catch (err) {
+    // A malformed declaration is answered with EVERY problem rather than the
+    // first, so all of them are carried through to the report.
+    if (err instanceof ContentHostError && err.statusCode === 400) {
+      return {
+        status: "refused",
+        message: err.message,
+        problems: parseProblems(err.details)
+      };
+    }
+    throw err;
+  }
+}
+async function confirmArtifacts(client, publishId) {
+  try {
+    const response = await client.confirmArtifacts(publishId);
+    return {
+      status: "ok",
+      state: response.state,
+      problems: response.problems
+    };
+  } catch (err) {
+    if (err instanceof ContentHostError && err.statusCode === 409) {
+      // Either nothing is at that key or the bytes are not what was declared.
+      // Both are fixed by fresh slots and sending again.
+      return {
+        status: "mismatch",
+        problems: parseProblems(err.details)
+      };
+    }
+    throw err;
+  }
+}
+async function promote(client, publishId) {
+  try {
+    return {
+      status: "ok",
+      response: await client.promote(publishId)
+    };
+  } catch (err) {
+    if (err instanceof ContentHostError && err.statusCode === 0) {
+      // The pointer may well have moved; the answer saying so was lost. Ask.
+      const status = await client.status(publishId);
+      return {
+        status: "ok",
+        response: {
+          state: status.state,
+          url: null,
+          commit: null
+        }
+      };
+    }
+    if (err instanceof ContentHostError && err.statusCode === 409) {
+      /*
+       * Somebody pushed while this was building.
+       *
+       * Content's own sentence already says what to do ("Rebuild from the
+       * current head"), so it is passed through rather than replaced, and the
+       * `POINTER_STALE` code and the loader's words come out of `details` the
+       * way every other refusal's problems do.
+       *
+       * `head` is read if it is there and not required: the API's written
+       * contract says a stale promote carries the sha the branch is at now,
+       * and `postPublishPromote.ts` does not send it today. Naming the sha is
+       * worth having when it arrives; failing without it would be this CLI
+       * refusing an answer that is otherwise complete.
+       */
+      const head = stringField(err.body, "head");
+      return {
+        status: "stale",
+        message: err.message + (head ? ` The branch is at ${head.slice(0, 7)} now.` : ""),
+        problems: parseProblems(err.details)
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * A step that did not answer is not a step that did not happen.
+ *
+ * Verify and promote can take minutes on content's side, and a connection that
+ * dies in the middle says nothing about what content did. Problems are kept on
+ * the row rather than only returned by the call that found them, so asking is
+ * not retrying: one `GET` gets the same answer the lost response carried.
+ */
+async function recoverWithStatus(err, client, publishId) {
+  if (err instanceof ContentHostError && err.statusCode === 0) {
+    return client.status(publishId);
+  }
+  throw err;
+}
+async function uploadAll(args) {
+  const {
+    client,
+    slots,
+    fileOf,
+    sleep
+  } = args;
+  const uploaded = [];
+  try {
+    await pool(slots, UPLOAD_CONCURRENCY, async slot => {
+      const file = fileOf.get(slot.key);
+      if (file === undefined) {
+        // Content asked for a key this build does not have. Declaring again
+        // cannot fix that, so it is not a round; it is a bug on one side.
+        throw new PublishProtocolError(`Content asked for an artifact this build does not have: ${slot.key}`);
+      }
+      for (let attempt = 1;; attempt++) {
+        try {
+          await client.upload(slot, file);
+          uploaded.push(slot.key);
+          return;
+        } catch (err) {
+          if (attempt >= UPLOAD_ATTEMPTS || !(err instanceof UploadError) || !isWorthRetrying(err)) {
+            throw err;
+          }
+          await sleep(250 * 2 ** attempt);
+        }
+      }
+    });
+  } catch (err) {
+    if (err instanceof UploadError && isExpiredSlot(err)) {
+      return {
+        status: "expired",
+        uploaded
+      };
+    }
+    throw err;
+  }
+  return {
+    status: "ok",
+    uploaded
+  };
+}
+
+/**
+ * Whether to try the same slot again.
+ *
+ * A dropped connection or a busy store, yes. A 403 is an expired slot and will
+ * be a 403 every time - that one is answered by declaring again, which is a
+ * round rather than a retry.
+ */
+function isWorthRetrying(err) {
+  return err.statusCode === 0 || err.statusCode === 429 || err.statusCode >= 500;
+}
+function errorFrom(err) {
+  if (err instanceof ContentHostError) {
+    const detail = detailText(err.details);
+    return {
+      status: "error",
+      message: err.statusCode === 401 || err.statusCode === 403 ? `${err.message}\n\nThe credential was refused. A project token can be revoked, and only a token carrying val:publish may publish.` : `${err.message}${detail ? `\n${detail}` : ""}`
+    };
+  }
+  if (err instanceof UploadError || err instanceof PublishProtocolError) {
+    return {
+      status: "error",
+      message: err.message
+    };
+  }
+  throw err;
+}
+
+/**
+ * Which commit this build is of, and which branch content commits saves to.
+ *
+ * The commit is baked into the published server and decides which version of
+ * its own content the site reads, so a wrong answer is worse than none: what
+ * the caller said, then Val's own variables, then the CI runner, then git.
+ *
+ * `GITHUB_SHA` before `git rev-parse` because on a `pull_request` event the
+ * checkout is a detached merge commit that exists only on the runner, and
+ * content committed against it would be committed against nothing.
+ */
+async function resolveGit(args) {
+  const {
+    root,
+    options,
+    env
+  } = args;
+  const fromGit = await safeReadGit(root);
+  const commit = options.commit ?? env.VAL_GIT_COMMIT ?? env.GITHUB_SHA ?? fromGit.commit;
+  const branchName = options.branch ?? env.VAL_GIT_BRANCH ?? env.GITHUB_REF_NAME ?? fromGit.branch;
+  // A detached HEAD has no branch, and "HEAD" is not one: content commits
+  // saves to a branch, and the failure would arrive hours later as a save that
+  // cannot be published.
+  const branch = branchName === "HEAD" ? undefined : branchName;
+  if (!commit || !branch) {
+    return {
+      status: "error",
+      message: `Could not tell which ${!commit ? "commit" : "branch"} this build is of.\n\n` + "Pass --commit and --branch, or set VAL_GIT_COMMIT and VAL_GIT_BRANCH.\n" + "The commit is baked into the published site and decides which version of\n" + "its own content it reads, so there is nothing safe to guess."
+    };
+  }
+  return {
+    status: "ok",
+    commit,
+    branch
+  };
+}
+function stringField(body, key) {
+  if (typeof body === "object" && body !== null) {
+    const value = Reflect.get(body, key);
+    if (typeof value === "string" && value !== "") {
+      return value;
+    }
+  }
+  return null;
+}
+
+/** "1 artifact", "3 artifacts". Every one of these lines ends up in a CI log. */
+function count(n, noun) {
+  return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["kB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value.toFixed(1)} ${units[unit]}`;
+}
+
+/**
+ * `val publish` - a built project in, a live site out.
+ *
+ * A thin shell around `runPublish`: everything it decides is decided there,
+ * and everything colourful happens here. A CI job reads the exit code, a
+ * person reads the lines.
+ */
+async function publish(options) {
+  const result = await runPublish({
+    ...(options.root ? {
+      root: options.root
+    } : {}),
+    ...(options.artifacts ? {
+      artifacts: options.artifacts
+    } : {}),
+    ...(options.commit ? {
+      commit: options.commit
+    } : {}),
+    ...(options.branch ? {
+      branch: options.branch
+    } : {}),
+    ...(options.layerRev ? {
+      layerRev: options.layerRev
+    } : {}),
+    ...(options.buildHash ? {
+      buildHash: options.buildHash
+    } : {}),
+    ...(options.linksOwnCss === undefined ? {} : {
+      linksOwnCss: options.linksOwnCss
+    }),
+    ...(options.dryRun ? {
+      dryRun: options.dryRun
+    } : {}),
+    log: line => console.log(pc.dim(line))
+  });
+  switch (result.status) {
+    case "live":
+    case "verified":
+      {
+        const uploaded = result.uploaded === 0 ? "nothing new to upload" : `${result.uploaded} uploaded, ${formatBytes(result.uploadedBytes)}`;
+        console.log(pc.green(result.status === "live" ? "✅ Published" : "✅ Verified (not published: --dry-run)") + pc.dim(` — ${result.artifacts} artifact${result.artifacts === 1 ? "" : "s"}, ${uploaded}`));
+        if (result.status === "live" && result.url) {
+          console.log(pc.cyan(result.url));
+        }
+        if (result.previewUrl) {
+          console.log(pc.dim("Canary: ") + pc.cyan(result.previewUrl));
+        }
+        return;
+      }
+    case "failed":
+      {
+        error(result.message);
+        for (const problem of result.problems) {
+          printProblem(problem);
+        }
+        if (result.previewUrl) {
+          console.error(pc.dim("Canary: ") + pc.cyan(result.previewUrl));
+        }
+        if (result.publishId) {
+          console.error(pc.dim(`Publish ${result.publishId}${result.state ? ` is "${result.state}"` : ""}.`));
+        }
+        process.exitCode = 1;
+        return;
+      }
+    case "error":
+      {
+        error(result.message);
+        process.exitCode = 1;
+        return;
+      }
+  }
+}
+
+/**
+ * A problem, as content wrote it.
+ *
+ * Verbatim, including the codes the build platform passed through: content
+ * knows what went wrong with the canary and this does not, so rewording can
+ * only lose the sentence that says what to change. The hint is printed for the
+ * same reason - a gate that merely fails is useless.
+ */
+function printProblem(problem) {
+  console.error(pc.red(problem.code ? `  ${problem.code}: ` : "  ") + problem.message);
+  const keys = problem.keys ?? [];
+  if (keys.length > 0) {
+    const shown = keys.slice(0, 10).join(", ");
+    console.error(pc.dim(`    ${shown}${keys.length > 10 ? `, and ${keys.length - 10} more` : ""}`));
+  }
+  if (problem.hint) {
+    console.error(pc.dim(`    ${problem.hint}`));
+  }
+}
+
 async function main() {
   const {
     input,
@@ -2027,6 +3402,7 @@ async function main() {
         login
         files
         connect
+        publish
         versions
         lsp
         debug
@@ -2051,6 +3427,32 @@ async function main() {
       Options:
         --root [root], -r [root] Set project root directory (default process.cwd())
 
+      Command: publish
+      Description: publish this project's build through content.val.build.
+        Declares the build's artifacts, uploads the ones content does not already hold,
+        and has content verify it by building and rendering a canary before the site
+        changes. Authenticates with VAL_PROJECT_TOKEN, or with the "val login" token in
+        .val/pat.json (which needs the project, as "<org>/<project>", in val.config or
+        VAL_PROJECT). Never as a flag: an argument is visible to anyone who can list
+        processes, and it is kept in shell history and in every CI log.
+      Options:
+        --root [root], -r [root] Set project root directory (default process.cwd())
+        --artifacts [dir]        The built artifacts (default <root>/.val/publish). The path
+                                 of each file under it is its artifact key: server, client,
+                                 css, rsc, layer, or a path under chunk/server, chunk/client,
+                                 chunk/rsc, asset, public
+        --commit [sha]           The commit this build is of (default VAL_GIT_COMMIT,
+                                 else GITHUB_SHA, else git HEAD)
+        --branch [name]          The branch content commits saves to (default VAL_GIT_BRANCH,
+                                 else GITHUB_REF_NAME, else the current git branch)
+        --layer-rev [rev]        Name the dependency layer content already holds, when this
+                                 build does not send one
+        --build-hash [hash]      Identify the build (default: a hash of its artifacts).
+                                 Declaring the same one twice resumes that publish
+        --links-own-css          The app links its own CSS (--no-links-own-css for the
+                                 opposite; omit it when the build did not say)
+        --dry-run                Verify, and stop before the site changes
+
       Command: list-unused-files
       Description: EXPERIMENTAL.
         List files that are in the configured files directory (files.directory, default public/val) but not in use by any Val module.
@@ -2114,6 +3516,18 @@ async function main() {
       out: {
         type: "string"
       },
+      artifacts: {
+        type: "string"
+      },
+      layerRev: {
+        type: "string"
+      },
+      buildHash: {
+        type: "string"
+      },
+      linksOwnCss: {
+        type: "boolean"
+      },
       commit: {
         type: "string"
       },
@@ -2177,6 +3591,17 @@ async function main() {
         yes: flags.yes,
         verbose: flags.verbose
       });
+    case "publish":
+      return publish({
+        root: flags.root,
+        artifacts: flags.artifacts,
+        commit: flags.commit,
+        branch: flags.branch,
+        layerRev: flags.layerRev,
+        buildHash: flags.buildHash,
+        linksOwnCss: flags.linksOwnCss,
+        dryRun: flags.dryRun
+      });
     case "login":
       return login({
         root: flags.root