@andrian.yablonskyy/thub-common 1.0.0

package/LICENSE.md

@@ -0,0 +1,26 @@
+Custom License
+
+Copyright (c) 2026 Andrian Yablonskyy
+
+Permission is granted to use this software as-is, subject to the following
+conditions:
+
+1. No Modification. This software may not be modified, adapted, or used to
+   create derivative works.
+
+2. No Redistribution. This software may not be republished, redistributed,
+   or repackaged, in whole or in part, under this or any other name.
+
+3. Public Use Notification. Any public use of this software (including in a
+   publicly accessible product, service, or project) requires prior
+   notification to the author at andrian.yablonskyy@gmail.com.
+
+4. Commercial Use. Any commercial use of this software requires the
+   author's prior written agreement.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @andrian.yablonskyy/thub-common
+
+Shared code for [TestHub](https://github.com/andrianyablonskyy/thub) — a self-hosted job network that lets CI/CD pipelines and individual developers run firmware tests on real hardware or emulators in a private lab. This package has no server and no CLI of its own; it's the small, dependency-light core that the [Agent](https://github.com/andrianyablonskyy/thub-agent), [Coordinator](https://github.com/andrianyablonskyy/thub-coordinator) and [Client](https://github.com/andrianyablonskyy/thub-client) all depend on, so the three speak exactly the same protocol.
+
+See the [main TestHub repo](https://github.com/andrianyablonskyy/thub) for the full system architecture, deployment diagrams and end-to-end flows.
+
+## Install
+
+```bash
+npm install @andrian.yablonskyy/thub-common
+```
+
+## What's in it
+
+### Job spec schema and validation
+
+An [Ajv](https://ajv.js.org/) JSON schema for the job specification the Agent sends to the Coordinator, and a thin wrapper that validates a spec and fills in its defaults.
+
+```js
+const { validateJobSpec } = require('@andrian.yablonskyy/thub-common');
+
+const { valid, spec, errors } = validateJobSpec({
+  target: { type: 'hw', labels: ['board:nucleo-f401re'] },
+  firmware: { url: 'https://artifactory.example.com/app.bin' },
+  tests: { url: 'https://artifactory.example.com/tests.tar.gz' }
+});
+```
+
+The schema deliberately has no field for shell commands — a job only ever names a firmware image and a test package; the Client runs a fixed entry point (`run-tests.sh`) from that package, never arbitrary code from the spec itself. Top-level fields: `target` (`type`, `labels`, optional `group`), `firmware` (`url`, optional `sha256`/`flashAddress`), `tests` (`url`, `suite`, `args`), `timeoutSec`, `priority`, `source` (`ci`/`cli`), `user` (a free-text job-owner label), `meta` (arbitrary key/value metadata), and `dryRun`.
+
+### State enums and exit codes
+
+```js
+const { RESOURCE_STATES, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, BUSY_SOURCES, EXIT_CODES, exitCodeForJobState } = require('@andrian.yablonskyy/thub-common');
+```
+
+- `RESOURCE_STATES`: `REGISTERED`, `IDLE`, `BUSY`, `OUT_OF_SERVICE`, `MAINTENANCE`.
+- `JOB_STATES`: `QUEUED`, `ASSIGNED`, `PREPARING`, `RUNNING`, `PASSED`, `FAILED`, `ERROR`, `TIMEOUT`, `CANCELED`, `LOST`. `ACTIVE_JOB_STATES`/`TERMINAL_JOB_STATES` are the two natural partitions of that set.
+- `BUSY_SOURCES`: `ci`, `cli`, `local` — why a resource is currently busy.
+- `EXIT_CODES` / `exitCodeForJobState(state)`: the Agent CLI's process exit codes (`PASSED` → 0, `FAILED` → 1, `ERROR`/`TIMEOUT`/`LOST` → 2, `CANCELED` → 3, usage/auth error → 4, detached with Ctrl-C → 130), so a CI step can branch on `$?` without parsing output.
+
+### API client
+
+A minimal `fetch`-based HTTP client for the Coordinator's `/api/v1` surface, with a hand-rolled Server-Sent-Events parser (no external SSE dependency) — used by both the Agent and the Client so they speak the exact same protocol.
+
+```js
+const { ApiClient } = require('@andrian.yablonskyy/thub-common');
+
+const client = new ApiClient({ baseUrl: 'https://thub.example.com', token: 'agt_...' });
+const job = await client.post('/jobs', spec);
+await client.streamEvents(`/jobs/${job.jobId}/logs/stream`, {
+  onEvent: ({ event, id, data }) => console.log(event, data)
+});
+```
+
+`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.
+
+## Development
+
+```bash
+npm install
+npm test    # node --test test/*.test.js
+npm run lint
+```
+
+## License
+
+See [LICENSE.md](./LICENSE.md).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@andrian.yablonskyy/thub-common",
+  "version": "1.0.0",
+  "description": "Shared job-spec schema, state enums and a thin API client used by the Agent and Client",
+  "main": "src/index.js",
+  "files": ["src"],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Andrian Yablonskyy <andrian.yablonskyy@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrianyablonskyy/thub-common.git"
+  },
+  "homepage": "https://github.com/andrianyablonskyy/thub-common#readme",
+  "bugs": "https://github.com/andrianyablonskyy/thub-common/issues",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.11.0",
+    "eslint-plugin-promise": "^7.3.0",
+    "globals": "^17.12.0"
+  }
+}

package/src/api-client.js

@@ -0,0 +1,168 @@
+/**
+ * @file        packages/shared/src/api-client.js
+ * @description Fetch-based HTTP client with SSE parsing, shared by the 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';
+
+/**
+ * A thin wrapper around fetch() for talking to the Coordinator's
+ * /api/v1 surface. Shared by the Agent CLI and the Client daemon so
+ * both speak the exact same protocol (README.md §1: "This keeps CI
+ * and manual usage identical").
+ */
+class ApiClient{
+  constructor({ baseUrl, token }){
+    if (!baseUrl){
+      throw new Error('ApiClient requires baseUrl');
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.token = token;
+  }
+
+  _url(path){
+    return `${this.baseUrl}/api/v1${path}`;
+  }
+
+  _headers(extra = {}){
+    const headers = { ...extra };
+    if (this.token){
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
+
+  async request(method, path, { body, headers, query, signal } = {}){
+    let url = this._url(path);
+    if (query){
+      const qs = new URLSearchParams(
+        Object.entries(query).filter(([, v]) => v !== undefined && v !== null)
+      ).toString();
+      if (qs){
+        url += `?${qs}`;
+      }
+    }
+
+    const isJsonBody = body !== undefined && !(body instanceof FormData),
+      res = await fetch(url, {
+        method,
+        signal,
+        headers: this._headers({
+          ...(isJsonBody ? { 'Content-Type': 'application/json' } : {}),
+          ...headers
+        }),
+        body: isJsonBody ? JSON.stringify(body) : body
+      }),
+
+      text = await res.text(),
+      data = text ? safeJson(text) : undefined;
+
+    if (!res.ok){
+      const err = new Error((data && data.error) || `HTTP ${res.status}`);
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data;
+  }
+
+  get(path, opts){
+    return this.request('GET', path, opts);
+  }
+
+  post(path, body, opts){
+    return this.request('POST', path, { ...opts, body });
+  }
+
+  /**
+   * Opens a Server-Sent-Events stream and invokes onEvent({event, id, data})
+   * for each event. Resolves when the stream ends (server closes it, e.g.
+   * on job.end) or rejects on network error / abort.
+   */
+  async streamEvents(path, { lastEventId, signal, onEvent, query } = {}){
+    let url = this._url(path);
+    if (query){
+      const qs = new URLSearchParams(
+        Object.entries(query).filter(([, v]) => v !== undefined && v !== null)
+      ).toString();
+      if (qs){
+        url += `?${qs}`;
+      }
+    }
+
+    const headers = this._headers({ Accept: 'text/event-stream' });
+    if (lastEventId){
+      headers['Last-Event-ID'] = String(lastEventId);
+    }
+
+    const res = await fetch(url, { headers, signal });
+    if (!res.ok){
+      const err = new Error(`HTTP ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+
+    const reader = res.body.getReader(),
+      decoder = new TextDecoder();
+    let buf = '';
+
+    while (true){
+      const { done, value } = await reader.read();
+      if (done){
+        break;
+      }
+      buf += decoder.decode(value, { stream: true });
+
+      let sep;
+      while ((sep = buf.indexOf('\n\n')) !== -1){
+        const rawEvent = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        const parsed = parseSseEvent(rawEvent);
+        if (parsed){
+          onEvent(parsed);
+        }
+      }
+    }
+  }
+}
+
+function parseSseEvent(raw){
+  let event = 'message',
+    id;
+  const dataLines = [];
+  for (const line of raw.split('\n')){
+    if (line.startsWith('event:')){
+      event = line.slice(6).trim();
+    }
+    else if (line.startsWith('id:')){
+      id = line.slice(3).trim();
+    }
+    else if (line.startsWith('data:')){
+      dataLines.push(line.slice(5).trim());
+    }
+  }
+  if (dataLines.length === 0 && !id){
+    return null;
+  }
+  const rawData = dataLines.join('\n');
+  return { event, id, data: safeJson(rawData) ?? rawData };
+}
+
+function safeJson(text){
+  try {
+    return JSON.parse(text);
+  }
+  catch {
+    return undefined;
+  }
+}
+
+module.exports = { ApiClient };

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * @file        packages/shared/src/index.js
+ * @description Public entry point re-exporting shared states, schema, and API 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';
+
+module.exports = {
+  ...require('./states'),
+  ...require('./validate-job-spec'),
+  ApiClient: require('./api-client').ApiClient
+};

package/src/job-spec.schema.js

@@ -0,0 +1,78 @@
+/**
+ * @file        packages/shared/src/job-spec.schema.js
+ * @description Ajv JSON schema for the job specification (README §4.3)
+ *
+ * @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';
+
+// Matches the job spec shape documented in README.md §4.3.
+// Deliberately has no field for shell commands: the Client only ever
+// runs the fixed entry point from the downloaded test package.
+const jobSpecSchema = {
+  $id: 'https://thub.example.com/schemas/job-spec.json',
+  type: 'object',
+  additionalProperties: false,
+  required: ['target', 'firmware', 'tests'],
+  properties: {
+    target: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['type'],
+      properties: {
+        type: { enum: ['hw', 'sw'] },
+        labels: {
+          type: 'array',
+          items: { type: 'string', minLength: 1 },
+          default: []
+        },
+        // Constrains scheduling to resources that are members of this
+        // group (§13.1, `thub run --group <id>`) — a third targeting
+        // dimension alongside type/labels. Omitted: any matching resource
+        // in any (or no) group is eligible, same as before groups existed.
+        group: { type: 'string', minLength: 1 }
+      }
+    },
+    firmware: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['url'],
+      properties: {
+        url: { type: 'string', format: 'uri' },
+        sha256: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+        flashAddress: { type: 'string' }
+      }
+    },
+    tests: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['url'],
+      properties: {
+        url: { type: 'string', format: 'uri' },
+        suite: { type: 'string', default: 'default' },
+        args: { type: 'array', items: { type: 'string' }, default: [] }
+      }
+    },
+    timeoutSec: { type: 'integer', minimum: 1, default: 1800 },
+    priority: { type: 'integer', minimum: 0, maximum: 100, default: 50 },
+    source: { enum: ['ci', 'cli'] },
+    // Free-text job owner (`thub run --user <name>`, §7.1) — purely a
+    // label shown on the Client and dashboard to tell whose job is whose,
+    // not an identity: nothing authenticates or enforces it.
+    user: { type: 'string', minLength: 1 },
+    meta: { type: 'object' },
+    // Exercises the full pipeline (schedule, accept, state transitions,
+    // logs, artifact, result) without flashing/running anything for real —
+    // see README §7.1 "Dry-run the pipeline".
+    dryRun: { type: 'boolean', default: false }
+  }
+};
+
+module.exports = { jobSpecSchema };

package/src/states.js

@@ -0,0 +1,105 @@
+/**
+ * @file        packages/shared/src/states.js
+ * @description Resource and job state enums, and CLI exit codes
+ *
+ * @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';
+
+// §4.1 Resource (Client) states
+const RESOURCE_STATES = Object.freeze({
+    REGISTERED: 'REGISTERED',
+    IDLE: 'IDLE',
+    BUSY: 'BUSY',
+    OUT_OF_SERVICE: 'OUT_OF_SERVICE',
+    MAINTENANCE: 'MAINTENANCE'
+  }),
+
+  SCHEDULABLE_RESOURCE_STATES = new Set([RESOURCE_STATES.IDLE]),
+
+  BUSY_SOURCES = Object.freeze({
+    CI: 'ci',
+    CLI: 'cli',
+    LOCAL: 'local'
+  }),
+
+  // §4.2 Job states
+  JOB_STATES = Object.freeze({
+    QUEUED: 'QUEUED',
+    ASSIGNED: 'ASSIGNED',
+    PREPARING: 'PREPARING',
+    RUNNING: 'RUNNING',
+    PASSED: 'PASSED',
+    FAILED: 'FAILED',
+    ERROR: 'ERROR',
+    TIMEOUT: 'TIMEOUT',
+    CANCELED: 'CANCELED',
+    LOST: 'LOST'
+  }),
+
+  TERMINAL_JOB_STATES = new Set([
+    JOB_STATES.PASSED,
+    JOB_STATES.FAILED,
+    JOB_STATES.ERROR,
+    JOB_STATES.TIMEOUT,
+    JOB_STATES.CANCELED,
+    JOB_STATES.LOST
+  ]),
+
+  ACTIVE_JOB_STATES = new Set([
+    JOB_STATES.QUEUED,
+    JOB_STATES.ASSIGNED,
+    JOB_STATES.PREPARING,
+    JOB_STATES.RUNNING
+  ]),
+
+  JOB_SOURCES = Object.freeze({
+    CI: 'ci',
+    CLI: 'cli'
+  }),
+
+  // §7 Agent CLI exit codes
+  EXIT_CODES = Object.freeze({
+    PASSED: 0,
+    FAILED: 1,
+    INFRA: 2, // ERROR, TIMEOUT, LOST
+    CANCELED: 3,
+    USAGE: 4,
+    DETACHED: 130
+  });
+
+function exitCodeForJobState(state){
+  switch (state){
+    case JOB_STATES.PASSED:
+      return EXIT_CODES.PASSED;
+    case JOB_STATES.FAILED:
+      return EXIT_CODES.FAILED;
+    case JOB_STATES.ERROR:
+    case JOB_STATES.TIMEOUT:
+    case JOB_STATES.LOST:
+      return EXIT_CODES.INFRA;
+    case JOB_STATES.CANCELED:
+      return EXIT_CODES.CANCELED;
+    default:
+      return EXIT_CODES.USAGE;
+  }
+}
+
+module.exports = {
+  RESOURCE_STATES,
+  SCHEDULABLE_RESOURCE_STATES,
+  BUSY_SOURCES,
+  JOB_STATES,
+  TERMINAL_JOB_STATES,
+  ACTIVE_JOB_STATES,
+  JOB_SOURCES,
+  EXIT_CODES,
+  exitCodeForJobState
+};

package/src/validate-job-spec.js

@@ -0,0 +1,38 @@
+/**
+ * @file        packages/shared/src/validate-job-spec.js
+ * @description Validates a job spec object against the Ajv schema
+ *
+ * @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 Ajv = require('ajv'),
+  addFormats = require('ajv-formats'),
+  { jobSpecSchema } = require('./job-spec.schema');
+
+const ajv = new Ajv({ useDefaults: true, allErrors: true, strict: false });
+addFormats(ajv);
+const validateFn = ajv.compile(jobSpecSchema);
+
+/**
+ * Validates and normalizes (defaults applied in place) a job spec.
+ * Returns { valid, spec, errors }.
+ */
+function validateJobSpec(spec){
+  const clone = JSON.parse(JSON.stringify(spec ?? {})),
+    valid = validateFn(clone);
+  return {
+    valid,
+    spec: clone,
+    errors: valid ? [] : (validateFn.errors || []).map((e) => `${e.instancePath || '/'} ${e.message}`)
+  };
+}
+
+module.exports = { validateJobSpec };