radiant-docs 0.1.60 → 0.1.62

package/template/scripts/publish-shiki-platform-assets.mjs

@@ -0,0 +1,1151 @@
+#!/usr/bin/env node
+import {
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build as esbuild } from "esbuild";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+const NODE_MODULES_DIR = path.join(FRAMEWORK_DIR, "node_modules");
+const CURRENT_ASSET_FILE = path.join(
+  FRAMEWORK_DIR,
+  "src",
+  "generated",
+  "shiki-platform-assets.json",
+);
+const LANGUAGE_DIST_DIR = path.join(
+  NODE_MODULES_DIR,
+  "@shikijs",
+  "langs",
+  "dist",
+);
+const THEME_DIST_DIR = path.join(
+  NODE_MODULES_DIR,
+  "@shikijs",
+  "themes",
+  "dist",
+);
+const DEFAULT_PLATFORM_PREFIX = "_platform/shiki";
+const DEFAULT_PROGRESS_INTERVAL = 25;
+const DEFAULT_R2_REQUEST_TIMEOUT_MS = 30_000;
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const MARKER_CACHE_CONTROL = "no-store";
+const UPLOAD_COMPLETE_MARKER = ".radiant-upload-complete.json";
+const UPLOAD_MARKER_VERSION = 1;
+
+const LICENSE_PACKAGES = [
+  "shiki",
+  "@shikijs/core",
+  "@shikijs/engine-javascript",
+  "@shikijs/langs",
+  "@shikijs/themes",
+  "@shikijs/vscode-textmate",
+  "oniguruma-to-es",
+];
+
+const RUNTIME_ENTRY_SOURCE = `
+import {
+  createHighlighterCore,
+  createHighlighterCoreSync,
+  getSingletonHighlighterCore,
+} from "@shikijs/core";
+import { createJavaScriptRegexEngine } from "@shikijs/engine-javascript";
+
+export {
+  createHighlighterCore,
+  createHighlighterCoreSync,
+  createJavaScriptRegexEngine,
+  getSingletonHighlighterCore,
+};
+
+export async function createRadiantShikiHighlighter(options = {}) {
+  const {
+    themes = [],
+    langs = [],
+    langAlias,
+    warnings = false,
+  } = options;
+
+  return createHighlighterCore({
+    themes,
+    langs,
+    langAlias,
+    warnings,
+    engine: createJavaScriptRegexEngine(),
+  });
+}
+`;
+
+function findEnvFileArg(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--env-file") {
+      const nextValue = argv[index + 1];
+      if (!nextValue || nextValue.startsWith("--")) {
+        throw new Error("Missing value for --env-file");
+      }
+      return nextValue;
+    }
+  }
+  return process.env.SHIKI_PLATFORM_ENV_FILE ?? "";
+}
+
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+
+  const normalized = trimmed.startsWith("export ")
+    ? trimmed.slice("export ".length).trim()
+    : trimmed;
+  const equalsIndex = normalized.indexOf("=");
+  if (equalsIndex === -1) return null;
+
+  const key = normalized.slice(0, equalsIndex).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return null;
+
+  let value = normalized.slice(equalsIndex + 1).trim();
+  const quote = value[0];
+  if (
+    (quote === `"` || quote === "'") &&
+    value.length >= 2 &&
+    value[value.length - 1] === quote
+  ) {
+    value = value.slice(1, -1);
+    if (quote === `"`) {
+      value = value
+        .replaceAll("\\n", "\n")
+        .replaceAll("\\r", "\r")
+        .replaceAll("\\t", "\t")
+        .replaceAll('\\"', '"')
+        .replaceAll("\\\\", "\\");
+    }
+  } else {
+    value = value.replace(/\s+#.*$/, "").trim();
+  }
+
+  return [key, value];
+}
+
+async function loadEnvFile(envFile) {
+  if (!envFile) return null;
+
+  const resolved = path.resolve(process.cwd(), envFile);
+  const contents = await fs.readFile(resolved, "utf8");
+  let loadedCount = 0;
+
+  for (const line of contents.split(/\r?\n/)) {
+    const parsed = parseEnvLine(line);
+    if (!parsed) continue;
+    const [key, value] = parsed;
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+      loadedCount += 1;
+    }
+  }
+
+  return {
+    loadedCount,
+    path: resolved,
+  };
+}
+
+function readPositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function parseArgs(argv) {
+  const args = {
+    accountId:
+      process.env.SHIKI_PLATFORM_R2_ACCOUNT_ID ??
+      process.env.R2_ACCOUNT_ID ??
+      process.env.CLOUDFLARE_ACCOUNT_ID ??
+      "",
+    accessKeyId:
+      process.env.SHIKI_PLATFORM_R2_ACCESS_KEY_ID ??
+      process.env.R2_ACCESS_KEY_ID ??
+      "",
+    assetVersion: process.env.SHIKI_PLATFORM_ASSET_VERSION ?? "",
+    bucket:
+      process.env.SHIKI_PLATFORM_R2_BUCKET_NAME ??
+      process.env.SHIKI_PLATFORM_R2_BUCKET ??
+      process.env.R2_BUCKET_NAME ??
+      "",
+    checkCurrent: false,
+    currentFile:
+      process.env.SHIKI_PLATFORM_CURRENT_FILE ?? CURRENT_ASSET_FILE,
+    dryRun: false,
+    endpoint:
+      process.env.SHIKI_PLATFORM_R2_ENDPOINT ?? process.env.R2_ENDPOINT ?? "",
+    envFile: process.env.SHIKI_PLATFORM_ENV_FILE ?? "",
+    keepOutput: false,
+    outDir: "",
+    platformPrefix:
+      process.env.SHIKI_PLATFORM_ASSET_PREFIX ?? DEFAULT_PLATFORM_PREFIX,
+    prepareOnly: false,
+    progressInterval: readPositiveInteger(
+      process.env.SHIKI_PLATFORM_UPLOAD_PROGRESS_INTERVAL,
+      DEFAULT_PROGRESS_INTERVAL,
+    ),
+    region:
+      process.env.SHIKI_PLATFORM_R2_REGION ?? process.env.R2_REGION ?? "auto",
+    requestTimeoutMs: readPositiveInteger(
+      process.env.SHIKI_PLATFORM_R2_REQUEST_TIMEOUT_MS,
+      DEFAULT_R2_REQUEST_TIMEOUT_MS,
+    ),
+    secretAccessKey:
+      process.env.SHIKI_PLATFORM_R2_SECRET_ACCESS_KEY ??
+      process.env.R2_SECRET_ACCESS_KEY ??
+      "",
+    writeCurrent: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
+    if (arg === "--check-current") {
+      args.checkCurrent = true;
+      continue;
+    }
+    if (arg === "--keep-output") {
+      args.keepOutput = true;
+      continue;
+    }
+    if (arg === "--prepare-only") {
+      args.prepareOnly = true;
+      continue;
+    }
+    if (arg === "--write-current") {
+      args.writeCurrent = true;
+      continue;
+    }
+
+    const nextValue = argv[index + 1];
+    if (!nextValue || nextValue.startsWith("--")) {
+      throw new Error(`Missing value for ${arg}`);
+    }
+    index += 1;
+
+    switch (arg) {
+      case "--access-key-id":
+        args.accessKeyId = nextValue;
+        break;
+      case "--account-id":
+        args.accountId = nextValue;
+        break;
+      case "--asset-version":
+        args.assetVersion = nextValue;
+        break;
+      case "--bucket":
+        args.bucket = nextValue;
+        break;
+      case "--current-file":
+        args.currentFile = nextValue;
+        break;
+      case "--endpoint":
+        args.endpoint = nextValue;
+        break;
+      case "--env-file":
+        args.envFile = nextValue;
+        break;
+      case "--out-dir":
+        args.outDir = nextValue;
+        break;
+      case "--prefix":
+        args.platformPrefix = nextValue;
+        break;
+      case "--progress-interval":
+        args.progressInterval = readPositiveInteger(
+          nextValue,
+          DEFAULT_PROGRESS_INTERVAL,
+        );
+        break;
+      case "--region":
+        args.region = nextValue;
+        break;
+      case "--request-timeout-ms":
+        args.requestTimeoutMs = readPositiveInteger(
+          nextValue,
+          DEFAULT_R2_REQUEST_TIMEOUT_MS,
+        );
+        break;
+      case "--secret-access-key":
+        args.secretAccessKey = nextValue;
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  if (args.checkCurrent && args.writeCurrent) {
+    throw new Error("Use either --check-current or --write-current, not both.");
+  }
+
+  return args;
+}
+
+function normalizePrefix(value) {
+  return value.trim().replace(/^\/+|\/+$/g, "");
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function joinPosix(...segments) {
+  return segments
+    .map((segment) => String(segment).trim().replace(/^\/+|\/+$/g, ""))
+    .filter(Boolean)
+    .join("/");
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJsonValue(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([firstKey], [secondKey]) => firstKey.localeCompare(secondKey))
+        .map(([key, item]) => [key, sortJsonValue(item)]),
+    );
+  }
+  return value;
+}
+
+function formatJson(value) {
+  return `${JSON.stringify(sortJsonValue(value), null, 2)}\n`;
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(sortJsonValue(value));
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readSortedMjsFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".mjs"))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function copyFileEnsuringDir(source, destination) {
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.copyFile(source, destination);
+}
+
+function hashBuffer(buffer, algorithm = "sha256") {
+  return crypto.createHash(algorithm).update(buffer).digest("hex");
+}
+
+async function listFilesRecursive(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(entryPath)));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+async function assertSafeOutputDir(outDir) {
+  const resolved = path.resolve(outDir);
+  const forbiddenDirs = new Set([
+    path.parse(resolved).root,
+    os.homedir(),
+    FRAMEWORK_DIR,
+    path.join(FRAMEWORK_DIR, "scripts"),
+    process.cwd(),
+  ]);
+
+  if (forbiddenDirs.has(resolved)) {
+    throw new Error(`Refusing to clear unsafe output directory: ${resolved}`);
+  }
+}
+
+async function resetOutputDir(outDir) {
+  await assertSafeOutputDir(outDir);
+  await fs.rm(outDir, { force: true, recursive: true });
+  await fs.mkdir(outDir, { recursive: true });
+}
+
+async function buildRuntime(outDir) {
+  const tempEntryPath = path.join(outDir, ".runtime-entry.mjs");
+  const runtimePath = path.join(outDir, "runtime.mjs");
+
+  await fs.writeFile(tempEntryPath, RUNTIME_ENTRY_SOURCE, "utf8");
+  await esbuild({
+    absWorkingDir: FRAMEWORK_DIR,
+    bundle: true,
+    entryPoints: [tempEntryPath],
+    format: "esm",
+    logLevel: "silent",
+    minify: true,
+    nodePaths: [NODE_MODULES_DIR],
+    outfile: runtimePath,
+    platform: "browser",
+    target: "es2022",
+    treeShaking: true,
+  });
+  await fs.rm(tempEntryPath, { force: true });
+}
+
+function normalizeModuleDefault(value) {
+  const moduleDefault = value?.default ?? value;
+  if (Array.isArray(moduleDefault)) return moduleDefault;
+  return moduleDefault ? [moduleDefault] : [];
+}
+
+async function buildLanguageManifestEntries(languageFileNames) {
+  const languages = {};
+  const aliasCandidates = new Map();
+
+  for (const fileName of languageFileNames) {
+    const sourcePath = path.join(LANGUAGE_DIST_DIR, fileName);
+    const moduleUrl = pathToFileURL(sourcePath).href;
+    const moduleValue = await import(moduleUrl);
+    const registrations = normalizeModuleDefault(moduleValue);
+    const fileStem = fileName.replace(/\.mjs$/, "");
+    const registrationNames = registrations
+      .map((registration) => registration?.name)
+      .filter((name) => typeof name === "string" && name.trim().length > 0);
+    const canonicalName = registrationNames[0] ?? fileStem;
+    const aliases = new Set([fileStem, canonicalName]);
+
+    for (const registration of registrations) {
+      if (typeof registration?.name === "string") {
+        aliases.add(registration.name);
+      }
+      for (const alias of registration?.aliases ?? []) {
+        aliases.add(alias);
+      }
+    }
+
+    languages[fileStem] = {
+      aliases: Array.from(aliases).sort((a, b) => a.localeCompare(b)),
+      displayName:
+        typeof registrations[0]?.displayName === "string"
+          ? registrations[0].displayName
+          : canonicalName,
+      module: `langs/${fileName}`,
+      registrations: registrationNames,
+    };
+
+    for (const alias of aliases) {
+      const normalizedAlias = String(alias).trim().toLowerCase();
+      if (!normalizedAlias) continue;
+      const candidates = aliasCandidates.get(normalizedAlias) ?? [];
+      candidates.push({
+        canonicalName,
+        fileStem,
+        registrationNames,
+      });
+      aliasCandidates.set(normalizedAlias, candidates);
+    }
+  }
+
+  const languageAliases = {};
+  for (const [alias, candidates] of aliasCandidates) {
+    const preferredCandidate =
+      candidates.find(
+        (candidate) =>
+          candidate.fileStem.toLowerCase() ===
+          candidate.canonicalName.toLowerCase(),
+      ) ??
+      candidates.find((candidate) => candidate.fileStem.toLowerCase() === alias) ??
+      candidates.find(
+        (candidate) => candidate.canonicalName.toLowerCase() === alias,
+      ) ??
+      candidates[0];
+
+    if (preferredCandidate) {
+      languageAliases[alias] = preferredCandidate.fileStem;
+    }
+  }
+
+  return {
+    languageAliases: Object.fromEntries(
+      Object.entries(languageAliases).sort(([firstKey], [secondKey]) =>
+        firstKey.localeCompare(secondKey),
+      ),
+    ),
+    languages,
+  };
+}
+
+async function buildThemeManifestEntries(themeFileNames) {
+  const themes = {};
+
+  for (const fileName of themeFileNames) {
+    const sourcePath = path.join(THEME_DIST_DIR, fileName);
+    const moduleUrl = pathToFileURL(sourcePath).href;
+    const moduleValue = await import(moduleUrl);
+    const theme = moduleValue.default ?? moduleValue;
+    const fileStem = fileName.replace(/\.mjs$/, "");
+    const themeName =
+      typeof theme?.name === "string" && theme.name.trim().length > 0
+        ? theme.name
+        : fileStem;
+
+    themes[themeName] = {
+      displayName:
+        typeof theme?.displayName === "string" ? theme.displayName : themeName,
+      module: `themes/${fileName}`,
+      type: typeof theme?.type === "string" ? theme.type : undefined,
+    };
+  }
+
+  return themes;
+}
+
+async function copyLanguageModules(outDir) {
+  const fileNames = await readSortedMjsFiles(LANGUAGE_DIST_DIR);
+  for (const fileName of fileNames) {
+    await copyFileEnsuringDir(
+      path.join(LANGUAGE_DIST_DIR, fileName),
+      path.join(outDir, "langs", fileName),
+    );
+  }
+  return fileNames;
+}
+
+async function copyThemeModules(outDir) {
+  const fileNames = await readSortedMjsFiles(THEME_DIST_DIR);
+  for (const fileName of fileNames) {
+    await copyFileEnsuringDir(
+      path.join(THEME_DIST_DIR, fileName),
+      path.join(outDir, "themes", fileName),
+    );
+  }
+  return fileNames;
+}
+
+function licenseDestinationName(packageName, licensePath) {
+  const extension = path.extname(licensePath) || ".txt";
+  return `${packageName.replaceAll("/", "__")}${extension}`;
+}
+
+async function copyLicenses(outDir) {
+  const copiedLicenses = [];
+
+  for (const packageName of LICENSE_PACKAGES) {
+    const packageDir = path.join(NODE_MODULES_DIR, packageName);
+    const entries = await fs.readdir(packageDir, { withFileTypes: true });
+    const licenseEntry = entries.find(
+      (entry) => entry.isFile() && /^license(?:\..*)?$/i.test(entry.name),
+    );
+    if (!licenseEntry) continue;
+
+    const sourcePath = path.join(packageDir, licenseEntry.name);
+    const destinationName = licenseDestinationName(
+      packageName,
+      licenseEntry.name,
+    );
+    await copyFileEnsuringDir(
+      sourcePath,
+      path.join(outDir, "licenses", destinationName),
+    );
+    copiedLicenses.push({
+      module: `licenses/${destinationName}`,
+      package: packageName,
+    });
+  }
+
+  return copiedLicenses.sort((a, b) => a.package.localeCompare(b.package));
+}
+
+async function buildFileManifest(outDir) {
+  const absoluteFiles = await listFilesRecursive(outDir);
+  const files = {};
+
+  for (const absolutePath of absoluteFiles) {
+    const relativePath = toPosixPath(path.relative(outDir, absolutePath));
+    if (relativePath === "manifest.json") continue;
+
+    const buffer = await fs.readFile(absolutePath);
+    files[relativePath] = {
+      bytes: buffer.byteLength,
+      sha256: hashBuffer(buffer),
+    };
+  }
+
+  return Object.fromEntries(
+    Object.entries(files).sort(([firstKey], [secondKey]) =>
+      firstKey.localeCompare(secondKey),
+    ),
+  );
+}
+
+function buildAssetFingerprint(manifestBase) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(manifestBase))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function buildCurrentAssetDescriptor({
+  manifest,
+  manifestBytes,
+  manifestSha256,
+  platformPrefix,
+}) {
+  return {
+    assetVersion: manifest.assetVersion,
+    counts: {
+      languages: Object.keys(manifest.languages).length,
+      themes: Object.keys(manifest.themes).length,
+    },
+    manifest: {
+      bytes: manifestBytes,
+      module: "manifest.json",
+      sha256: manifestSha256,
+    },
+    packageVersions: manifest.packageVersions,
+    prefix: platformPrefix,
+    runtime: manifest.runtime,
+  };
+}
+
+async function writeCurrentAssetFile(filePath, descriptor) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, formatJson(descriptor), "utf8");
+}
+
+function describeCurrentDescriptor(descriptor) {
+  const packageVersions = Object.entries(descriptor.packageVersions)
+    .map(([name, version]) => `${name}@${version}`)
+    .join(", ");
+
+  return [
+    `assetVersion=${descriptor.assetVersion}`,
+    `prefix=${descriptor.prefix}`,
+    `packages=${packageVersions}`,
+    `manifestSha256=${descriptor.manifest.sha256}`,
+  ].join("; ");
+}
+
+async function checkCurrentAssetFile(filePath, descriptor) {
+  if (!(await pathExists(filePath))) {
+    throw new Error(
+      `Current Shiki platform asset file is missing: ${filePath}\n` +
+        "Run: npm --prefix framework run shiki:publish-platform-assets -- --prepare-only --write-current",
+    );
+  }
+
+  const current = await readJson(filePath);
+  if (canonicalJson(current) === canonicalJson(descriptor)) {
+    return;
+  }
+
+  throw new Error(
+    `Current Shiki platform asset file is out of date: ${filePath}\n` +
+      `Expected: ${describeCurrentDescriptor(descriptor)}\n` +
+      `Found: ${describeCurrentDescriptor(current)}\n` +
+      "Run: npm --prefix framework run shiki:publish-platform-assets -- --prepare-only --write-current",
+  );
+}
+
+async function prepareAssets({ assetVersionOverride, outDir }) {
+  await resetOutputDir(outDir);
+
+  const shikiPackage = await readJson(
+    path.join(NODE_MODULES_DIR, "shiki", "package.json"),
+  );
+  const corePackage = await readJson(
+    path.join(NODE_MODULES_DIR, "@shikijs", "core", "package.json"),
+  );
+  const enginePackage = await readJson(
+    path.join(
+      NODE_MODULES_DIR,
+      "@shikijs",
+      "engine-javascript",
+      "package.json",
+    ),
+  );
+  const languagePackage = await readJson(
+    path.join(NODE_MODULES_DIR, "@shikijs", "langs", "package.json"),
+  );
+  const themePackage = await readJson(
+    path.join(NODE_MODULES_DIR, "@shikijs", "themes", "package.json"),
+  );
+
+  await buildRuntime(outDir);
+  const languageFileNames = await copyLanguageModules(outDir);
+  const themeFileNames = await copyThemeModules(outDir);
+  const licenses = await copyLicenses(outDir);
+  const files = await buildFileManifest(outDir);
+  const languageManifest = await buildLanguageManifestEntries(languageFileNames);
+  const themes = await buildThemeManifestEntries(themeFileNames);
+  const manifestBase = {
+    files,
+    languageAliases: languageManifest.languageAliases,
+    languages: languageManifest.languages,
+    licenses,
+    packageVersions: {
+      "@shikijs/core": corePackage.version,
+      "@shikijs/engine-javascript": enginePackage.version,
+      "@shikijs/langs": languagePackage.version,
+      "@shikijs/themes": themePackage.version,
+      shiki: shikiPackage.version,
+    },
+    runtime: {
+      engine: "javascript-regexp",
+      module: "runtime.mjs",
+    },
+    themes,
+  };
+  const fingerprint = buildAssetFingerprint(manifestBase);
+  const assetVersion =
+    assetVersionOverride.trim() ||
+    `shiki-${shikiPackage.version}-${fingerprint}`;
+  const manifest = {
+    assetVersion,
+    ...manifestBase,
+  };
+  const manifestJson = `${JSON.stringify(manifest, null, 2)}\n`;
+  const manifestBuffer = Buffer.from(manifestJson);
+
+  await fs.writeFile(
+    path.join(outDir, "manifest.json"),
+    manifestJson,
+    "utf8",
+  );
+
+  return {
+    assetVersion,
+    files: await buildFileManifest(outDir),
+    languageCount: languageFileNames.length,
+    manifest,
+    manifestBytes: manifestBuffer.byteLength,
+    manifestSha256: hashBuffer(manifestBuffer),
+    outDir,
+    shikiVersion: shikiPackage.version,
+    themeCount: themeFileNames.length,
+    uploadFileCount: (await listFilesRecursive(outDir)).length,
+  };
+}
+
+function getContentType(relativePath) {
+  if (relativePath.endsWith(".mjs")) return "text/javascript; charset=utf-8";
+  if (relativePath.endsWith(".json")) return "application/json; charset=utf-8";
+  if (relativePath.endsWith(".md")) return "text/markdown; charset=utf-8";
+  return "text/plain; charset=utf-8";
+}
+
+function createR2Client(args) {
+  const endpoint =
+    args.endpoint ||
+    (args.accountId
+      ? `https://${args.accountId}.r2.cloudflarestorage.com`
+      : "");
+  if (!endpoint) {
+    throw new Error("Missing R2 endpoint. Set R2_ACCOUNT_ID or R2_ENDPOINT.");
+  }
+  if (!args.accessKeyId || !args.secretAccessKey) {
+    throw new Error(
+      "Missing R2 credentials. Set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.",
+    );
+  }
+
+  return new S3Client({
+    credentials: {
+      accessKeyId: args.accessKeyId,
+      secretAccessKey: args.secretAccessKey,
+    },
+    endpoint,
+    maxAttempts: 2,
+    region: args.region,
+  });
+}
+
+async function sendR2CommandWithTimeout(s3, command, { label, timeoutMs }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    return await s3.send(command, {
+      abortSignal: controller.signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error(`Timed out after ${timeoutMs}ms while ${label}.`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function objectHasSameHash(s3, bucket, key, sha256, requestTimeoutMs) {
+  try {
+    const response = await sendR2CommandWithTimeout(
+      s3,
+      new HeadObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      }),
+      {
+        label: `checking ${bucket}/${key}`,
+        timeoutMs: requestTimeoutMs,
+      },
+    );
+    return response.Metadata?.["radiant-sha256"] === sha256;
+  } catch (error) {
+    const statusCode = error?.$metadata?.httpStatusCode;
+    if (statusCode === 403 || statusCode === 404) return false;
+    throw error;
+  }
+}
+
+async function completionMarkerMatches({
+  assetVersion,
+  bucket,
+  fileCount,
+  key,
+  manifestSha256,
+  requestTimeoutMs,
+  s3,
+}) {
+  try {
+    const response = await sendR2CommandWithTimeout(
+      s3,
+      new HeadObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      }),
+      {
+        label: `checking completion marker ${bucket}/${key}`,
+        timeoutMs: requestTimeoutMs,
+      },
+    );
+    const metadata = response.Metadata ?? {};
+
+    return (
+      metadata["radiant-shiki-asset-version"] === assetVersion &&
+      metadata["radiant-shiki-file-count"] === String(fileCount) &&
+      metadata["radiant-shiki-manifest-sha256"] === manifestSha256 &&
+      metadata["radiant-shiki-marker-version"] ===
+        String(UPLOAD_MARKER_VERSION)
+    );
+  } catch (error) {
+    const statusCode = error?.$metadata?.httpStatusCode;
+    if (statusCode === 403 || statusCode === 404) return false;
+    throw error;
+  }
+}
+
+function buildCompletionMarker({
+  assetVersion,
+  fileCount,
+  manifestBytes,
+  manifestSha256,
+  uploadPrefix,
+}) {
+  return {
+    assetVersion,
+    completedAt: new Date().toISOString(),
+    fileCount,
+    manifest: {
+      bytes: manifestBytes,
+      module: "manifest.json",
+      sha256: manifestSha256,
+    },
+    markerVersion: UPLOAD_MARKER_VERSION,
+    prefix: uploadPrefix,
+  };
+}
+
+async function uploadCompletionMarker({
+  assetVersion,
+  bucket,
+  fileCount,
+  key,
+  manifestBytes,
+  manifestSha256,
+  requestTimeoutMs,
+  s3,
+  uploadPrefix,
+}) {
+  const marker = buildCompletionMarker({
+    assetVersion,
+    fileCount,
+    manifestBytes,
+    manifestSha256,
+    uploadPrefix,
+  });
+  const body = Buffer.from(formatJson(marker));
+
+  await sendR2CommandWithTimeout(
+    s3,
+    new PutObjectCommand({
+      Body: body,
+      Bucket: bucket,
+      CacheControl: MARKER_CACHE_CONTROL,
+      ContentType: "application/json; charset=utf-8",
+      Key: key,
+      Metadata: {
+        "radiant-sha256": hashBuffer(body),
+        "radiant-shiki-asset-version": assetVersion,
+        "radiant-shiki-file-count": String(fileCount),
+        "radiant-shiki-manifest-sha256": manifestSha256,
+        "radiant-shiki-marker-version": String(UPLOAD_MARKER_VERSION),
+      },
+    }),
+    {
+      label: `uploading completion marker ${bucket}/${key}`,
+      timeoutMs: requestTimeoutMs,
+    },
+  );
+}
+
+async function uploadAssets({
+  args,
+  assetVersion,
+  fileCount,
+  manifestBytes,
+  manifestSha256,
+  outDir,
+}) {
+  if (!args.bucket) {
+    throw new Error("Missing R2 bucket. Set R2_BUCKET_NAME or pass --bucket.");
+  }
+
+  const s3 = createR2Client(args);
+  try {
+    const absoluteFiles = await listFilesRecursive(outDir);
+    const platformPrefix = normalizePrefix(args.platformPrefix);
+    const uploadPrefix = joinPosix(platformPrefix, assetVersion);
+    const markerKey = joinPosix(uploadPrefix, UPLOAD_COMPLETE_MARKER);
+    const stats = {
+      checked: 0,
+      marker: "missing",
+      uploaded: 0,
+      skipped: 0,
+    };
+    const total = fileCount;
+
+    if (
+      await completionMarkerMatches({
+        assetVersion,
+        bucket: args.bucket,
+        fileCount,
+        key: markerKey,
+        manifestSha256,
+        requestTimeoutMs: args.requestTimeoutMs,
+        s3,
+      })
+    ) {
+      console.log(
+        `Completion marker matches; skipping ${total} asset checks for ${args.bucket}/${uploadPrefix}`,
+      );
+
+      return {
+        ...stats,
+        marker: "matched",
+        prefix: uploadPrefix,
+        skipped: total,
+      };
+    }
+
+    console.log(`Checking/uploading ${total} files to ${args.bucket}/${uploadPrefix}`);
+
+    for (const absolutePath of absoluteFiles) {
+      const relativePath = toPosixPath(path.relative(outDir, absolutePath));
+      const body = await fs.readFile(absolutePath);
+      const sha256 = hashBuffer(body);
+      const key = joinPosix(uploadPrefix, relativePath);
+      const shouldSkip = await objectHasSameHash(
+        s3,
+        args.bucket,
+        key,
+        sha256,
+        args.requestTimeoutMs,
+      );
+      stats.checked += 1;
+
+      if (shouldSkip) {
+        stats.skipped += 1;
+        if (
+          stats.checked % args.progressInterval === 0 ||
+          stats.checked === total
+        ) {
+          console.log(
+            `Progress: ${stats.checked}/${total}; uploaded: ${stats.uploaded}; skipped: ${stats.skipped}`,
+          );
+        }
+        continue;
+      }
+
+      await sendR2CommandWithTimeout(
+        s3,
+        new PutObjectCommand({
+          Body: body,
+          Bucket: args.bucket,
+          CacheControl: IMMUTABLE_CACHE_CONTROL,
+          ContentType: getContentType(relativePath),
+          Key: key,
+          Metadata: {
+            "radiant-sha256": sha256,
+            "radiant-shiki-asset-version": assetVersion,
+          },
+        }),
+        {
+          label: `uploading ${args.bucket}/${key}`,
+          timeoutMs: args.requestTimeoutMs,
+        },
+      );
+      stats.uploaded += 1;
+      if (
+        stats.checked % args.progressInterval === 0 ||
+        stats.checked === total
+      ) {
+        console.log(
+          `Progress: ${stats.checked}/${total}; uploaded: ${stats.uploaded}; skipped: ${stats.skipped}`,
+        );
+      }
+    }
+
+    await uploadCompletionMarker({
+      assetVersion,
+      bucket: args.bucket,
+      fileCount,
+      key: markerKey,
+      manifestBytes,
+      manifestSha256,
+      requestTimeoutMs: args.requestTimeoutMs,
+      s3,
+      uploadPrefix,
+    });
+    stats.marker = "uploaded";
+
+    return {
+      ...stats,
+      prefix: uploadPrefix,
+    };
+  } finally {
+    s3.destroy();
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const loadedEnvFile = await loadEnvFile(findEnvFileArg(argv));
+  if (loadedEnvFile) {
+    console.log(
+      `Loaded ${loadedEnvFile.loadedCount} environment variables from ${loadedEnvFile.path}`,
+    );
+  }
+
+  const args = parseArgs(argv);
+  const outDir = path.resolve(
+    args.outDir ||
+      path.join(
+        os.tmpdir(),
+        `radiant-shiki-platform-assets-${process.pid}-${Date.now()}`,
+      ),
+  );
+
+  const prepared = await prepareAssets({
+    assetVersionOverride: args.assetVersion,
+    outDir,
+  });
+  const platformPrefix = normalizePrefix(args.platformPrefix);
+  const uploadPrefix = joinPosix(platformPrefix, prepared.assetVersion);
+  const currentDescriptor = buildCurrentAssetDescriptor({
+    manifest: prepared.manifest,
+    manifestBytes: prepared.manifestBytes,
+    manifestSha256: prepared.manifestSha256,
+    platformPrefix,
+  });
+
+  console.log(
+    `Prepared Shiki platform assets ${prepared.assetVersion} in ${prepared.outDir}`,
+  );
+  console.log(
+    `Runtime: runtime.mjs; languages: ${prepared.languageCount}; themes: ${prepared.themeCount}`,
+  );
+
+  if (args.writeCurrent) {
+    await writeCurrentAssetFile(path.resolve(args.currentFile), currentDescriptor);
+    console.log(
+      `Wrote current Shiki platform asset file to ${path.resolve(args.currentFile)}`,
+    );
+  }
+
+  if (args.checkCurrent) {
+    await checkCurrentAssetFile(path.resolve(args.currentFile), currentDescriptor);
+    console.log("Current Shiki platform asset file is up to date.");
+  }
+
+  if (args.prepareOnly) {
+    console.log("Prepare-only mode; no upload attempted.");
+    return;
+  }
+
+  if (args.dryRun) {
+    console.log(
+      `Dry run; would upload/check ${prepared.uploadFileCount} asset files plus completion marker at ${args.bucket || "<bucket>"}/${uploadPrefix}`,
+    );
+    if (!args.keepOutput && !args.outDir && (await pathExists(outDir))) {
+      await fs.rm(outDir, { force: true, recursive: true });
+    }
+    return;
+  }
+
+  const uploadStats = await uploadAssets({
+    args,
+    assetVersion: prepared.assetVersion,
+    fileCount: prepared.uploadFileCount,
+    manifestBytes: prepared.manifestBytes,
+    manifestSha256: prepared.manifestSha256,
+    outDir,
+  });
+
+  console.log(
+    `Uploaded Shiki platform assets to ${args.bucket}/${uploadStats.prefix}`,
+  );
+  console.log(
+    `Uploaded: ${uploadStats.uploaded}; skipped: ${uploadStats.skipped}; marker: ${uploadStats.marker}`,
+  );
+
+  if (!args.keepOutput && !args.outDir && (await pathExists(outDir))) {
+    await fs.rm(outDir, { force: true, recursive: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});