@andrian.yablonskyy/thub-common 1.0.7 → 1.0.9

package/README.md

@@ -46,7 +46,8 @@ A minimal `fetch`-based HTTP client for the Coordinator's `/api/v1` surface, wit
 ```js
 const { ApiClient } = require('@andrian.yablonskyy/thub-common');
 
-const client = new ApiClient({ baseUrl: 'https://thub.example.com', token: 'agt_...' });
+// userAgent is optional; the Coordinator records "thub-agent/<v>" / "thub-client/<v>" versions for its dashboard
+const client = new ApiClient({ baseUrl: 'https://thub.example.com', token: 'agt_...', userAgent: 'thub-agent/1.0.8' });
 const job = await client.post('/jobs', spec);
 await client.streamEvents(`/jobs/${job.jobId}/logs/stream`, {
   onEvent: ({ event, id, data }) => console.log(event, data)
@@ -55,6 +56,10 @@ await client.streamEvents(`/jobs/${job.jobId}/logs/stream`, {
 
 `request()`/`get()`/`post()` handle JSON bodies, query strings and non-2xx errors (throwing with `.status`/`.body` set); `streamEvents()` reconnects the caller is expected to drive (it just parses one connection's worth of events and resolves when the stream ends) and honors `Last-Event-ID` for resuming after a drop.
 
+### Version checks and self-update helpers
+
+`PACKAGES` (the Coordinator/Agent/Client npm names), `fetchLatestVersion(pkg, { registry })` (the `latest` dist-tag from the npm registry), `compareVersions`/`isNewer`/`isValidVersion` (strict `X.Y.Z[-pre]`), `npmBin()` (the npm next to the running node) and `npmInstallGlobal(pkg, version)` (only for the three TestHub packages, only a valid version).
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-common",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Shared job-spec schema, state enums and a thin API client used by the Agent and Client",
   "main": "src/index.js",
   "files": [

package/src/api-client.js

@@ -20,12 +20,15 @@
  * and manual usage identical").
  */
 class ApiClient{
-  constructor({ baseUrl, token }){
+  // `userAgent` (e.g. "thub-agent/1.0.8") is how the Coordinator learns
+  // which Agent/Client version is talking to it, for the dashboard.
+  constructor({ baseUrl, token, userAgent }){
     if (!baseUrl){
       throw new Error('ApiClient requires baseUrl');
     }
     this.baseUrl = baseUrl.replace(/\/+$/, '');
     this.token = token;
+    this.userAgent = userAgent;
   }
 
   _url(path){
@@ -34,6 +37,9 @@ class ApiClient{
 
   _headers(extra = {}){
     const headers = { ...extra };
+    if (this.userAgent){
+      headers['User-Agent'] = this.userAgent;
+    }
     if (this.token){
       headers.Authorization = `Bearer ${this.token}`;
     }

package/src/index.js

@@ -1,6 +1,6 @@
 /**
  * @file        packages/shared/src/index.js
- * @description Public entry point re-exporting shared states, schema, and API client
+ * @description Public entry point re-exporting shared states, schema, API client and update helpers
  *
  * @author      Andrian Yablonskyy
  * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
@@ -16,5 +16,6 @@
 module.exports = {
   ...require('./states'),
   ...require('./validate-job-spec'),
+  ...require('./updates'),
   ApiClient: require('./api-client').ApiClient
 };

package/src/updates.js

@@ -0,0 +1,117 @@
+/**
+ * @file        packages/shared/src/updates.js
+ * @description New-version checks and `npm i -g` self-update helpers shared by the Coordinator, Agent and Client
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const fs = require('node:fs'),
+  path = require('node:path'),
+  { spawnSync } = require('node:child_process');
+
+const PACKAGES = {
+    coordinator: '@andrian.yablonskyy/thub-coordinator',
+    agent: '@andrian.yablonskyy/thub-agent',
+    client: '@andrian.yablonskyy/thub-client'
+  },
+
+  // Strict on purpose: a version string ends up on an `npm i -g` command
+  // line (as root, for the Client), so nothing but a plain semver passes.
+  VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,32})?$/,
+
+  DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+function isValidVersion(v){
+  return typeof v === 'string' && VERSION_RE.test(v);
+}
+
+// Semver precedence for x.y.z[-pre]: numeric core first, then a release
+// sorts after any of its prereleases. Returns <0, 0 or >0.
+function compareVersions(a, b){
+  const [coreA, preA] = String(a).split('-', 2),
+    [coreB, preB] = String(b).split('-', 2),
+    partsA = coreA.split('.').map(Number),
+    partsB = coreB.split('.').map(Number);
+  for (let i = 0; i < 3; i++){
+    const diff = (partsA[i] || 0) - (partsB[i] || 0);
+    if (diff){
+      return diff;
+    }
+  }
+  if (preA === preB){
+    return 0;
+  }
+  if (!preA){
+    return 1;
+  }
+  if (!preB){
+    return -1;
+  }
+  return preA < preB ? -1 : 1;
+}
+
+function isNewer(candidate, current){
+  return isValidVersion(candidate) && isValidVersion(current) && compareVersions(candidate, current) > 0;
+}
+
+// The registry npm itself would use (`npm_config_registry` is set when
+// running under npm), else the public one.
+function defaultRegistry(){
+  return (process.env.npm_config_registry || DEFAULT_REGISTRY).replace(/\/+$/, '');
+}
+
+// Latest published version of `pkg` (its `latest` dist-tag).
+async function fetchLatestVersion(pkg, { registry = defaultRegistry(), timeoutMs = 10_000 } = {}){
+  const url = `${registry.replace(/\/+$/, '')}/${pkg.replace('/', '%2f')}/latest`,
+    res = await fetch(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok){
+    throw new Error(`${pkg}: registry returned HTTP ${res.status}`);
+  }
+  const { version } = await res.json();
+  if (!isValidVersion(version)){
+    throw new Error(`${pkg}: registry returned an invalid version`);
+  }
+  return version;
+}
+
+// The npm that belongs to the running node (same prefix as this global
+// install, whether apt, nvm or a custom prefix), falling back to PATH.
+function npmBin(){
+  const candidate = path.join(path.dirname(process.execPath), 'npm');
+  return fs.existsSync(candidate) ? candidate : 'npm';
+}
+
+// `npm i -g <pkg>@<version>` (as the current user — root for the Client's
+// update helper; `sudo` is the caller's job otherwise). Returns npm's exit code.
+function npmInstallGlobal(pkg, version, { env = process.env, stdio = 'inherit' } = {}){
+  if (!Object.values(PACKAGES).includes(pkg)){
+    throw new Error(`Refusing to install unknown package ${pkg}`);
+  }
+  if (!isValidVersion(version)){
+    throw new Error(`Invalid version "${version}"`);
+  }
+  const result = spawnSync(npmBin(), ['i', '-g', `${pkg}@${version}`], { env, stdio });
+  if (result.error){
+    throw result.error;
+  }
+  return result.status;
+}
+
+module.exports = {
+  PACKAGES,
+  isValidVersion,
+  compareVersions,
+  isNewer,
+  defaultRegistry,
+  fetchLatestVersion,
+  npmBin,
+  npmInstallGlobal
+};