The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(server): stamp the real build version into images instead of the package.json placeholder (#10257)
Devin Foleyd1b9448b57a8
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.ymlindex 1cf0640c62..66c505e3f8 100644--- a/.github/workflows/docker.yml+++ b/.github/workflows/docker.yml@@ -21,6 +21,24 @@ jobs:steps:- name: Checkoutuses: actions/checkout@v7+ with:+ # Full history and tags so `git describe` below can compute the+ # release version to stamp into the image.+ fetch-depth: 0++ # `.git` is dockerignored, so a running image cannot derive its own+ # version and otherwise reports the source package.json placeholder in+ # analytics and the debug panel. Compute it here from the pristine+ # checkout (real CalVer drift from the nearest release tag) and pass it+ # into both builds. Empty when no release tag is reachable — the server+ # then keeps its existing fallbacks.+ - name: Compute build version+ id: build-version+ run: |+ set -euo pipefail+ version="$(git describe --tags --match 'v*' --long --dirty 2>/dev/null || true)"+ echo "version=${version}" >> "$GITHUB_OUTPUT"+ echo "Stamping build version: ${version:-<none>}"- name: Setup pnpmuses: pnpm/action-setup@v6@@ -124,6 +142,8 @@ jobs:# the Dockerfile now declares a later `cloud` stage, and without a# target the default would silently become that stage.target: production+ build-args: |+ PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}platforms: linux/amd64,linux/arm64push: truecache-from: type=gha@@ -161,6 +181,7 @@ jobs:# the variant; add here when managed deployments need another.build-args: |CLOUD_BUNDLED_PLUGINS=daytona+ PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}platforms: linux/amd64,linux/arm64push: truecache-from: type=ghadiff --git a/Dockerfile b/Dockerfileindex e6a3cba9d1..7793c247fe 100644--- a/Dockerfile+++ b/Dockerfile@@ -59,6 +59,10 @@ RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" &FROM base AS productionARG USER_UID=1000ARG USER_GID=1000+# Real version for this build, computed from `git describe` on the CI runner+# (the image has no .git, so the server cannot derive it at runtime). Empty for+# local `docker build`, which just leaves the server on its normal fallbacks.+ARG PAPERCLIP_BUILD_VERSION=""WORKDIR /appCOPY --chown=node:node --from=build /app /appRUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai @google/gemini-cli@latest \@@ -78,6 +82,7 @@ ENV NODE_ENV=production \SERVE_UI=true \PAPERCLIP_HOME=/paperclip \PAPERCLIP_INSTANCE_ID=default \+ PAPERCLIP_BUILD_VERSION=${PAPERCLIP_BUILD_VERSION} \USER_UID=${USER_UID} \USER_GID=${USER_GID} \PAPERCLIP_CONFIG=/paperclip/instances/default/config.json \diff --git a/server/src/__tests__/build-version.test.ts b/server/src/__tests__/build-version.test.tsnew file mode 100644index 0000000000..9bf122583c--- /dev/null+++ b/server/src/__tests__/build-version.test.ts@@ -0,0 +1,58 @@+import { describe, expect, it, vi } from "vitest";+import { parseBuildVersion, readBuildVersion } from "../build-version.js";++describe("parseBuildVersion", () => {+ it("trims a stamped git describe string", () => {+ expect(parseBuildVersion(" v2026.722.0-15-g4c55f0d\n")).toBe("v2026.722.0-15-g4c55f0d");+ });++ it("accepts an already-resolved version verbatim", () => {+ expect(parseBuildVersion("2026.725.0-canary.2")).toBe("2026.725.0-canary.2");+ });++ it("rejects empty and whitespace-bearing values", () => {+ expect(parseBuildVersion("")).toBeNull();+ expect(parseBuildVersion(" ")).toBeNull();+ expect(parseBuildVersion("v1 with spaces")).toBeNull();+ expect(parseBuildVersion(null)).toBeNull();+ expect(parseBuildVersion(undefined)).toBeNull();+ });+});++describe("readBuildVersion", () => {+ it("prefers an explicit environment version over the file", () => {+ const readTextFile = vi.fn(() => "v9999.0.0-0-g0000000");++ expect(+ readBuildVersion({+ environmentVersion: "v2026.722.0-15-g4c55f0d",+ readTextFile,+ }),+ ).toBe("v2026.722.0-15-g4c55f0d");+ expect(readTextFile).not.toHaveBeenCalled();+ });++ it("reads the build marker when no environment version is set", () => {+ expect(+ readBuildVersion({+ environmentVersion: null,+ buildVersionPath: "/app/.paperclip-build-version",+ readTextFile: (path) => {+ expect(path).toBe("/app/.paperclip-build-version");+ return "v2026.722.0-15-g4c55f0d\n";+ },+ }),+ ).toBe("v2026.722.0-15-g4c55f0d");+ });++ it("returns null when neither the environment nor the file provides a version", () => {+ expect(+ readBuildVersion({+ environmentVersion: null,+ readTextFile: () => {+ throw new Error("ENOENT");+ },+ }),+ ).toBeNull();+ });+});diff --git a/server/src/__tests__/version.test.ts b/server/src/__tests__/version.test.tsindex d6d717d8e6..c3e05f95e8 100644--- a/server/src/__tests__/version.test.ts+++ b/server/src/__tests__/version.test.ts@@ -101,6 +101,7 @@ describe("resolveServerVersion", () => {it("uses deployment commit metadata when a source build has no git directory", () => {expect(resolveServerVersion({+ buildVersion: null,buildCommit: "0123456789abcdef0123456789abcdef01234567",packageVersion: "2026.706.0",gitDescribeCommand: () => {@@ -111,6 +112,66 @@ describe("resolveServerVersion", () => {).toBe("2026.706.0+0.git.0123456");});+ it("uses the stamped build version when a Docker image has no git directory", () => {+ const debugLog = vi.fn();++ expect(+ resolveServerVersion({+ // A real CalVer describe stamped by CI wins over the coarse build-commit+ // stamp and the source placeholder — this is the analytics/debug-panel fix.+ buildVersion: "v2026.722.0-15-g4c55f0d",+ buildCommit: "0123456789abcdef0123456789abcdef01234567",+ packageVersion: "0.3.1",+ gitDescribeCommand: () => {+ throw new Error("fatal: not a git repository");+ },+ debugLog,+ }),+ ).toBe("2026.722.0+15.git.4c55f0d");+ expect(debugLog).toHaveBeenCalledWith(+ { reason: "build_version" },+ "using stamped build version for server version",+ );+ });++ it("collapses an on-tag stamped build version to the release version", () => {+ expect(+ resolveServerVersion({+ buildVersion: "v2026.722.0-0-g4c55f0d",+ packageVersion: "0.3.1",+ gitDescribeCommand: () => {+ throw new Error("no git");+ },+ debugLog: vi.fn(),+ }),+ ).toBe("2026.722.0");+ });++ it("uses a pre-resolved stamped build version verbatim", () => {+ expect(+ resolveServerVersion({+ buildVersion: "2026.725.0-canary.2",+ packageVersion: "0.3.1",+ gitDescribeCommand: () => {+ throw new Error("no git");+ },+ debugLog: vi.fn(),+ }),+ ).toBe("2026.725.0-canary.2");+ });++ it("keeps the live git-derived version even when a build version is stamped", () => {+ expect(+ resolveServerVersion({+ // A stamped version is only a fallback: a real checkout's git describe wins.+ buildVersion: "v2020.1.1-0-g0000000",+ packageVersion: "0.3.1",+ gitDescribeCommand: () => "v2026.626.0-58-g518fc71ce\n",+ debugLog: vi.fn(),+ }),+ ).toBe("2026.626.0+58.git.518fc71ce");+ });+it("skips git metadata probing for packaged installs under node_modules", () => {const debugLog = vi.fn();diff --git a/server/src/build-version.ts b/server/src/build-version.tsnew file mode 100644index 0000000000..f0938e739c--- /dev/null+++ b/server/src/build-version.ts@@ -0,0 +1,45 @@+import { readFileSync } from "node:fs";+import { fileURLToPath } from "node:url";++type ReadTextFile = (path: string) => string;++// The build version stamp is computed by CI on the build runner (where `.git`+// exists) and baked into the image, so a running container reports the real+// version instead of the source `package.json` placeholder. It is typically the+// raw `git describe` output, e.g. "v2026.722.0-15-g4c55f0d"; version.ts runs it+// through the same parser used for a live checkout. A resolved version set+// directly is accepted verbatim.+const DEFAULT_BUILD_VERSION_PATH = fileURLToPath(+ new URL("../../.paperclip-build-version", import.meta.url),+);++export function parseBuildVersion(value: string | null | undefined): string | null {+ const version = value?.trim() ?? "";+ // A version/describe string is a single token: reject empties and anything+ // carrying whitespace so a stray file cannot inject a multi-line value.+ if (!version || /\s/.test(version)) return null;+ return version;+}++export function readBuildVersion(+ opts: {+ environmentVersion?: string | null;+ buildVersionPath?: string;+ readTextFile?: ReadTextFile;+ } = {},+): string | null {+ const environmentVersion = parseBuildVersion(+ opts.environmentVersion === undefined+ ? process.env.PAPERCLIP_BUILD_VERSION+ : opts.environmentVersion,+ );+ if (environmentVersion) return environmentVersion;++ try {+ const readTextFile =+ opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));+ return parseBuildVersion(readTextFile(opts.buildVersionPath ?? DEFAULT_BUILD_VERSION_PATH));+ } catch {+ return null;+ }+}diff --git a/server/src/version.ts b/server/src/version.tsindex 525c2e2697..6627637b02 100644--- a/server/src/version.ts+++ b/server/src/version.ts@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";import { existsSync, realpathSync } from "node:fs";import { basename, dirname, join } from "node:path";import { parseBuildCommit, readBuildCommit } from "./build-commit.js";+import { parseBuildVersion, readBuildVersion } from "./build-version.js";type PackageJson = {version?: string;@@ -149,6 +150,7 @@ export function parseGitDescribeVersion(output: string): string | null {export function resolveServerVersion(opts: {buildCommit?: string | null;+ buildVersion?: string | null;gitDescribeCommand?: GitDescribeCommand;packageVersion?: string;debugLog?: DebugLog;@@ -191,6 +193,23 @@ export function resolveServerVersion();}+ // Prefer a version stamped into the build. A Docker image has no `.git`, so+ // the git describe above cannot run; CI computes the version on the build+ // runner and bakes it in, carrying the real CalVer instead of the source+ // placeholder. Parsed with the same rules as a live checkout, so both report+ // the same string. Falls through to the coarser build-commit stamp when unset.+ const buildVersion =+ opts.buildVersion === undefined+ ? readBuildVersion()+ : parseBuildVersion(opts.buildVersion);+ if (buildVersion) {+ debugLog(+ { reason: "build_version" },+ "using stamped build version for server version",+ );+ return parseGitDescribeVersion(buildVersion) ?? buildVersion;+ }+const buildCommit =opts.buildCommit === undefined? readBuildCommit()