feat(packaging): bundle vendored runtime readmes

Author: newbe36524

packages/code-server/scripts/build-artifacts.mjs

@@ -19,10 +19,12 @@ const packageId = "code-server"
 const platform = normalizePlatform(process.env.BUILD_ARTIFACTS_PLATFORM || process.platform)
 const arch = normalizeArch(process.env.ARCH || process.arch)
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.stack || error.message : String(error))
-  process.exitCode = 1
-})
+if (isMainModule()) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.stack || error.message : String(error))
+    process.exitCode = 1
+  })
+}
 
 async function main() {
   process.chdir(root)
@@ -31,15 +33,17 @@ async function main() {
   const version = await resolveVersion()
 
   await run("git", ["submodule", "update", "--init", "--recursive"], { cwd: root })
+  const sourceRevision = (await readGitOutput(["rev-parse", "HEAD"], codeServerRoot)).trim()
 
   await rm(artifactsDir, { recursive: true, force: true })
   await mkdir(artifactsDir, { recursive: true })
 
   await runBuildPipeline(version)
   await slimRelease()
+  await writePackagedReadme(releaseDir, { version, sourceRevision, targetPlatform: platform, targetArch: arch })
 
   const artifacts = await collectArtifacts(version)
-  await writeMetadata(version, artifacts)
+  await writeMetadata(version, sourceRevision, artifacts)
 }
 
 async function runBuildPipeline(version) {
@@ -195,8 +199,77 @@ async function collectArtifacts(version) {
   ]
 }
 
-async function writeMetadata(version, artifacts) {
-  const revision = await readGitOutput(["rev-parse", "HEAD"], codeServerRoot)
+export async function writePackagedReadme(releaseRoot, details) {
+  const readmePath = path.join(releaseRoot, "README.md")
+  const upstreamReadmePath = path.join(releaseRoot, "README.upstream.md")
+
+  if ((await exists(readmePath)) && !(await exists(upstreamReadmePath))) {
+    await writeFile(upstreamReadmePath, await readFile(readmePath, "utf8"))
+  }
+
+  await writeFile(readmePath, renderPackagedReadme(details))
+}
+
+export function renderPackagedReadme({ version, sourceRevision, targetPlatform = platform, targetArch = arch }) {
+  const usageBlock =
+    targetPlatform === "windows"
+      ? [
+          "```powershell",
+          ".\\bin\\code-server.cmd --help",
+          ".\\bin\\code-server.cmd --bind-addr 0.0.0.0:8080 .",
+          "```",
+          "",
+          "Direct Node entrypoint:",
+          "",
+          "```powershell",
+          "node .\\out\\node\\entry.js --help",
+          "```",
+        ].join("\n")
+      : [
+          "```bash",
+          "./bin/code-server --help",
+          "./bin/code-server --bind-addr 0.0.0.0:8080 .",
+          "```",
+          "",
+          "Direct Node entrypoint:",
+          "",
+          "```bash",
+          "node ./out/node/entry.js --help",
+          "```",
+        ].join("\n")
+
+  return [
+    "# code-server",
+    "",
+    "This archive is the HagiCode vendored slim build of code-server. Extract it and run it directly.",
+    "",
+    "## Usage",
+    "",
+    "1. Extract the archive and change into the extracted directory.",
+    "2. Start code-server with the wrapper below.",
+    "",
+    usageBlock,
+    "",
+    "## Dependencies",
+    "",
+    "- Node.js 22 must be available on PATH. This archive does not bundle a Node runtime.",
+    "- A modern web browser is required to use the UI after the server starts.",
+    "",
+    "## Version",
+    "",
+    `- Package: \`${packageId}\``,
+    `- Packaged version: \`${version}\``,
+    `- Target: \`${targetPlatform}/${targetArch}\``,
+    `- Source revision: \`${sourceRevision}\``,
+    "",
+    "## Notes",
+    "",
+    "- The original upstream README is preserved as `README.upstream.md` when it exists in the release tree.",
+    "",
+  ].join("\n")
+}
+
+async function writeMetadata(version, sourceRevision, artifacts) {
   const metadataFileName = "metadata.json"
   await writeFile(
     path.join(artifactsDir, metadataFileName),
@@ -207,7 +280,7 @@ async function writeMetadata(version, artifacts) {
         version,
         platform,
         arch,
-        sourceRevision: revision.trim(),
+        sourceRevision,
         extra: {
           slimArtifact: true,
           bundledNodeRuntime: false,
@@ -282,6 +355,15 @@ function normalizeArch(value) {
   }
 }
 
+async function exists(targetPath) {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
 function toPosixPath(value) {
   return value.replaceAll("\\", "/")
 }
@@ -375,3 +457,7 @@ async function calculateSha256(filePath) {
   const contents = await readFile(filePath)
   return createHash("sha256").update(contents).digest("hex")
 }
+
+function isMainModule() {
+  return process.argv[1] != null && path.resolve(process.argv[1]) === __filename
+}

packages/code-server/scripts/build-artifacts.test.mjs

@@ -0,0 +1,38 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+import { mkdtemp, readFile, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+import { renderPackagedReadme, writePackagedReadme } from "./build-artifacts.mjs"
+
+test("renderPackagedReadme emits code-server usage, dependency, and version details", () => {
+  const readme = renderPackagedReadme({
+    version: "4.99.0",
+    sourceRevision: "abc123",
+    targetPlatform: "windows",
+    targetArch: "amd64",
+  })
+
+  assert.match(readme, /\.\\bin\\code-server\.cmd --help/)
+  assert.match(readme, /Node\.js 22 must be available on PATH/)
+  assert.match(readme, /Packaged version: `4\.99\.0`/)
+  assert.match(readme, /Source revision: `abc123`/)
+})
+
+test("writePackagedReadme preserves the upstream README before overwriting it", async () => {
+  const releaseRoot = await mkdtemp(path.join(os.tmpdir(), "code-server-readme-"))
+  await writeFile(path.join(releaseRoot, "README.md"), "upstream docs\n")
+
+  await writePackagedReadme(releaseRoot, {
+    version: "4.99.0",
+    sourceRevision: "abc123",
+    targetPlatform: "linux",
+    targetArch: "amd64",
+  })
+
+  assert.equal(await readFile(path.join(releaseRoot, "README.upstream.md"), "utf8"), "upstream docs\n")
+  const packagedReadme = await readFile(path.join(releaseRoot, "README.md"), "utf8")
+  assert.match(packagedReadme, /# code-server/)
+  assert.match(packagedReadme, /\.\/bin\/code-server --help/)
+})

packages/omniroute/scripts/build-artifacts.mjs

@@ -36,6 +36,7 @@ async function main() {
   const version = process.env.VERSION || upstreamVersion
 
   await run("git", ["submodule", "update", "--init", "--recursive"], { cwd: root })
+  const sourceRevision = (await readGitOutput(["rev-parse", "HEAD"], upstreamRoot)).trim()
   await rm(artifactsDir, { recursive: true, force: true })
   await rm(releaseWorkspace, { recursive: true, force: true })
   await mkdir(artifactsDir, { recursive: true })
@@ -61,12 +62,12 @@ async function main() {
     env: withBuildEnv(process.env, version),
   })
 
-  const releaseRoot = await stageReleaseTree(version)
+  const releaseRoot = await stageReleaseTree({ version, upstreamVersion, sourceRevision })
   const artifacts = await createArchive(version, releaseRoot)
-  await writeMetadata(version, upstreamVersion, artifacts)
+  await writeMetadata(version, upstreamVersion, sourceRevision, artifacts)
 }
 
-async function stageReleaseTree(version) {
+async function stageReleaseTree({ version, upstreamVersion, sourceRevision }) {
   const releaseRoot = path.join(releaseWorkspace, `${packageId}-${version}-${platform}-${arch}`)
   await rm(releaseRoot, { recursive: true, force: true })
   await mkdir(releaseRoot, { recursive: true })
@@ -98,6 +99,7 @@ async function stageReleaseTree(version) {
   await access(path.join(releaseRoot, "app", "server.js"))
   await assertPackagedEntrypoints(releaseRoot, binEntries)
   await writePlatformWrappers(releaseRoot, binEntries, platform)
+  await writePackagedReadme(releaseRoot, { version, upstreamVersion, sourceRevision, targetPlatform: platform, targetArch: arch })
 
   return releaseRoot
 }
@@ -141,12 +143,11 @@ async function createArchive(version, releaseRoot) {
   ]
 }
 
-async function writeMetadata(version, upstreamVersion, artifacts) {
-  const revision = (await readGitOutput(["rev-parse", "HEAD"], upstreamRoot)).trim()
+async function writeMetadata(version, upstreamVersion, sourceRevision, artifacts) {
   const metadataFileName = "metadata.json"
   await writeFile(
     path.join(artifactsDir, metadataFileName),
-    `${JSON.stringify(createMetadataPayload({ version, upstreamVersion, sourceRevision: revision, artifacts }), null, 2)}\n`,
+    `${JSON.stringify(createMetadataPayload({ version, upstreamVersion, sourceRevision, artifacts }), null, 2)}\n`,
   )
 }
 
@@ -182,6 +183,82 @@ export function createMetadataPayload({ version, upstreamVersion, sourceRevision
   }
 }
 
+export async function writePackagedReadme(releaseRoot, details) {
+  const readmePath = path.join(releaseRoot, "README.md")
+  const upstreamReadmePath = path.join(releaseRoot, "README.upstream.md")
+
+  if ((await exists(readmePath)) && !(await exists(upstreamReadmePath))) {
+    await writeFile(upstreamReadmePath, await readFile(readmePath, "utf8"))
+  }
+
+  await writeFile(readmePath, renderPackagedReadme(details))
+}
+
+export function renderPackagedReadme({ version, upstreamVersion, sourceRevision, targetPlatform = platform, targetArch = arch }) {
+  const usageBlock =
+    targetPlatform === "windows"
+      ? [
+          "```powershell",
+          ".\\omniroute.cmd --help",
+          ".\\omniroute.cmd",
+          ".\\omniroute-reset-password.cmd",
+          "```",
+          "",
+          "Direct Node entrypoint:",
+          "",
+          "```powershell",
+          "node .\\bin\\omniroute.mjs --help",
+          "```",
+        ].join("\n")
+      : [
+          "```bash",
+          "./omniroute.sh --help",
+          "./omniroute.sh",
+          "./omniroute-reset-password.sh",
+          "```",
+          "",
+          "Direct Node entrypoint:",
+          "",
+          "```bash",
+          "node ./bin/omniroute.mjs --help",
+          "```",
+        ].join("\n")
+
+  return [
+    "# omniroute",
+    "",
+    "This archive is the HagiCode vendored standalone OmniRoute bundle. Extract it and run it directly.",
+    "",
+    "## Usage",
+    "",
+    "1. Extract the archive and change into the extracted directory.",
+    "2. If you need provider credentials or other runtime settings, start from `.env.example`.",
+    "3. Start OmniRoute with the wrapper below.",
+    "",
+    usageBlock,
+    "",
+    "## Dependencies",
+    "",
+    "- Run this vendored build with Node.js 22. The archive includes `.node-version` with `22`.",
+    "- No Node runtime is bundled. The wrapper scripts call `node` from PATH.",
+    "- Provider credentials, network access, and any route-specific configuration remain external dependencies.",
+    "",
+    "## Version",
+    "",
+    `- Package: \`${packageId}\``,
+    `- Packaged version: \`${version}\``,
+    `- Upstream version: \`${upstreamVersion}\``,
+    `- Target: \`${targetPlatform}/${targetArch}\``,
+    `- Source revision: \`${sourceRevision}\``,
+    "",
+    "## Notes",
+    "",
+    "- Packaged CLI entrypoint: `bin/omniroute.mjs`",
+    "- The original upstream README is preserved as `README.upstream.md` when it exists in the release tree.",
+    "",
+  ].join("\n")
+}
+
 async function readUpstreamVersion() {
   const packageJson = JSON.parse(await readFile(path.join(upstreamRoot, "package.json"), "utf8"))
   return packageJson.version

packages/omniroute/scripts/build-artifacts.test.mjs

@@ -1,10 +1,10 @@
 import test from "node:test"
 import assert from "node:assert/strict"
-import { access, mkdtemp, readFile, stat } from "node:fs/promises"
+import { access, mkdtemp, readFile, stat, writeFile } from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 
-import { createMetadataPayload, patchPrepublishScriptSource, patchResponsesWsProxySource, writePlatformWrappers } from "./build-artifacts.mjs"
+import { createMetadataPayload, patchPrepublishScriptSource, patchResponsesWsProxySource, renderPackagedReadme, writePackagedReadme, writePlatformWrappers } from "./build-artifacts.mjs"
 import { buildBlobKey } from "../../../scripts/publication.mjs"
 import { WINDOWS_WRAPPER_EXTENSIONS, getManifestBinEntries, getNativeSmokeWrapperFile, getWrapperDefinitions } from "./wrappers.mjs"
 
@@ -203,3 +203,37 @@ export function createResponsesWsProxy({
   assert.equal(patched.includes('const module = requireFn("wreq-js");'), true)
   assert.equal(patched.includes('wsFactory = loadDefaultWsFactory(),'), true)
 })
+
+
+test("renderPackagedReadme emits OmniRoute usage, dependency, and version details", () => {
+  const readme = renderPackagedReadme({
+    version: "2026.0505.0001",
+    upstreamVersion: "3.7.9",
+    sourceRevision: "abc123",
+    targetPlatform: "windows",
+    targetArch: "amd64",
+  })
+
+  assert.match(readme, /\.\\omniroute\.cmd --help/)
+  assert.match(readme, /\.node-version/)
+  assert.match(readme, /Upstream version: `3\.7\.9`/)
+  assert.match(readme, /Packaged CLI entrypoint: `bin\/omniroute\.mjs`/)
+})
+
+test("writePackagedReadme preserves the upstream OmniRoute README before overwriting it", async () => {
+  const releaseRoot = await mkdtemp(path.join(os.tmpdir(), "omniroute-readme-"))
+  await writeFile(path.join(releaseRoot, "README.md"), "upstream docs\n")
+
+  await writePackagedReadme(releaseRoot, {
+    version: "2026.0505.0001",
+    upstreamVersion: "3.7.9",
+    sourceRevision: "abc123",
+    targetPlatform: "linux",
+    targetArch: "amd64",
+  })
+
+  assert.equal(await readFile(path.join(releaseRoot, "README.upstream.md"), "utf8"), "upstream docs\n")
+  const packagedReadme = await readFile(path.join(releaseRoot, "README.md"), "utf8")
+  assert.match(packagedReadme, /# omniroute/)
+  assert.match(packagedReadme, /\.\/omniroute\.sh --help/)
+})