@andrian.yablonskyy/thub-coordinator 1.0.2 → 1.0.3

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
 {
@@ -40,46 +40,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,10 +1,11 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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",

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;