fix(version): mark dev builds dirty for untracked files; freeze /api/version at startup

git describe --dirty only flags tracked-file modifications, so adding a
new untracked file (e.g. hi.txt) left the version label clean. Now also
runs git status --porcelain and treats any untracked entries as dirty so
local dev builds are visibly distinct from a tagged release.

Also makes /api/version return the version captured at process startup
(matching /api/update-check) instead of re-spawning git describe per
request. The version label now reliably reflects the code that's
actually running — restart the service to pick up new commits/changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

packages/site/src/content/docs/api.md

@@ -528,7 +528,7 @@ Returned when the server was started with `--no-password`.
 
 #### `GET /api/version`
 
-Get the server version.
+Get the server version. The value is captured once at process startup and reflects the running code (not the latest git state on disk). Restart the service to pick up a new version.
 
 **Response:**
 

src/server/routes.js

@@ -163,11 +163,12 @@ function setupRoutes(
     }
   });
 
-  // Version API
+  // Version API — uses the version captured at server startup so dev/prod
+  // builds stay stable for the lifetime of the process. Restart the service
+  // to pick up a new git tag or dirty-state change.
   app.get('/api/version', (_req, res) => {
     log.debug('Version requested');
-    const { getVersion } = require('../utils/version');
-    res.json({ version: getVersion() });
+    res.json({ version: config.version });
   });
 
   // Changelog — served from repo CHANGELOG.md (bundled with the npm package).

src/utils/version.js

@@ -18,9 +18,10 @@ function getVersion() {
 
   // Running from source — git tags are the version source of truth.
   // This avoids drift between package.json and tagged releases.
+  const repoRoot = path.join(__dirname, '..', '..');
   try {
     const gitDesc = execSync('git describe --tags --always --dirty', {
-      cwd: path.join(__dirname, '..', '..'),
+      cwd: repoRoot,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
       windowsHide: true,
@@ -31,7 +32,10 @@ function getVersion() {
       const gitVersion = tagMatch[1];
       const commits = tagMatch[2];
       const hash = tagMatch[3];
-      const dirty = tagMatch[4];
+      // `git describe --dirty` only flags tracked-file modifications. Treat any
+      // untracked files (e.g. a fresh `hi.txt`) as dirty too so dev builds are
+      // always visibly distinct from the tagged release.
+      const dirty = tagMatch[4] || (hasUntrackedChanges(repoRoot) ? '-dirty' : '');
 
       // Exactly on a clean tag — return the tag version
       if (!commits && !dirty) {
@@ -69,4 +73,18 @@ function isInstalledGlobally() {
   return __dirname.includes('node_modules');
 }
 
+function hasUntrackedChanges(cwd) {
+  try {
+    const status = execSync('git status --porcelain', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    return status.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = { getVersion };

test/utils/version.test.js

@@ -44,6 +44,7 @@ describe('Version', () => {
     const origExecSync = child_process.execSync;
     child_process.execSync = (cmd, opts) => {
       if (cmd.includes('git describe')) return 'v2.5.0\n';
+      if (cmd.includes('git status --porcelain')) return '';
       return origExecSync(cmd, opts);
     };
     try {
@@ -62,6 +63,7 @@ describe('Version', () => {
     const origExecSync = child_process.execSync;
     child_process.execSync = (cmd, opts) => {
       if (cmd.includes('git describe')) return 'v2.5.0-3-gabcdef1\n';
+      if (cmd.includes('git status --porcelain')) return '';
       return origExecSync(cmd, opts);
     };
     try {
@@ -92,6 +94,44 @@ describe('Version', () => {
     }
   });
 
+  it('should mark version dirty when only untracked files are present', () => {
+    delete process.env.npm_package_version;
+    const child_process = require('child_process');
+    const origExecSync = child_process.execSync;
+    child_process.execSync = (cmd, opts) => {
+      if (cmd.includes('git describe')) return 'v2.5.0\n';
+      if (cmd.includes('git status --porcelain')) return '?? hi.txt\n';
+      return origExecSync(cmd, opts);
+    };
+    try {
+      delete require.cache[require.resolve('../../src/utils/version')];
+      const { getVersion } = require('../../src/utils/version');
+      assert.equal(getVersion(), '2.5.0-dev+dirty');
+    } finally {
+      child_process.execSync = origExecSync;
+      delete require.cache[require.resolve('../../src/utils/version')];
+    }
+  });
+
+  it('should stay clean when no untracked or modified files are present', () => {
+    delete process.env.npm_package_version;
+    const child_process = require('child_process');
+    const origExecSync = child_process.execSync;
+    child_process.execSync = (cmd, opts) => {
+      if (cmd.includes('git describe')) return 'v2.5.0\n';
+      if (cmd.includes('git status --porcelain')) return '';
+      return origExecSync(cmd, opts);
+    };
+    try {
+      delete require.cache[require.resolve('../../src/utils/version')];
+      const { getVersion } = require('../../src/utils/version');
+      assert.equal(getVersion(), '2.5.0');
+    } finally {
+      child_process.execSync = origExecSync;
+      delete require.cache[require.resolve('../../src/utils/version')];
+    }
+  });
+
   it('should fall back to package.json when git has no semver tag', () => {
     delete process.env.npm_package_version;
     const child_process = require('child_process');