chore(docs): add versioned documentation with auto-detection

Close #675

Author: Killusions

.github/scripts/merge-versions.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * Merge versions.json for documentation deployment
+ *
+ * This script merges existing versions from S3 with newly deployed versions,
+ * ensuring the version selector shows all available documentation versions.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+
+const VERSIONS_ORDER = {
+  latest: 0,
+  preview: 1
+};
+
+/**
+ * Parse version number for sorting (e.g., "v2" -> 2)
+ */
+function parseVersionNumber(version) {
+  const match = version.match(/^v(\d+)/);
+  return match ? parseInt(match[1], 10) : 999;
+}
+
+/**
+ * Sort versions in the correct order:
+ * 1. latest
+ * 2. preview
+ * 3. v2, v1 (descending)
+ */
+function sortVersions(versions) {
+  return versions.sort((a, b) => {
+    const orderA = VERSIONS_ORDER[a.version] ?? 1000 + parseVersionNumber(a.version);
+    const orderB = VERSIONS_ORDER[b.version] ?? 1000 + parseVersionNumber(b.version);
+
+    // For version numbers, sort descending (higher versions first)
+    if (orderA >= 1000 && orderB >= 1000) {
+      return orderB - orderA;
+    }
+
+    return orderA - orderB;
+  });
+}
+
+/**
+ * Merge existing and new versions, removing duplicates
+ */
+function mergeVersions(existingVersions, newVersions) {
+  const versionMap = new Map();
+
+  // Add existing versions
+  for (const version of existingVersions) {
+    versionMap.set(version.version, version);
+  }
+
+  // Add/update with new versions
+  for (const version of newVersions) {
+    versionMap.set(version.version, version);
+  }
+
+  const merged = Array.from(versionMap.values());
+  return sortVersions(merged);
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length !== 3) {
+    console.error(
+      'Usage: merge-versions.mjs <existing-versions-file> <new-versions-file> <output-file>'
+    );
+    process.exit(1);
+  }
+
+  const [existingFile, newFile, outputFile] = args;
+
+  // Read existing versions
+  let existingVersions = [];
+  try {
+    const content = readFileSync(existingFile, 'utf-8');
+    existingVersions = JSON.parse(content);
+    console.log(`Loaded ${existingVersions.length} existing versions`);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.log('No existing versions file found, starting fresh');
+    } else {
+      console.error('Error reading existing versions:', error.message);
+      process.exit(1);
+    }
+  }
+
+  // Read new versions
+  let newVersions = [];
+  try {
+    const content = readFileSync(newFile, 'utf-8');
+    newVersions = JSON.parse(content);
+    console.log(`Loaded ${newVersions.length} new versions to deploy`);
+  } catch (error) {
+    console.error('Error reading new versions:', error.message);
+    process.exit(1);
+  }
+
+  // Merge and sort
+  const mergedVersions = mergeVersions(existingVersions, newVersions);
+  console.log(`Merged result: ${mergedVersions.length} total versions`);
+  console.log('Version order:', mergedVersions.map(v => v.version).join(', '));
+
+  // Write output
+  try {
+    writeFileSync(outputFile, JSON.stringify(mergedVersions, null, 2));
+    console.log(`Successfully wrote merged versions to ${outputFile}`);
+  } catch (error) {
+    console.error('Error writing output:', error.message);
+    process.exit(1);
+  }
+}
+
+main();