@atelic-action/ui 0.15.1 → 0.16.1

package/src/scripts/serve-static.ts

@@ -0,0 +1,47 @@
+/**
+ * Serves dist/client the way Vercel does for these sites: a file as is, a
+ * clean URL from its .html file or folder index, and anything else as
+ * 404.html with a real 404 status. Only the e2e suite uses it; production
+ * never runs a server. The build it serves is the site's, found from the
+ * working directory.
+ *
+ * Usage: atelic-serve-static   (PORT sets the port, 4173 unless given)
+ */
+import { existsSync, statSync } from "node:fs";
+import { join, normalize } from "node:path";
+
+/** The file a request path names under `root`, by Vercel's clean URL rules; none on a miss. */
+export function resolveFile(root: string, pathname: string): string | undefined {
+	const clean = normalize(decodeURIComponent(pathname)).replace(/^(\.\.[/\\])+/, "");
+	const candidates = [
+		join(root, clean),
+		join(root, `${clean}.html`),
+		join(root, clean, "index.html"),
+	];
+	return candidates.find(
+		(file) => file.startsWith(root) && existsSync(file) && statSync(file).isFile(),
+	);
+}
+
+/** The command: serves dist/client of the working directory until stopped. */
+export function main(cwd: string = process.cwd()): void {
+	const root = join(cwd, "dist", "client");
+	const port = Number(process.env.PORT ?? 4173);
+
+	Bun.serve({
+		// Loopback only: this serves the build to the local browser under test and
+		// has no business answering anyone else on the network.
+		hostname: "127.0.0.1",
+		port,
+		fetch(request) {
+			const file = resolveFile(root, new URL(request.url).pathname);
+			if (file) return new Response(Bun.file(file));
+			return new Response(Bun.file(join(root, "404.html")), {
+				status: 404,
+				headers: { "content-type": "text/html; charset=utf-8" },
+			});
+		},
+	});
+
+	console.log(`serving ${root} on http://127.0.0.1:${port}`);
+}

package/src/scripts/site-config.ts

@@ -0,0 +1,34 @@
+/**
+ * Finds the site a command was run in. A command lives in the package, so
+ * it cannot import the site's config by a relative path as a script in the
+ * site once did: it resolves src/site.config.ts against the directory it
+ * was run from and imports that.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ArtifactConfig } from "../artifact/artifactConfig";
+
+/** Where a site keeps its config, from the site's root. */
+export const SITE_CONFIG = "src/site.config.ts";
+
+/** The absolute path of the config for the site rooted at `cwd`. */
+export function siteConfigPath(cwd: string = process.cwd()): string {
+	return resolve(cwd, SITE_CONFIG);
+}
+
+/**
+ * The `site` export of the config in `cwd`. Throws one line naming the
+ * directory when there is no config there, or when it exports no `site`.
+ */
+export async function loadSite(cwd: string = process.cwd()): Promise<ArtifactConfig> {
+	const path = siteConfigPath(cwd);
+	if (!existsSync(path)) {
+		throw new Error(`no ${SITE_CONFIG} in ${cwd}. Run this from the root of an artifact site.`);
+	}
+	const module = (await import(pathToFileURL(path).href)) as { site?: ArtifactConfig };
+	if (!module.site) {
+		throw new Error(`${SITE_CONFIG} in ${cwd} exports no \`site\`.`);
+	}
+	return module.site;
+}

package/src/scripts/stamp-health.ts

@@ -0,0 +1,29 @@
+/**
+ * Writes dist/client/health.json after the build: a shallow health endpoint
+ * for uptime monitors that also answers "which build is live?".
+ * Runs as the last step of `bun build`, from the site's root.
+ *
+ * Usage: atelic-stamp-health
+ */
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+
+function commitSha(): string {
+	// Vercel builds have no .git directory; the CLI/CI export the sha instead.
+	const fromEnv = process.env.VERCEL_GIT_COMMIT_SHA ?? process.env.GITHUB_SHA;
+	if (fromEnv) return fromEnv.slice(0, 7);
+	const git = spawnSync("git", ["rev-parse", "--short", "HEAD"], { encoding: "utf8" });
+	return git.status === 0 ? git.stdout.trim() : "unknown";
+}
+
+/** The command: stamps the build in the working directory. */
+export function main(): void {
+	const health = {
+		status: "ok",
+		commit: commitSha(),
+		builtAt: new Date().toISOString(),
+	};
+
+	writeFileSync("dist/client/health.json", `${JSON.stringify(health, null, "\t")}\n`);
+	console.log(`[health] dist/client/health.json (${health.commit})`);
+}

package/src/vite/artifact-config.ts

@@ -0,0 +1,105 @@
+/**
+ * The whole Vite configuration of an artifact site, as one call. Every site
+ * cut from the artifact template carried its own copy of this configuration;
+ * here it is written once, and a site's vite.config.ts names its pages:
+ *
+ *   import { artifactConfig } from "@atelic-action/ui/vite";
+ *
+ *   export default artifactConfig({ pages: ["/writeup", "/proposal", "/report"] });
+ *
+ * The site's own paths (the `@` alias to its src) are found from the
+ * directory Vite is run in, which is the site's root.
+ */
+import { resolve } from "node:path";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import { mergeConfig, type UserConfig } from "vite";
+import { privateChunks } from "./private-chunks.js";
+
+export interface ArtifactConfigOptions {
+	/**
+	 * The path of each artifact page the site carries, such as "/writeup".
+	 * The root and the 404 page are always prerendered and need no entry.
+	 */
+	pages: readonly string[];
+	/**
+	 * The escape hatch for a site with a real need of its own: merged over
+	 * the result with Vite's `mergeConfig`, so a site adds a setting without
+	 * going back to a configuration written by hand.
+	 */
+	extend?: UserConfig;
+}
+
+/** One entry of the prerender list. */
+export interface ArtifactPage {
+	path: string;
+	prerender: { enabled: true };
+}
+
+/** The prerender list for a site: the root, each page it names, then the 404. */
+export function artifactPages(pages: readonly string[]): ArtifactPage[] {
+	const named = pages.filter((path) => path !== "/" && path !== "/404");
+	return [
+		// The root holds no document: it sends the reader to /writeup
+		// (vercel.json does the same on the host), and its prerendered
+		// index.html is what a static preview serves at the bare host.
+		{ path: "/", prerender: { enabled: true } },
+		...named.map((path): ArtifactPage => ({ path, prerender: { enabled: true } })),
+		// The 404 page, rendered by the catch all route and copied to
+		// dist/client/404.html by the build for the host to serve on any miss.
+		{ path: "/404", prerender: { enabled: true } },
+	];
+}
+
+export function artifactConfig({ pages, extend }: ArtifactConfigOptions): UserConfig {
+	const config: UserConfig = {
+		// Every stylesheet rides in the one base sheet the root route links
+		// (src/styles/base.css), the documents' own included, since they come from
+		// @atelic-action/ui. Nothing imports CSS from a component, so there is no
+		// component bundle to fold: `build.cssCodeSplit: false`, which sat here to
+		// fold it, now fails the build, because TanStack Start looks for the
+		// `style.css` that setting emits and none is written. A site that gives a
+		// component its own stylesheet again restores the setting through `extend`.
+		plugins: [
+			tanstackStart({
+				prerender: {
+					enabled: true,
+					crawlLinks: true,
+					// The writeup links each screenshot crop to its full image, and
+					// the crawler follows every href it finds: without this filter it
+					// prerenders /images/<shot>.png as an HTML page and writes that
+					// over the real file in dist/client (found on a client's writeup,
+					// 2026-09-24).
+					filter: ({ path }) => !path.startsWith("/images/"),
+				},
+				// Nothing links to an artifact page, so the crawler would miss every
+				// one of them; each is listed by the site to be prerendered at all. A
+				// site names the pages it uses and no others.
+				pages: artifactPages(pages),
+				// No sitemap. A sitemap is a page asking to be crawled, and every
+				// page here is a document prepared for one business; public/robots.txt
+				// disallows the whole host to match.
+				sitemap: { enabled: false },
+			}),
+			react(),
+			// A document's content builds into /assets/doc/, which the access wall
+			// holds back, and the build fails if any lands where the login page
+			// can load it (privateChunks beside this file, needsSession in
+			// @atelic-action/ui/gate).
+			privateChunks(),
+		],
+		resolve: {
+			alias: {
+				// The site's src, from the directory Vite is run in: this file lives
+				// in the package, so nothing here can be found relative to it.
+				"@": resolve(process.cwd(), "./src"),
+			},
+		},
+		// @atelic-action/ui ships TSX and CSS as written, so the prerender's server build
+		// has to compile it rather than hand it to Node as an external.
+		ssr: {
+			noExternal: ["@atelic-action/ui"],
+		},
+	};
+	return extend ? mergeConfig(config, extend) : config;
+}

package/src/vite/index.ts

@@ -0,0 +1,12 @@
+/**
+ * What a site's vite.config.ts imports (`@atelic-action/ui/vite`): the
+ * configuration of an artifact site as one call, and the plugin inside it
+ * for a site that writes its own.
+ */
+export {
+	type ArtifactConfigOptions,
+	type ArtifactPage,
+	artifactConfig,
+	artifactPages,
+} from "./artifact-config.js";
+export { DOC_DIR, isPrivateContent, privateChunks } from "./private-chunks.js";