diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 1cf0640c62..66c505e3f8 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -21,6 +21,24 @@ jobs: steps: - name: Checkout uses: 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:-}" - name: Setup pnpm uses: 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/arm64 push: true cache-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/arm64 push: true cache-from: type=gha diff --git a/Dockerfile b/Dockerfile index 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 production ARG USER_UID=1000 ARG 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 /app COPY --chown=node:node --from=build /app /app RUN 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.ts new file mode 100644 index 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.ts index 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.ts new file mode 100644 index 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.ts index 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()