@andrian.yablonskyy/thub-coordinator 1.0.0

package/public/js/theme.js

@@ -0,0 +1,51 @@
+/**
+ * @file        packages/coordinator/public/js/theme.js
+ * @description Dashboard: theme toggle, persisted to the account (§10.1) with localStorage as a pre-login fallback
+ *
+ * @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';
+
+(function (){
+  const root = document.documentElement,
+    key = 'thub-theme';
+
+  function apply(theme){
+    root.setAttribute('data-bs-theme', theme);
+  }
+
+  // Server-rendered value (layout.pug: html(data-bs-theme=user.theme)) wins
+  // once logged in — it's the account's saved preference, synced across
+  // devices (§10.1). "auto" means no account preference yet (or logged
+  // out, e.g. the login page), so localStorage is still the fallback there.
+  if (root.getAttribute('data-bs-theme') === 'auto'){
+    const stored = localStorage.getItem(key);
+    if (stored){
+      apply(stored);
+    }
+  }
+
+  // Shared by the navbar toggle below and the profile page's theme buttons
+  // (public/js/profile-theme.js) — one place that applies it locally and
+  // persists it to the account, so both call sites can't drift.
+  window.thubSetTheme = function thubSetTheme(theme){
+    apply(theme);
+    localStorage.setItem(key, theme);
+    fetch('/profile/theme', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ theme })
+    }).catch(() => {}); // best effort — logged-out visitors can still toggle locally
+  };
+
+  document.getElementById('theme-toggle')?.addEventListener('click', () => {
+    window.thubSetTheme(root.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark');
+  });
+})();

package/public/js/tooltips.js

@@ -0,0 +1,18 @@
+/**
+ * @file        packages/coordinator/public/js/tooltips.js
+ * @description Dashboard: initializes Bootstrap tooltips on data-bs-toggle elements
+ *
+ * @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';
+
+(function (){
+  document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach((el) => new bootstrap.Tooltip(el));
+})();

package/src/api/admin.js

@@ -0,0 +1,112 @@
+/**
+ * @file        packages/coordinator/src/api/admin.js
+ * @description Admin API routes: agents, join key, resource maintenance, job queue reset/clean (README §6.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';
+
+const express = require('express'),
+  { requireAdminSession, requireAdminRole } = require('../auth'),
+  { generateToken, hashToken } = require('../services/tokens');
+
+// §6.3 Admin endpoints. Authenticated via the dashboard session (§10),
+// not an API bearer token.
+function createAdminRouter({ services }){
+  const router = express.Router();
+  router.use(requireAdminSession, requireAdminRole);
+
+  router.post('/agents', (req, res, next) => {
+    try {
+      const { name, kind } = req.body;
+      if (!name || !['ci', 'cli'].includes(kind)){
+        return res.status(400).json({ error: 'name and kind (ci|cli) are required' });
+      }
+      const { agent, token } = services.agents.create({ name, kind });
+      res.status(201).json({ agent, token });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.delete('/agents/:id', (req, res) => {
+    services.agents.revoke(req.params.id);
+    res.status(204).end();
+  });
+
+  router.post('/resources/:id/maintenance', (req, res, next) => {
+    try {
+      const resource = services.registry.setMaintenance(req.params.id, !!req.body.enabled);
+      res.json(resource);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  // Referenced in §10's dashboard resource actions.
+  router.post('/resources/:id/rotate-token', (req, res) => {
+    const token = generateToken('res');
+    services.db.prepare('UPDATE resources SET token_hash = ? WHERE id = ?').run(hashToken(token), req.params.id);
+    services.events.record('resource', req.params.id, 'resource.token_rotated', {});
+    res.json({ resourceToken: token });
+  });
+
+  // Cancels every QUEUED/ASSIGNED/PREPARING/RUNNING job (§13.1).
+  router.post('/jobs/reset-queue', (req, res) => {
+    const canceled = services.jobs.resetQueue();
+    res.json({ canceled });
+  });
+
+  // Permanently deletes finished jobs and their logs/artifacts (§13.1).
+  router.post('/jobs/clean-history', (req, res) => {
+    const deleted = services.jobs.cleanHistory();
+    res.json({ deleted });
+  });
+
+  // Resource groups (§13.1) — membership itself is declared by each
+  // Client's own config (`groups: [...]`), not managed here.
+  router.get('/groups', (req, res) => {
+    res.json({ groups: services.groups.list() });
+  });
+
+  router.post('/groups', (req, res, next) => {
+    try {
+      const { name, comment } = req.body;
+      if (!name){
+        return res.status(400).json({ error: 'name is required' });
+      }
+      res.status(201).json(services.groups.create({ name, comment }));
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/groups/:id', (req, res, next) => {
+    try {
+      const { name, comment } = req.body;
+      res.json(services.groups.update(req.params.id, { name, comment }));
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.delete('/groups/:id', (req, res) => {
+    services.groups.remove(req.params.id);
+    res.status(204).end();
+  });
+
+  return router;
+}
+
+module.exports = { createAdminRouter };

package/src/api/agent.js

@@ -0,0 +1,110 @@
+/**
+ * @file        packages/coordinator/src/api/agent.js
+ * @description Agent API routes: job submission, status, cancel, log streaming (README §6.1)
+ *
+ * @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 express = require('express'),
+  { requireRole } = require('../auth'),
+  { attachJobStream } = require('./sse');
+
+// §6.1 Agent endpoints.
+function createAgentRouter({ services, config }){
+  const router = express.Router(),
+    // Applied per-route (not via router.use()) because this router shares
+    // the /api/v1 prefix with the resource and admin routers — a blanket
+    // router-level middleware would run for their paths too, before route
+    // matching even happens, and reject them for lacking an agent token.
+    auth = requireRole('agent');
+
+  router.post('/jobs', auth, (req, res, next) => {
+    try {
+      const job = services.jobs.create({ agentId: req.agent.id, source: req.body.source || 'cli', spec: req.body });
+      res.status(201).json({ jobId: job.id, state: job.state, webUrl: `${config.publicUrl}/jobs/${job.id}` });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.get('/jobs/:id', auth, (req, res) => {
+    const job = services.jobs.get(req.params.id);
+    if (!job){
+      return res.status(404).json({ error: 'Unknown job' });
+    }
+    const resource = job.resource_id ? services.registry.get(job.resource_id) : null;
+    res.json({ ...job, resource: resource ? { id: resource.id, name: resource.name } : null });
+  });
+
+  router.get('/jobs', auth, (req, res) => {
+    const jobs = services.jobs.list({
+      state: req.query.state,
+      source: req.query.source,
+      agentId: req.agent.id,
+      mine: req.query.mine === 'true' || req.query.mine === '1',
+      limit: req.query.limit ? Number(req.query.limit) : undefined
+    });
+    res.json({ jobs });
+  });
+
+  router.post('/jobs/:id/cancel', auth, (req, res, next) => {
+    try {
+      const job = services.jobs.cancel(req.params.id, { agentId: req.agent.id, isAdmin: false });
+      res.json(job);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.get('/jobs/:id/logs', auth, (req, res) => {
+    const after = Number(req.query.after || 0),
+      limit = req.query.limit ? Number(req.query.limit) : undefined;
+    res.json({ lines: services.logs.listSince(req.params.id, after, limit) });
+  });
+
+  router.get('/jobs/:id/logs/stream', auth, (req, res) => {
+    attachJobStream(req, res, { jobId: req.params.id, services, config });
+  });
+
+  router.get('/jobs/:id/artifacts', auth, (req, res) => {
+    const artifacts = services.artifacts.listForJob(req.params.id).map((a) => ({
+      id: a.id,
+      name: a.name,
+      size: a.size,
+      sha256: a.sha256,
+      contentType: a.content_type,
+      url: services.artifacts.signedUrl(a)
+    }));
+    res.json({ artifacts });
+  });
+
+  router.get('/resources', auth, (req, res) => {
+    res.json({ resources: services.registry.list().map(publicResource) });
+  });
+
+  return router;
+}
+
+function publicResource(r){
+  return {
+    id: r.id,
+    name: r.name,
+    type: r.type,
+    status: r.status,
+    busySource: r.busy_source,
+    labels: r.labels,
+    lastHeartbeatAt: r.last_heartbeat_at
+  };
+}
+
+module.exports = { createAgentRouter };

package/src/api/resource.js

@@ -0,0 +1,211 @@
+/**
+ * @file        packages/coordinator/src/api/resource.js
+ * @description Resource (Client) API routes: register, heartbeat, job long-poll, result/log upload (README §6.2)
+ *
+ * @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 express = require('express'),
+  multer = require('multer'),
+  { requireRole, requireJoinKey } = require('../auth'),
+  { JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+
+const upload = multer({ dest: require('node:os').tmpdir() });
+
+function requireOwnResource(req, res, next){
+  if (req.resource.id !== req.params.id){
+    return res.status(403).json({ error: 'Token does not match resource' });
+  }
+  next();
+}
+
+function requireOwnJob(services){
+  return (req, res, next) => {
+    const job = services.jobs.get(req.params.id);
+    if (!job){
+      return res.status(404).json({ error: 'Unknown job' });
+    }
+    if (job.resource_id !== req.resource.id){
+      return res.status(403).json({ error: 'Job is not assigned to this resource' });
+    }
+    req.job = job;
+    next();
+  };
+}
+
+// §6.2 Resource (Client) endpoints.
+function createResourceRouter({ services, config }){
+  const router = express.Router();
+
+  // Self-service registration: no admin action required. A Client proves
+  // it belongs by presenting the shared clientJoinKey (config/env on its
+  // side) and declares its own name/type/labels; the Coordinator upserts
+  // the resource by name (see registry.registerAuto).
+  router.post('/resources/register', requireJoinKey(config), (req, res, next) => {
+    try {
+      const { clientId, name, type, labels, groups, hostInfo, capabilities } = req.body;
+      if (!clientId){
+        return res.status(400).json({ error: 'clientId is required (persisted in the Client\'s .client-id file)' });
+      }
+      if (!name || !['hw', 'sw'].includes(type)){
+        return res.status(400).json({ error: 'name and type (hw|sw) are required' });
+      }
+      const { resourceId, resourceToken } = services.registry.registerAuto({
+        clientId,
+        name,
+        type,
+        labels: labels || capabilities?.labels || [],
+        groups: groups || [],
+        hostInfo
+      });
+      res.json({ resourceId, resourceToken, heartbeatIntervalSec: config.heartbeat.intervalSec });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  // Applied per-route, not via router.use() — this router shares the
+  // /api/v1 prefix with the agent and admin routers, and a blanket
+  // router-level middleware would run for their paths too before route
+  // matching happens (see the same note in api/agent.js).
+  const auth = requireRole('resource');
+
+  router.post('/resources/:id/heartbeat', auth, requireOwnResource, (req, res, next) => {
+    try {
+      const { state, activeJobId, localLock, metrics } = req.body;
+      services.registry.heartbeat(req.params.id, { state, activeJobId, localLock, metrics });
+      const commands = services.commands.drain(req.params.id);
+      res.json({ serverTime: new Date().toISOString(), commands });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/resources/:id/status', auth, requireOwnResource, (req, res, next) => {
+    try {
+      const { busy, source, reason } = req.body;
+      if (source && source !== 'local'){
+        return res.status(400).json({ error: 'Only source=local may be set explicitly' });
+      }
+      const resource = services.registry.setLocalLock(req.params.id, { locked: !!busy, reason });
+      res.json(resource);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.get('/resources/:id/jobs/next', auth, requireOwnResource, async (req, res) => {
+    const waitSec = Math.min(Number(req.query.wait) || 0, 60),
+
+      existing = services.jobs.list({ state: JOB_STATES.ASSIGNED, resourceId: req.params.id, limit: 1 })[0];
+    if (existing){
+      return res.json(existing);
+    }
+
+    if (waitSec <= 0){
+      return res.status(204).end();
+    }
+
+    const jobId = await waitForAssignment(services.bus, req.params.id, waitSec);
+    if (!jobId){
+      return res.status(204).end();
+    }
+    res.json(services.jobs.get(jobId));
+  });
+
+  router.post('/jobs/:id/accept', auth, requireOwnJob(services), (req, res, next) => {
+    try {
+      if (req.job.state !== JOB_STATES.ASSIGNED){
+        return res.status(409).json({ error: `Cannot accept job in state ${req.job.state}` });
+      }
+      const job = services.jobs.setState(req.params.id, JOB_STATES.PREPARING);
+      res.json(job);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/jobs/:id/state', auth, requireOwnJob(services), (req, res, next) => {
+    try {
+      const { state, message } = req.body;
+      if (![JOB_STATES.PREPARING, JOB_STATES.RUNNING].includes(state)){
+        return res.status(400).json({ error: 'state must be PREPARING or RUNNING' });
+      }
+      const job = services.jobs.setState(req.params.id, state, { message });
+      res.json(job);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/jobs/:id/logs', auth, requireOwnJob(services), (req, res, next) => {
+    try {
+      const lines = Array.isArray(req.body) ? req.body : req.body.lines;
+      if (!Array.isArray(lines)){
+        return res.status(400).json({ error: 'Expected an array of log lines' });
+      }
+      const inserted = services.logs.appendBatch(req.params.id, lines);
+      res.status(202).json({ accepted: inserted.length });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/jobs/:id/artifacts', auth, requireOwnJob(services), upload.any(), (req, res, next) => {
+    try {
+      const stored = services.artifacts.storeUploaded(req.params.id, req.files || []);
+      res.status(201).json({ artifacts: stored.map((a) => ({ id: a.id, name: a.name, size: a.size })) });
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  router.post('/jobs/:id/result', auth, requireOwnJob(services), (req, res, next) => {
+    try {
+      const { state, exitCode, summary } = req.body,
+        job = services.jobs.applyResult(req.params.id, req.resource.id, { state, exitCode, summary });
+      res.json(job);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  return router;
+}
+
+function waitForAssignment(bus, resourceId, waitSec){
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      bus.off('job.assigned', onAssigned);
+      resolve(null);
+    }, waitSec * 1000);
+
+    function onAssigned(evt){
+      if (evt.resourceId !== resourceId){
+        return;
+      }
+      clearTimeout(timer);
+      bus.off('job.assigned', onAssigned);
+      resolve(evt.jobId);
+    }
+    bus.on('job.assigned', onAssigned);
+  });
+}
+
+module.exports = { createResourceRouter };

package/src/api/sse.js

@@ -0,0 +1,96 @@
+/**
+ * @file        packages/coordinator/src/api/sse.js
+ * @description Server-Sent Events helper: streams a job's log/state/end events, resumable by seq (README §6.4)
+ *
+ * @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 { TERMINAL_JOB_STATES } = require('@andrian.yablonskyy/thub-common');
+
+// §6.4: log / state / end events, resumable via Last-Event-ID (§7: "the
+// Agent reconnects with exponential backoff and resumes from the last seq").
+function attachJobStream(req, res, { jobId, services, config }){
+  const { jobs, logs, registry, bus } = services,
+
+    job = jobs.get(jobId);
+  if (!job){
+    res.status(404).json({ error: 'Unknown job' });
+    return;
+  }
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no'
+  });
+  res.flushHeaders?.();
+
+  const lastEventId = req.get('Last-Event-ID'),
+    afterSeq = Number(lastEventId ?? req.query.after ?? 0) || 0;
+
+  function writeEvent(event, data, id){
+    if (id !== undefined){
+      res.write(`id: ${id}\n`);
+    }
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+  }
+
+  for (const line of logs.listSince(jobId, afterSeq)){
+    writeEvent('log', { ts: line.ts, stream: line.stream, line: line.line }, line.seq);
+  }
+
+  function artifactsUrl(){
+    return `${config.publicUrl}/jobs/${jobId}#artifacts`;
+  }
+
+  const current = jobs.get(jobId);
+  if (TERMINAL_JOB_STATES.has(current.state)){
+    writeEvent('end', { state: current.state, artifactsUrl: artifactsUrl() });
+    return res.end();
+  }
+
+  const resourceName = (id) => (id ? registry.get(id)?.name : undefined);
+  writeEvent('state', { state: current.state, resource: resourceName(current.resource_id) });
+
+  const onLog = (entry) => {
+      if (entry.jobId === jobId){
+        writeEvent('log', { ts: entry.ts, stream: entry.stream, line: entry.line }, entry.seq);
+      }
+    },
+    onState = (evt) => {
+      if (evt.jobId === jobId){
+        writeEvent('state', { state: evt.state, resource: resourceName(evt.resourceId) });
+      }
+    },
+    onFinished = (evt) => {
+      if (evt.jobId !== jobId){
+        return;
+      }
+      writeEvent('end', { state: evt.state, artifactsUrl: artifactsUrl() });
+      cleanup();
+      res.end();
+    };
+
+  function cleanup(){
+    bus.off('job.log', onLog);
+    bus.off('job.state', onState);
+    bus.off('job.finished', onFinished);
+  }
+
+  bus.on('job.log', onLog);
+  bus.on('job.state', onState);
+  bus.on('job.finished', onFinished);
+  req.on('close', cleanup);
+}
+
+module.exports = { attachJobStream };

package/src/auth.js

@@ -0,0 +1,94 @@
+/**
+ * @file        packages/coordinator/src/auth.js
+ * @description Bearer token and admin session authentication/authorization middleware (README §12)
+ *
+ * @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 crypto = require('node:crypto'),
+  { hashToken } = require('./services/tokens');
+
+// §3.1 / §12: bearer tokens are hashed with SHA-256 and carry a role
+// (agent | resource); admin is authenticated via the dashboard session
+// instead of an API token (§10).
+function requireRole(role){
+  return (req, res, next) => {
+    const header = req.headers.authorization || '',
+      [scheme, token] = header.split(' ');
+    if (scheme !== 'Bearer' || !token){
+      return res.status(401).json({ error: 'Missing bearer token' });
+    }
+    const tokenHash = hashToken(token);
+
+    if (role === 'agent'){
+      const agent = req.app.locals.services.agents.getByTokenHash(tokenHash);
+      if (!agent){
+        return res.status(401).json({ error: 'Invalid or revoked agent token' });
+      }
+      req.app.locals.services.agents.touchLastUsed(agent.id);
+      req.agent = agent;
+      return next();
+    }
+
+    if (role === 'resource'){
+      const resource = req.app.locals.services.registry.getByTokenHash(tokenHash);
+      if (!resource){
+        return res.status(401).json({ error: 'Invalid resource token' });
+      }
+      req.resource = resource;
+      return next();
+    }
+
+    return res.status(500).json({ error: `Unknown role ${role}` });
+  };
+}
+
+// Gates self-service Client registration (see api/resource.js). A shared
+// secret rather than a per-resource token, since the whole point is that
+// no admin action is needed to let a new Client in — every Client just
+// carries the same key from its own config/env.
+function requireJoinKey(config){
+  return (req, res, next) => {
+    if (!config.clientJoinKey){
+      return res.status(503).json({ error: 'Coordinator has no clientJoinKey configured; auto-registration is disabled' });
+    }
+    const header = req.headers.authorization || '',
+      [scheme, key] = header.split(' ');
+    if (scheme !== 'Bearer' || !key){
+      return res.status(401).json({ error: 'Missing bearer join key' });
+    }
+    const a = crypto.createHash('sha256').update(key).digest(),
+      b = crypto.createHash('sha256').update(config.clientJoinKey).digest();
+    if (!crypto.timingSafeEqual(a, b)){
+      return res.status(401).json({ error: 'Invalid join key' });
+    }
+    next();
+  };
+}
+
+function requireAdminSession(req, res, next){
+  if (!req.session?.user){
+    if (req.accepts('html')){
+      return res.redirect('/login');
+    }
+    return res.status(401).json({ error: 'Login required' });
+  }
+  next();
+}
+
+function requireAdminRole(req, res, next){
+  if (req.session?.user?.role !== 'admin'){
+    return res.status(403).json({ error: 'Admin role required' });
+  }
+  next();
+}
+
+module.exports = { requireRole, requireJoinKey, requireAdminSession, requireAdminRole };