@valbuild/cli 0.137.0 → 0.138.1

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

@@ -6,13 +6,14 @@ import { glob } from 'fast-glob';
 import { Internal, DEFAULT_VAL_REMOTE_HOST, DEFAULT_CONTENT_HOST } from '@valbuild/core';
 import { createPrettierFormatter, createService, createValModuleFileInspector, fixHandlers, createFixPatch, getModulePathRange, findJsonEntryFilePath, createJsonEntryPathMap, createModulePathMap, findAndEvalValConfigFile, getSettings, uploadRemoteFile, createDefaultValFSHost, startValLogin, awaitValLoginConfirmation, persistPersonalAccessToken, ValLoginError, loadValModules, safeReadGit, ValOpsHttp, ValOpsFS, getPersonalAccessTokenPath, parsePersonalAccessTokenFile, formatPatchSourceError } from '@valbuild/server';
 import fs from 'fs/promises';
-import { resolveSchemaSourceFixes, parseDeclare, parseArtifacts, parseVerify, parsePromote, parseStatus, parsePublishToken, PublishProtocolError, parseProblems } from '@valbuild/shared/internal';
+import { resolveSchemaSourceFixes, parseBuildTarget, parseDeclare, parseArtifacts, parseVerify, parsePromote, parseStatus, parsePublishToken, PublishProtocolError, parseProblems } from '@valbuild/shared/internal';
 import fs$1 from 'fs';
 import ts from 'typescript';
 import JSZip from 'jszip';
 import readline from 'readline';
 import crypto from 'crypto';
 import zlib from 'zlib';
+import os from 'os';
 
 function error(message) {
   console.error(chalk.red("❌Error: ") + message);
@@ -2095,10 +2096,10 @@ function confirm(question) {
  * 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.
+ * **This is the seam with the build.** Whatever built the project writes this
+ * directory, and this reads it: `buildArtifacts` when `val publish` builds the
+ * checkout itself, or anything else that lays out the same keys, handed over
+ * with `--artifacts`. One path for bytes to leave by, whoever built them.
  */
 async function collectArtifacts(dir) {
   const artifacts = [];
@@ -2250,6 +2251,308 @@ function resolveArtifactsDir(options) {
   };
 }
 
+/**
+ * `val publish`'s build: the site, built from the checkout, as the artifacts
+ * the publish API takes (valbuild/home, docs/app-mode.md, "Briefing:
+ * val-publish" and "Flow B").
+ *
+ * The same builder the Studio runs in a tab -- `@valbuild/tanstack-build` --
+ * plus the half a tab cannot run: the project's dependency layer, built from
+ * its own `node_modules` (`@valbuild/tanstack-build/node`). So a CI checkout
+ * and a Studio build of the same content produce the same site, and the layer
+ * is the one thing only this side can make.
+ *
+ * Against content's build target, never the loader's: content is the only
+ * address a publisher has, and it answers what the platform expects.
+ *
+ * Written to a directory, and then published by the upload path `val publish
+ * --artifacts` has always had: one path for bytes to leave by, whoever built
+ * them.
+ */
+
+/** What `val publish` hands on to the upload. */
+
+/**
+ * The builder, loaded only when a build is asked for: it brings rolldown's
+ * native binary with it, and `val validate` has no use for one.
+ */
+async function loadBuilder() {
+  try {
+    const [build, node] = await Promise.all([import('@valbuild/tanstack-build'), import('@valbuild/tanstack-build/node')]);
+    return {
+      status: "ok",
+      build,
+      node
+    };
+  } catch (e) {
+    return {
+      status: "error",
+      message: "`val publish` builds the site with @valbuild/tanstack-build and rolldown, and " + `they could not be loaded: ${e instanceof Error ? e.message : String(e)}\n\n` + "Install them in the project:\n\n" + "    npm install --save-dev @valbuild/tanstack-build rolldown @tanstack/router-generator @tanstack/router-plugin\n\n" + "or publish a build made elsewhere with --artifacts <dir>."
+    };
+  }
+}
+
+/**
+ * Never the project's own files, at any depth: installed packages. Dot
+ * directories (`.git`, `.tanstack`, `.val`, `.output`) are tooling too.
+ */
+const IGNORED_DIRS = new Set(["node_modules"]);
+
+/**
+ * Build output, at the project's root only: `src/routes/build/` is a route
+ * called "build", not a previous build.
+ */
+const ROOT_OUTPUT_DIRS = new Set(["dist", "build"]);
+
+/** Lockfiles are JSON, and nothing imports them. */
+const ROOT_LOCKFILES = new Set(["package-lock.json"]);
+const CODE_FILE = /\.(tsx?|jsx?|mjs|cjs|css)$/;
+
+/**
+ * JSON is the project's too: `tsconfig.json` and `tsr.config.json` are read
+ * by the build, a `.val.json` holds a `.jsonValues()` entry no import points
+ * at, and a module may import one -- the starter's `val.server.ts` imports
+ * `.prettierrc.json`, which is also why a dot FILE is read.
+ */
+const JSON_FILE = /\.json$/;
+
+/**
+ * The project's source as it is STORED, which is what the Studio builds from:
+ * every file this build read, less the stylesheets.
+ *
+ * This build compiles them, because it can run what a stylesheet asks for -- a
+ * Tailwind `@plugin` is a module resolved and executed from `node_modules`. A
+ * build in the browser cannot, and refuses the stylesheet rather than ship a
+ * page that is quietly unstyled; the starter's `src/styles.css` has
+ * `@plugin "@tailwindcss/typography"`. So a stored stylesheet made every
+ * Studio publish after the first one fail. Without it, the Studio's build has
+ * no CSS of its own and ships the live site's (`liveStylesheet` in the
+ * Studio), which is right: a Studio save changes content and uploaded files,
+ * never a stylesheet. It is also what the platform's own publish has always
+ * stored.
+ */
+function withoutStylesheets(sources) {
+  return Object.fromEntries(Object.entries(sources).filter(([key]) => !key.endsWith(".css")));
+}
+
+/**
+ * The project's own files: its source as text, and the binaries it imports
+ * (an image, a font) base64, as `BuildInput.assets` takes them. `public/` is
+ * neither: it is served as is, and read by `readPublicFiles`.
+ */
+function readProjectFiles(root, isAsset) {
+  const sources = {};
+  const assets = {};
+  const walk = dir => {
+    let entries;
+    try {
+      entries = fs$1.readdirSync(dir, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || IGNORED_DIRS.has(entry.name)) continue;
+        if (dir === root && ROOT_OUTPUT_DIRS.has(entry.name)) continue;
+        if (dir === root && entry.name === "public") continue;
+        walk(full);
+        continue;
+      }
+      const key = path.relative(root, full).split(path.sep).join("/");
+      if (CODE_FILE.test(entry.name)) {
+        sources[key] = fs$1.readFileSync(full, "utf8");
+      } else if (JSON_FILE.test(entry.name)) {
+        if (!ROOT_LOCKFILES.has(key)) {
+          sources[key] = fs$1.readFileSync(full, "utf8");
+        }
+      } else if (isAsset(key)) {
+        assets[key] = fs$1.readFileSync(full).toString("base64");
+      }
+    }
+  };
+  walk(root);
+  return {
+    sources,
+    assets
+  };
+}
+
+/** Files under `public/`, base64, keyed `public/<path>` as the build takes them. */
+function readPublicFiles(root) {
+  const out = {};
+  const base = path.join(root, "public");
+  const walk = dir => {
+    let entries;
+    try {
+      entries = fs$1.readdirSync(dir, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);else {
+        const key = path.relative(root, full).split(path.sep).join("/");
+        out[key] = fs$1.readFileSync(full).toString("base64");
+      }
+    }
+  };
+  walk(base);
+  return out;
+}
+
+/** The project's build-time variables: `PUBLIC_*` reach the browser, by the builder's rule. */
+function publicEnv(env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith("PUBLIC_") && value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * The target, with this project's layer as built here rather than as content
+ * last stored it: a build has to link against the layer it ships with.
+ */
+function targetWithLayer(target, layer) {
+  return {
+    ...target,
+    project: {
+      ...target.project,
+      rev: (layer === null || layer === void 0 ? void 0 : layer.rev) ?? null,
+      modules: (layer === null || layer === void 0 ? void 0 : layer.modules) ?? {},
+      css: (layer === null || layer === void 0 ? void 0 : layer.css) ?? {},
+      workerOnly: (layer === null || layer === void 0 ? void 0 : layer.workerOnly) ?? []
+    }
+  };
+}
+function writeArtifact(dir, key, body) {
+  const file = path.join(dir, ...key.split("/"));
+  fs$1.mkdirSync(path.dirname(file), {
+    recursive: true
+  });
+  fs$1.writeFileSync(file, body);
+}
+async function buildArtifacts(options) {
+  const log = options.log ?? (() => {});
+  const loaded = await loadBuilder();
+  if (loaded.status === "error") return loaded;
+  const {
+    build: builder,
+    node
+  } = loaded;
+  const {
+    root,
+    target
+  } = options;
+  const warnings = [];
+  try {
+    /*
+     * Wired for the platform at publish time, as the Studio's builds are: the
+     * wired `val.server.ts` reads its files from a module the BUILD emits, so
+     * no checkout can carry it. `rebakeGit` would be the tab's spelling of the
+     * same thing for a record that is already wired.
+     */
+    const {
+      sources: onDisk,
+      assets
+    } = readProjectFiles(root, builder.isAsset);
+    const wiring = builder.isValProject(onDisk) && !builder.isWired(onDisk) ? builder.wireUp(onDisk, {
+      project: options.project,
+      loader: options.contentHost,
+      ...(options.git ? {
+        git: options.git
+      } : {})
+    }) : null;
+    // Less the one about the layer, which is the thing this goes on to build.
+    warnings.push(...((wiring === null || wiring === void 0 ? void 0 : wiring.warnings) ?? []).filter(warning => !warning.includes("dependency layer built for it")));
+    const sources = (wiring === null || wiring === void 0 ? void 0 : wiring.files) ?? onDisk;
+    const projectSource = withoutStylesheets(sources);
+
+    // The dependency layer: from what the project imports, of what it declares.
+    log("Building the dependency layer");
+    const manifest = (() => {
+      try {
+        return JSON.parse(sources["package.json"] ?? "{}");
+      } catch {
+        return {};
+      }
+    })();
+    const deps = node.layerDepsOf(manifest, sources);
+    const css = await node.collectDependencyCss(root, node.cssSpecifiersOf(sources));
+    const layer = await node.buildVendorLayer(root, deps, css, {
+      base: target.base,
+      // A project on the platform layers its own copies; only the platform's
+      // own checkout carries pinned ones.
+      resolvePlatformModule: () => null,
+      // No built base layer here: the export audit is skipped, not failed.
+      baseLayerDir: null
+    });
+    log("Building the site");
+    const fileBased = await node.isFileBased(root);
+    const files = fileBased ? await node.generateRouteTree(root, sources) : sources;
+    /*
+     * The project's copy of the splitter first, then the one beside this CLI
+     * -- where a package manager puts an optional peer the project installed
+     * but did not hoist. Neither is a build that does not split, which costs
+     * size and not behaviour.
+     */
+    const splitter = (await node.routeSplitter(root)) ?? (typeof __dirname === "string" ? await node.routeSplitter(__dirname) : null);
+    if (splitter === null) {
+      warnings.push("Routes are not code-split: @tanstack/router-plugin is not installed.");
+    }
+    const built = await builder.buildUserApp({
+      files,
+      target: targetWithLayer(target, layer),
+      env: publicEnv(options.env ?? process.env),
+      publicFiles: readPublicFiles(root),
+      assets,
+      // The project's own files, without the generated tree or the
+      // stylesheets: what the next publish -- the Studio's included -- starts
+      // from. See `withoutStylesheets`.
+      projectSource,
+      loadCssModule: node.cssModuleLoader(root),
+      ...(splitter ? {
+        routeSplitter: splitter
+      } : {}),
+      rsc: target.project.rsc
+    });
+    const artifacts = await builder.publishArtifacts(built, {
+      projectSource
+    });
+    const dir = options.outDir ?? fs$1.mkdtempSync(path.join(os.tmpdir(), "val-publish-"));
+    for (const artifact of artifacts) {
+      writeArtifact(dir, artifact.key, artifact.body);
+    }
+    /*
+     * The layer: sent when content does not hold this one, named when it
+     * does. The rev is a digest of the built chunks, so "content has this" is
+     * a fact rather than a hope.
+     */
+    let layerRev;
+    if (layer === null) layerRev = null;else if (layer.rev === target.project.rev) layerRev = layer.rev;else writeArtifact(dir, "layer", zlib.gzipSync(JSON.stringify(layer)));
+    return {
+      status: "built",
+      dir,
+      buildHash: built.hash,
+      linksOwnCss: built.linksOwnCss,
+      ...(layerRev !== undefined ? {
+        layerRev
+      } : {}),
+      warnings
+    };
+  } catch (e) {
+    return {
+      status: "error",
+      message: `The site could not be built: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`
+    };
+  }
+}
+
 /**
  * The one host `val publish` talks to.
  *
@@ -2396,6 +2699,11 @@ function createPublishClient(options) {
   };
   const publishUrl = (publishId, step) => `${host}/v1/publish/${encodeURIComponent(publishId)}${step ? `/${step}` : ""}`;
   return {
+    buildTarget: async () => parseBuildTarget(await getJson({
+      url: `${host}/v1/build-target`,
+      headers,
+      fetchImpl
+    })),
     declare: async body => parseDeclare(await postJson({
       url: `${host}/v1/publish`,
       headers,
@@ -2735,40 +3043,33 @@ const DECLARE_ROUNDS = 3;
  * that could reach either.
  */
 async function runPublish(options) {
+  var _built;
   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") {
+
+  /*
+   * Upload-only when there is a build to upload: `--artifacts`, or the
+   * directory it defaults to. Otherwise this builds the checkout -- which is
+   * what a CI runner has, and `.val/` is never committed, so a fresh checkout
+   * always builds.
+   */
+  const prebuilt = options.artifacts !== undefined || fs$1.existsSync(path.join(root, DEFAULT_ARTIFACTS_DIR));
+  if (!prebuilt && !fs$1.existsSync(path.join(root, "package.json"))) {
     return {
       status: "error",
-      message: dir.message
+      message: `Nothing to publish: ${root} has no package.json to build, and no --artifacts were given.\n\n` + "Run this in the project, or point at a build made elsewhere:\n\n" + "    npx val publish --artifacts <directory>"
     };
   }
-  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.`
-    };
+  let collected = null;
+  let layerRev = null;
+  if (prebuilt) {
+    const fromDir = await collectPrebuilt(root, options.artifacts, log);
+    if (fromDir.status === "error") return fromDir;
+    collected = fromDir.collected;
+    layerRev = fromDir.layerRev;
   }
-  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,
@@ -2778,9 +3079,10 @@ async function runPublish(options) {
     return git;
   }
   const config = await findAndEvalValConfigFile(root).catch(() => null);
+  const project = (config === null || config === void 0 ? void 0 : config.project) ?? env.VAL_PROJECT ?? null;
   const credential = await resolvePublishCredential({
     root,
-    project: (config === null || config === void 0 ? void 0 : config.project) ?? env.VAL_PROJECT ?? null,
+    project,
     env,
     ...(options.fetchImpl ? {
       fetchImpl: options.fetchImpl
@@ -2792,16 +3094,52 @@ async function runPublish(options) {
       message: credential.message
     };
   }
+  const contentHost = getContentHost(env);
   const client = createPublishClient({
-    host: getContentHost(env),
+    host: contentHost,
     token: credential.credential.token,
     ...(options.fetchImpl ? {
       fetchImpl: options.fetchImpl
     } : {})
   });
-  const buildHash = options.buildHash ?? buildHashOf(collected.artifacts);
+  let built = null;
+  try {
+    if (collected === null) {
+      log("Asking content what to build against");
+      const target = await client.buildTarget();
+      const build = await buildArtifacts({
+        root,
+        target,
+        project: project ?? "",
+        contentHost,
+        git: {
+          commit: git.commit,
+          branch: git.branch
+        },
+        env,
+        log
+      });
+      if (build.status === "error") {
+        return {
+          status: "error",
+          message: build.message
+        };
+      }
+      built = build;
+      for (const warning of build.warnings) log(`warn: ${warning}`);
+      const fromBuild = await collectPrebuilt(root, build.dir, log);
+      if (fromBuild.status === "error") return fromBuild;
+      collected = fromBuild.collected;
+      // Named when content already holds it; otherwise it is in the directory.
+      layerRev = build.layerRev !== undefined ? build.layerRev : fromBuild.layerRev;
+    }
+  } catch (err) {
+    return errorFrom(err);
+  }
+  const buildHash = options.buildHash ?? ((_built = built) === null || _built === void 0 ? void 0 : _built.buildHash) ?? buildHashOf(collected.artifacts);
   log(`${count(collected.artifacts.length, "artifact")}, ${formatBytes(collected.totalBytes)}` + `, at ${git.commit.slice(0, 7)} on ${git.branch}`);
   try {
+    var _built2;
     return await publishDeclaredBuild({
       client,
       log,
@@ -2812,8 +3150,8 @@ async function runPublish(options) {
         buildHash,
         commit: git.commit,
         branch: git.branch,
-        layerRev,
-        linksOwnCss: options.linksOwnCss ?? null,
+        layerRev: options.layerRev ?? layerRev,
+        linksOwnCss: options.linksOwnCss ?? ((_built2 = built) === null || _built2 === void 0 ? void 0 : _built2.linksOwnCss) ?? null,
         artifacts: collected.artifacts.map(({
           key,
           sha256,
@@ -2828,7 +3166,53 @@ async function runPublish(options) {
     });
   } catch (err) {
     return errorFrom(err);
+  } finally {
+    // Ours to remove: a build is written to a fresh temporary directory.
+    if (built !== null) {
+      fs$1.rmSync(built.dir, {
+        recursive: true,
+        force: true
+      });
+    }
+  }
+}
+
+/** A build on disk: its artifacts, and the layer it sends or names. */
+async function collectPrebuilt(root, artifacts, log) {
+  const dir = resolveArtifactsDir({
+    root,
+    ...(artifacts ? {
+      dir: 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
+    };
+  }
+  return {
+    status: "ok",
+    collected,
+    layerRev: layer.layerRev
+  };
 }
 async function publishDeclaredBuild(args) {
   const {
@@ -3322,6 +3706,125 @@ function printProblem(problem) {
   }
 }
 
+/**
+ * `val ci-report` -- CI saying how its build of a commit went.
+ *
+ * The last step of a connected project's workflow, run whether the build
+ * passed or not. Content learns a build failed from this and nothing else,
+ * so it needs no GitHub permission to tell an editor "Published, not on the
+ * site yet: the build failed" (valbuild/home, docs/app-mode.md, "Failures":
+ * after the seal). The run's address goes with it, for "View run".
+ *
+ * Everything has a default from GitHub Actions' own environment -- the
+ * commit it checked out, the branch it ran for, the run's URL -- so the step
+ * is one line. Never fails the job over a report it could not send: the
+ * build's own result is what the job's status is, and a report is advice.
+ */
+
+function ciReportFromEnv(options, env = process.env) {
+  const status = options.status;
+  if (status !== "failed" && status !== "succeeded") {
+    return {
+      status: "error",
+      message: `--status is "failed" or "succeeded"${status === undefined ? "" : `, not "${status}"`}.`
+    };
+  }
+  const commit = options.commit ?? env.GITHUB_SHA ?? env.VAL_GIT_COMMIT;
+  if (!commit) {
+    return {
+      status: "error",
+      message: "No commit to report on: pass --commit, or run this in GitHub Actions (GITHUB_SHA)."
+    };
+  }
+  const branch = options.branch ?? env.GITHUB_REF_NAME ?? env.VAL_GIT_BRANCH;
+  const url = options.url ?? (env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined);
+  return {
+    status: "ok",
+    report: {
+      status,
+      commit,
+      ...(branch ? {
+        branch
+      } : {}),
+      ...(url ? {
+        url
+      } : {})
+    }
+  };
+}
+async function reportCiRun(options) {
+  const env = options.env ?? process.env;
+  const config = await findAndEvalValConfigFile(options.root).catch(() => null);
+  const credential = await resolvePublishCredential({
+    root: options.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 body = options.report;
+  try {
+    await postJson({
+      url: `${getContentHost(env)}/v1/ci-runs`,
+      headers: {
+        Authorization: `Bearer ${credential.credential.token}`
+      },
+      body,
+      ...(options.fetchImpl ? {
+        fetchImpl: options.fetchImpl
+      } : {})
+    });
+    return {
+      status: "reported"
+    };
+  } catch (e) {
+    return {
+      status: "error",
+      message: e instanceof ContentHostError ? `Content did not take the report (${e.statusCode}): ${e.message}` : e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+
+/**
+ * `val ci-report` -- a thin shell around `reportCiRun`. It never fails the
+ * job: the build's own result is what the job's status is, and a report that
+ * could not be sent is said and then left.
+ */
+async function ciReport(options) {
+  const read = ciReportFromEnv({
+    status: options.status,
+    ...(options.commit ? {
+      commit: options.commit
+    } : {}),
+    ...(options.branch ? {
+      branch: options.branch
+    } : {}),
+    ...(options.url ? {
+      url: options.url
+    } : {})
+  });
+  if (read.status === "error") {
+    console.error(pc.yellow(`val ci-report: ${read.message}`));
+    return;
+  }
+  const sent = await reportCiRun({
+    root: options.root ?? process.cwd(),
+    report: read.report
+  });
+  if (sent.status === "error") {
+    console.error(pc.yellow(`val ci-report: not reported. ${sent.message}`));
+    return;
+  }
+  console.log(pc.dim(`Reported the build of ${read.report.commit.slice(0, 7)} as ${read.report.status}.`));
+}
+
 async function main() {
   const {
     input,
@@ -3364,19 +3867,35 @@ async function main() {
       Options:
         --root [root], -r [root] Set project root directory (default process.cwd())
 
+      Command: ci-report
+      Description: tell content how CI's build of a commit went, for a connected
+                   project's workflow. Run as its last step, whatever the build did:
+                   a failed build then reads "Published, not on the site yet" in the
+                   Studio, with a link to the run. Never fails the job.
+      Options:
+        --status [failed|succeeded]  How the build went
+        --commit [sha]           The commit built (default GITHUB_SHA)
+        --branch [name]          Its branch (default GITHUB_REF_NAME, else the project's)
+        --url [url]              The run (default this GitHub Actions run)
+
       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.
+      Description: build this project and publish it through content.val.build.
+        Asks content what to build against, builds the site and its dependency layer from
+        the checkout (needs @valbuild/tanstack-build, rolldown, @tanstack/router-generator
+        and @tanstack/router-plugin installed), declares the artifacts, uploads the ones
+        content does not already hold, and has content verify it by building and rendering
+        a canary before the site changes. With --artifacts, or a .val/publish directory,
+        it publishes that build instead of making one. 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,
+        --artifacts [dir]        Publish a build made elsewhere (default: build the checkout,
+                                 unless <root>/.val/publish exists). The path of each file
+                                 under it is its artifact key: server, client, css, rsc,
+                                 layer, source, 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)
@@ -3485,6 +4004,12 @@ async function main() {
       },
       verbose: {
         type: "boolean"
+      },
+      status: {
+        type: "string"
+      },
+      url: {
+        type: "string"
       }
     },
     hardRejection: false
@@ -3528,6 +4053,14 @@ async function main() {
         yes: flags.yes,
         verbose: flags.verbose
       });
+    case "ci-report":
+      return ciReport({
+        root: flags.root,
+        status: flags.status,
+        commit: flags.commit,
+        branch: flags.branch,
+        url: flags.url
+      });
     case "publish":
       return publish({
         root: flags.root,