@andrian.yablonskyy/thub-coordinator 1.0.2 → 1.0.4

package/README.md

@@ -7,14 +7,14 @@ See the [main TestHub repo](https://github.com/andrianyablonskyy/thub) for the f
 ## Install
 
 ```bash
-npm install @andrian.yablonskyy/thub-coordinator
+npm install -g @andrian.yablonskyy/thub-coordinator
 ```
 
-Or clone this repo directly and run it from source (see below).
+This gives you two global commands: `thub-coordinator` (the server itself) and `thub-admin` (the local operator CLI, below). Or clone this repo directly and run it from source (see below).
 
 ## Configuration
 
-The Coordinator loads a plain **JSON** config file (no YAML support). Resolution order, first match wins: `THUB_COORDINATOR_CONFIG` env var path → the bundled `config.json` default. There is no other automatic fallback path — a real deployment always sets `THUB_COORDINATOR_CONFIG` explicitly.
+The Coordinator loads a plain **JSON** config file (no YAML support). Resolution order, first match wins: `THUB_COORDINATOR_CONFIG` env var path → `~/.config/thub/coordinator.json` → the bundled `config.json` default.
 
 ```json
 {
@@ -33,6 +33,8 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
 
 `sessionSecret` signs the dashboard's session cookie and the HMAC on artifact download links; `clientJoinKey` is the shared secret Clients self-register with — omit or leave `null` to disable auto-registration entirely. Individual `THUB_LISTEN` / `THUB_PUBLIC_URL` / `THUB_DATA_DIR` / `THUB_SESSION_SECRET` / `THUB_CLIENT_JOIN_KEY` env vars override whatever the file set.
 
+`npm install -g` creates `~/.config/thub/coordinator.json` for you if it doesn't already exist, with a home-anchored `dataDir` and a freshly generated random `sessionSecret` (not the placeholder above) — a re-install never overwrites it or regenerates the secret. Set `publicUrl` and `clientJoinKey` yourself before relying on auto-registration.
+
 ## Running it
 
 ```bash
@@ -40,46 +42,46 @@ The Coordinator loads a plain **JSON** config file (no YAML support). Resolution
 # password (creates user "admin") or use thub-admin afterwards.
 THUB_COORDINATOR_CONFIG=/etc/thub/coordinator.json \
 THUB_BOOTSTRAP_ADMIN_PASSWORD=correct-horse-battery-staple \
-node src/server.js
+thub-coordinator
 # -> Reset password for admin user "admin" from THUB_BOOTSTRAP_ADMIN_PASSWORD
 # -> TestHub Coordinator listening on http://127.0.0.1:8080
 ```
 
-`THUB_BOOTSTRAP_ADMIN_PASSWORD` is more than a first-run convenience — it's an **exceptional password reset**, checked on every startup, not only when `admin_users` is empty. Whenever it's set, the named account (`THUB_BOOTSTRAP_ADMIN_USER`, default `admin`) has its password forced to it — creating that user as `admin` if it doesn't exist yet, or just resetting the password (never the role) if it does. With it unset, login uses whatever's already in the DB, as normal — unset it again once you're back in, or every subsequent restart re-applies it.
+`thub-coordinator` is the global command from `npm install -g`; from a local checkout of this repo it's `node src/server.js` or `npm start`/`npm run dev` (auto-restart on change) — all equivalent, all reading config the same way (above).
 
-Or just `npm start` / `npm run dev` (auto-restart on change) against the bundled `config.json` default for local development.
+`THUB_BOOTSTRAP_ADMIN_PASSWORD` is more than a first-run convenience — it's an **exceptional password reset**, checked on every startup, not only when `admin_users` is empty. Whenever it's set, the named account (`THUB_BOOTSTRAP_ADMIN_USER`, default `admin`) has its password forced to it — creating that user as `admin` if it doesn't exist yet, or just resetting the password (never the role) if it does. With it unset, login uses whatever's already in the DB, as normal — unset it again once you're back in, or every subsequent restart re-applies it.
 
 ## `thub-admin` — the local operator CLI
 
-Talks to the Coordinator's SQLite database directly — no running server required, and no HTTP auth of its own, so it's meant to be run on the Coordinator host itself:
+Talks to the Coordinator's SQLite database directly — no running server required, and no HTTP auth of its own, so it's meant to be run on the Coordinator host itself. `thub-admin` is the global command from `npm install -g`; from a local checkout it's `node bin/thub-admin.js`:
 
 ```bash
 # Create additional dashboard users (first one can also come from
 # THUB_BOOTSTRAP_ADMIN_PASSWORD above).
-node bin/thub-admin.js create-admin alice s3cret --role admin
+thub-admin create-admin alice s3cret --role admin
 
 # Register a CI or developer identity — the only credential still issued
 # by an admin; the token is shown once.
-node bin/thub-admin.js agent add ci-firmware --kind ci
+thub-admin agent add ci-firmware --kind ci
 # -> Agent agt_... created. Token (shown once): agt_...
 
 # Mint the shared secret Clients use to self-register, and put it in both
 # the Coordinator's clientJoinKey and every Client's joinKey.
-node bin/thub-admin.js join-key generate
+thub-admin join-key generate
 
 # Take a resource out of rotation without an active job (or bring it back).
-node bin/thub-admin.js resource maintenance res_abc123 --on
+thub-admin resource maintenance res_abc123 --on
 
 # Cancel every queued/assigned/preparing/running job.
-node bin/thub-admin.js jobs reset --yes
+thub-admin jobs reset --yes
 
 # Permanently delete every finished job, plus its logs and artifacts on disk.
-node bin/thub-admin.js jobs clean --yes
+thub-admin jobs clean --yes
 
 # Resource groups: constrain which resources a job can schedule onto.
-node bin/thub-admin.js group add ci-nightly --comment "shared CI pool"
-node bin/thub-admin.js group list
-node bin/thub-admin.js group remove <groupId>
+thub-admin group add ci-nightly --comment "shared CI pool"
+thub-admin group list
+thub-admin group remove <groupId>
 ```
 
 Both `jobs reset` and `jobs clean` refuse to run without `--yes` — there's no undo for either, especially `clean`.

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "bin": {
-    "thub-admin": "./bin/thub-admin.js"
+    "thub-admin": "./bin/thub-admin.js",
+    "thub-coordinator": "./src/server.js"
   },
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
     "test": "node --test test/*.test.js",
+    "postinstall": "node scripts/install-default-config.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },

package/scripts/install-default-config.js

@@ -0,0 +1,74 @@
+/**
+ * @file        scripts/install-default-config.js
+ * @description npm postinstall: creates ~/.config/thub/coordinator.json on a real global install,
+ *              if it doesn't already exist, with a freshly generated sessionSecret rather than a
+ *              shared placeholder — so every real installation isn't using the same known secret
+ *              for its session cookies and artifact-download HMACs (README §12, §13)
+ *
+ * @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'),
+  os = require('node:os'),
+  path = require('node:path'),
+  crypto = require('node:crypto'),
+
+  CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'coordinator.json');
+
+// npm only sets this for an actual `npm install -g` — absent for a plain
+// local/workspace install (e.g. this monorepo's own `npm install`).
+function isGlobalInstall(){
+  return process.env.npm_config_global === 'true';
+}
+
+// Deliberately minimal, not a copy of the bundled config.json (which uses
+// a relative dataDir and a fixed sessionSecret for zero-setup `npm run
+// coordinator` in the monorepo — fine there since it's never a real
+// deployment). loadConfig()'s own DEFAULTS already cover everything else
+// (listen, publicUrl, heartbeat/scheduler/jobs/retention/artifacts), so
+// only what genuinely needs to differ for a real standalone install goes
+// here:
+//   - dataDir: home-anchored, not cwd-relative — a real install shouldn't
+//     silently get a different data directory depending on which
+//     directory you happened to launch thub-coordinator from.
+//   - sessionSecret: freshly random per install. The code's own default
+//     ("dev-only-change-me") is fine for local dev but would otherwise
+//     mean every real installation nobody got around to changing shares
+//     the exact same session-signing key.
+//   - clientJoinKey stays unset (null, the code's own default) — auto-
+//     registration is opt-in, and there's nothing sensible to
+//     auto-generate here since it also has to be copied to every Client.
+function defaultContent(){
+  return {
+    dataDir: path.join(os.homedir(), '.local', 'share', 'thub'),
+    sessionSecret: crypto.randomBytes(32).toString('hex')
+  };
+}
+
+// Best-effort and never fails the `npm install` itself. Never overwrites
+// an existing file — a re-install/upgrade must not clobber whatever the
+// user already configured, and must never regenerate sessionSecret out
+// from under a running deployment (that would invalidate every session).
+function main(){
+  if (!isGlobalInstall() || fs.existsSync(CONFIG_PATH)){
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(defaultContent(), null, 2) + '\n', { mode: 0o600 });
+    console.log(`thub-coordinator: created ${CONFIG_PATH} with a freshly generated sessionSecret`);
+  }
+  catch (err){
+    console.warn(`thub-coordinator: could not create ${CONFIG_PATH} automatically (${err.message}).`);
+  }
+}
+
+main();

package/src/config.js

@@ -14,11 +14,10 @@
 'use strict';
 
 const fs = require('node:fs'),
+  os = require('node:os'),
   path = require('node:path');
 
-// Defaults mirror README.md §13. Unlike the Client (config.js there), there
-// is no FHS-path fallback here — a real deployment must set
-// THUB_COORDINATOR_CONFIG explicitly to override the bundled default below.
+// Defaults mirror README.md §13.
 const DEFAULTS = {
   listen: '127.0.0.1:8080',
   publicUrl: 'http://localhost:8080',
@@ -63,13 +62,17 @@ function deepMerge(base, override){
   return out;
 }
 
-// Bundled with the package so the Coordinator has something sane to run
-// with out of the box; a real deployment overrides it with
-// THUB_COORDINATOR_CONFIG or /srv/thub/coordinator.json (§13).
-const PACKAGE_DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
+// User-level default (§13) — consulted when THUB_COORDINATOR_CONFIG isn't
+// set, before falling back to the bundled default below.
+const USER_CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'coordinator.json'),
+
+  // Bundled with the package so the Coordinator has something sane to run
+  // with out of the box; a real deployment overrides it with
+  // THUB_COORDINATOR_CONFIG or ~/.config/thub/coordinator.json (§13).
+  PACKAGE_DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
 
 function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
-  const candidate = [configPath, PACKAGE_DEFAULT_CONFIG_PATH].find(
+  const candidate = [configPath, USER_CONFIG_PATH, PACKAGE_DEFAULT_CONFIG_PATH].find(
       (p) => p && fs.existsSync(p)
     ),
     fileConfig = candidate ? JSON.parse(fs.readFileSync(candidate, 'utf8')) || {} : {},

package/src/server.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 /**
  * @file        packages/coordinator/src/server.js
  * @description Coordinator entry point: wires services, mounts routes, and starts the HTTP server
@@ -162,7 +164,7 @@ function ensureBootstrapAdmin(services){
     if (services.adminUsers.count() === 0){
       console.warn(
         'No admin_users exist and THUB_BOOTSTRAP_ADMIN_PASSWORD is not set — ' +
-          'create one with: node bin/thub-admin.js create-admin <user> <password>'
+          'create one with: thub-admin create-admin <user> <password> (or node bin/thub-admin.js ... from a checkout)'
       );
     }
     return;