@mh-gg/vite 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# matterhorn-sdk/vite
+
+Vite plugin for Matterhorn frontend bundle publishing.
+
+This package keeps the standalone `@mh-gg/vite` package available, but new code should import the plugin through `matterhorn-sdk/vite`.
+
+```ts
+import { defineConfig } from "vite";
+import { matterhorn } from "matterhorn-sdk/vite";
+
+export default defineConfig({
+  plugins: [matterhorn()]
+});
+```
+
+The plugin emits:
+
+- `matterhorn-frontend-manifest.json`, listing every built file with SHA-256 integrity and byte length.
+- `matterhorn-frontend-bundle.zip`, containing the built files plus the manifest.
+
+By default these files are written to the Vite root, not `dist`, so the generated archive is not included in the files it describes. Pass a relative directory when you want a separate deploy folder:
+
+```ts
+plugins: [matterhorn("./deploy/")]
+```

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@mh-gg/vite",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "description": "Vite plugin for Matterhorn frontend bundle manifests and archives.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,321 @@
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const DEFAULT_MANIFEST_FILE = "matterhorn-frontend-manifest.json";
+const DEFAULT_ARCHIVE_FILE = "matterhorn-frontend-bundle.zip";
+const DOCUMENT_ENTRYPOINT = "index.html";
+
+function pluginOptions(value) {
+  if (typeof value === "string") return { path: value };
+  if (value && typeof value === "object") return value;
+  return {};
+}
+function bytes(value) {
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  return Buffer.from(String(value));
+}
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function dosTime(date) {
+  return ((date.getHours() & 31) << 11) | ((date.getMinutes() & 63) << 5) | Math.floor(date.getSeconds() / 2);
+}
+
+function dosDate(date) {
+  return (((date.getFullYear() - 1980) & 127) << 9) | (((date.getMonth() + 1) & 15) << 5) | (date.getDate() & 31);
+}
+
+function u16(value) {
+  const buffer = Buffer.allocUnsafe(2);
+  buffer.writeUInt16LE(value);
+  return buffer;
+}
+
+function u32(value) {
+  const buffer = Buffer.allocUnsafe(4);
+  buffer.writeUInt32LE(value);
+  return buffer;
+}
+
+function zipStore(files) {
+  const date = new Date("2020-01-01T00:00:00Z");
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const name = bytes(file.path);
+    const body = bytes(file.body);
+    const checksum = crc32(body);
+    const localHeader = Buffer.concat([
+      u32(0x04034b50), u16(20), u16(0x0800), u16(0), u16(dosTime(date)), u16(dosDate(date)),
+      u32(checksum), u32(body.byteLength), u32(body.byteLength), u16(name.byteLength), u16(0), name
+    ]);
+    localParts.push(localHeader, body);
+    centralParts.push(Buffer.concat([
+      u32(0x02014b50), u16(20), u16(20), u16(0x0800), u16(0), u16(dosTime(date)), u16(dosDate(date)),
+      u32(checksum), u32(body.byteLength), u32(body.byteLength), u16(name.byteLength), u16(0), u16(0),
+      u16(0), u16(0), u32(0), u32(offset), name
+    ]));
+    offset += localHeader.byteLength + body.byteLength;
+  }
+
+  const central = Buffer.concat(centralParts);
+  return Buffer.concat([
+    ...localParts,
+    central,
+    u32(0x06054b50), u16(0), u16(0), u16(files.length), u16(files.length),
+    u32(central.byteLength), u32(offset), u16(0)
+  ]);
+}
+
+function integrity(buffer) {
+  return `sha256-${createHash("sha256").update(buffer).digest("hex")}`;
+}
+
+function sha256FromIntegrity(value) {
+  return value.slice("sha256-".length);
+}
+
+function contentType(fileName) {
+  if (fileName.endsWith(".js") || fileName.endsWith(".mjs")) return "text/javascript";
+  if (fileName.endsWith(".css")) return "text/css";
+  if (fileName.endsWith(".html")) return "text/html";
+  if (fileName.endsWith(".json")) return "application/json";
+  if (fileName.endsWith(".svg")) return "image/svg+xml";
+  if (fileName.endsWith(".wasm")) return "application/wasm";
+  return "application/octet-stream";
+}
+
+function chunkKind(fileName, type) {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith(".map")) return "source-map";
+  if (lower.endsWith(".wasm") || type === "application/wasm") return "wasm";
+  if (lower.endsWith(".worker.js") || lower.endsWith(".worker.mjs") || lower.includes("/workers/")) return "worker";
+  if (lower.endsWith(".js") || lower.endsWith(".mjs") || type === "text/javascript") return "script";
+  if (lower.endsWith(".css") || type === "text/css") return "style";
+  return "asset";
+}
+
+function chunkExecutable(kind) {
+  return kind === "script" || kind === "style" || kind === "wasm" || kind === "worker";
+}
+
+function frontendChunksFromFiles(files, entrypoint) {
+  const chunks = files
+    .map((file) => {
+      const kind = chunkKind(file.path, file.type);
+      if (kind === "asset") return undefined;
+      return {
+        id: file.path,
+        url: file.path,
+        sha256: sha256FromIntegrity(file.integrity),
+        bytes: file.byteLength,
+        contentType: file.type,
+        kind,
+        executable: chunkExecutable(kind),
+        entry: file.path === entrypoint
+      };
+    })
+    .filter(Boolean);
+  return {
+    schemaVersion: 1,
+    algorithm: "sha256",
+    hashEncoding: "hex",
+    sourceMapPolicy: chunks.some((chunk) => chunk.kind === "source-map") ? "included" : "excluded",
+    chunks
+  };
+}
+
+function bundleOutputFiles(bundle) {
+  return new Set(Object.values(bundle)
+    .map((item) => normalizePath(item.fileName))
+    .filter(Boolean));
+}
+
+function assertBundleFilesIncluded(files, bundle) {
+  const manifestPaths = new Set(files.map((file) => file.path));
+  for (const fileName of bundleOutputFiles(bundle)) {
+    if (!manifestPaths.has(fileName)) {
+      throw new Error(`Matterhorn Vite manifest is missing emitted bundle file: ${fileName}`);
+    }
+  }
+}
+
+function normalizePath(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function outputDir(outputOptions, config) {
+  if (outputOptions?.dir) return path.resolve(outputOptions.dir);
+  if (outputOptions?.file) return path.dirname(path.resolve(outputOptions.file));
+  return path.resolve(config?.root || process.cwd(), config?.build?.outDir || "dist");
+}
+
+function isInside(base, target) {
+  const relative = path.relative(path.resolve(base), path.resolve(target));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function artifactPath(options) {
+  return options.path || options.bundlePath || options.outDir || options.dir || ".";
+}
+
+function artifactDir(outputOptions, config, options) {
+  const root = path.resolve(config?.root || path.dirname(outputDir(outputOptions, config)));
+  const requested = String(artifactPath(options) || ".");
+  const resolved = path.resolve(root, requested);
+  if (!path.isAbsolute(requested) && !isInside(root, resolved)) {
+    throw new Error(`Matterhorn Vite bundle path must stay inside the Vite root: ${requested}`);
+  }
+  return resolved;
+}
+
+function entrypointsFromBundle(bundle) {
+  return new Set(Object.values(bundle)
+    .filter((item) => item.type === "chunk" && item.isEntry === true)
+    .map((item) => normalizePath(item.fileName)));
+}
+
+async function walkFiles(root, current, files) {
+  const entries = await fs.readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    const file = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      await walkFiles(root, file, files);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    files.push({
+      path: normalizePath(path.relative(root, file)),
+      file
+    });
+  }
+}
+
+async function distFiles(dir, artifactRoot, manifestFile, archiveFile, entrypoints) {
+  const discovered = [];
+  const skip = new Set([normalizePath(manifestFile), normalizePath(archiveFile)]);
+  await walkFiles(dir, dir, discovered);
+  const files = [];
+  const artifactRelative = isInside(dir, artifactRoot) ? normalizePath(path.relative(dir, artifactRoot)) : "";
+  const artifactPrefix = artifactRelative ? `${artifactRelative}/` : "";
+  for (const item of discovered) {
+    if (skip.has(item.path)) continue;
+    if (artifactPrefix && item.path.startsWith(artifactPrefix)) continue;
+    const body = await fs.readFile(item.file);
+    files.push({
+      path: item.path,
+      body,
+      entrypoint: entrypoints.has(item.path),
+      type: contentType(item.path),
+      integrity: integrity(body),
+      byteLength: body.byteLength
+    });
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function manifestFromFiles(files, options) {
+  const entrypoint = options.entrypoint || files.find((file) => file.entrypoint)?.path || files.find((file) => file.path.endsWith(".js"))?.path;
+  if (!entrypoint) throw new Error("Matterhorn Vite manifest could not determine an entrypoint.");
+  if (!files.some((file) => file.path === entrypoint)) {
+    throw new Error(`Matterhorn Vite manifest entrypoint is missing from emitted files: ${entrypoint}`);
+  }
+  if (!files.some((file) => file.path === DOCUMENT_ENTRYPOINT)) {
+    throw new Error(`Matterhorn Vite manifest requires ${DOCUMENT_ENTRYPOINT} in the build output.`);
+  }
+  return {
+    kind: "matterhorn.frontend.manifest",
+    version: 1,
+    entrypoint,
+    files: files.map((file) => ({
+      path: file.path,
+      type: file.type,
+      integrity: file.integrity,
+      byteLength: file.byteLength
+    })),
+    frontendChunks: frontendChunksFromFiles(files, entrypoint)
+  };
+}
+
+function rewriteDocumentEntrypoint(html, entrypoint) {
+  return html.replace(
+    /(<script\b[^>]*\btype=["']module["'][^>]*\bsrc=["'])(?:\/?\.?\/?src\/[^"']+)(["'][^>]*>\s*<\/script>)/i,
+    `$1./${entrypoint}$2`
+  );
+}
+
+async function includeRootDocument(files, config, outDir, entrypoint) {
+  if (files.some((file) => file.path === DOCUMENT_ENTRYPOINT)) return files;
+  const root = path.resolve(config?.root || process.cwd());
+  const file = path.join(root, DOCUMENT_ENTRYPOINT);
+  let body;
+  try {
+    body = Buffer.from(rewriteDocumentEntrypoint(await fs.readFile(file, "utf8"), entrypoint));
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return files;
+    throw error;
+  }
+  await fs.writeFile(path.join(outDir, DOCUMENT_ENTRYPOINT), body);
+  return [...files, {
+    path: DOCUMENT_ENTRYPOINT,
+    body,
+    entrypoint: false,
+    type: contentType(DOCUMENT_ENTRYPOINT),
+    integrity: integrity(body),
+    byteLength: body.byteLength
+  }].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function matterhorn(rawOptions = {}) {
+  const options = pluginOptions(rawOptions);
+  const manifestFile = options.manifestFile || DEFAULT_MANIFEST_FILE;
+  const archiveFile = options.archiveFile || DEFAULT_ARCHIVE_FILE;
+  let config;
+  return {
+    name: "matterhorn-frontend-bundle",
+    apply: "build",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    async writeBundle(outputOptions, bundle) {
+      const outDir = outputDir(outputOptions, config);
+      const bundleDir = artifactDir(outputOptions, config, options);
+      const emittedFiles = await distFiles(outDir, bundleDir, manifestFile, archiveFile, entrypointsFromBundle(bundle));
+      const entrypoint = options.entrypoint || emittedFiles.find((file) => file.entrypoint)?.path || emittedFiles.find((file) => file.path.endsWith(".js"))?.path;
+      const files = entrypoint ? await includeRootDocument(emittedFiles, config, outDir, entrypoint) : emittedFiles;
+      assertBundleFilesIncluded(files, bundle);
+      const manifest = manifestFromFiles(files, options);
+      const manifestBody = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+      const archive = zipStore([
+        ...files.map((file) => ({ path: file.path, body: file.body })),
+        { path: manifestFile, body: manifestBody }
+      ]);
+      const archiveMetadata = {
+        path: archiveFile,
+        delivery: "relay",
+        type: "application/zip",
+        integrity: integrity(archive),
+        byteLength: archive.byteLength
+      };
+      const finalManifest = { ...manifest, archive: archiveMetadata };
+      await fs.mkdir(bundleDir, { recursive: true });
+      await fs.writeFile(path.join(bundleDir, manifestFile), `${JSON.stringify(finalManifest, null, 2)}\n`);
+      await fs.writeFile(path.join(bundleDir, archiveFile), archive);
+    }
+  };
+}
+
+export const matterhornVitePlugin = matterhorn;