charness 3.7.0 → 3.9.0

package/dist/runnerUtility/packageId.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageIdOfArchive = getPackageIdOfArchive;
+exports.checkIsPackageId = checkIsPackageId;
+exports.checkArchiveHasId = checkArchiveHasId;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const zlib_1 = require("zlib");
+/**
+ * @description The id of a hub package: the first 16 hex digits of the sha256 of the tar BEFORE compression (`runners/hubPackage.ts`
+ * computes it the same way). Builtins only: the very first step of a pairing, which has no dependencies installed, checks the archive it
+ * downloaded against the id the hub announced with it.
+ */
+const packageIdLength = 16;
+const packageIdPattern = /^[0-9a-f]{16}$/;
+function getPackageIdOfArchive(archive) {
+    return (0, crypto_1.createHash)('sha256').update((0, zlib_1.gunzipSync)(archive)).digest('hex').slice(0, packageIdLength);
+}
+function checkIsPackageId(value) {
+    return packageIdPattern.test(value);
+}
+/** @description Does the archive file hold the package `expectedId` names? An unreadable or damaged archive does not. */
+function checkArchiveHasId(archivePath, expectedId) {
+    try {
+        return checkIsPackageId(expectedId) && getPackageIdOfArchive(fs.readFileSync(archivePath)) === expectedId;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=packageId.js.map

package/dist/runnerUtility/packageId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageId.js","sourceRoot":"","sources":["../../src/runnerUtility/packageId.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,sDAEC;AAED,4CAEC;AAGD,8CAMC;AA5BD,mCAAoC;AACpC,uCAAyB;AACzB,+BAAkC;AAElC;;;;GAIG;AAEH,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAE1C,SAAgB,qBAAqB,CAAC,OAAe;IACnD,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAA,iBAAU,EAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AAClG,CAAC;AAED,SAAgB,gBAAgB,CAAC,KAAa;IAC5C,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,yHAAyH;AACzH,SAAgB,iBAAiB,CAAC,WAAmB,EAAE,UAAkB;IACvE,IAAI,CAAC;QACH,OAAO,gBAAgB,CAAC,UAAU,CAAC,IAAI,qBAAqB,CAAC,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,KAAK,UAAU,CAAC;IAC5G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/runnerUtility/pairArgs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description The one option of `charness-runner pair` that the admin line adds. Builtins only: `runnerCli.ts` reads it before any
+ * dependency is installed, and the hub (`runners/bootstrapLine.ts`) writes it.
+ *
+ * `--service-follows` says that the line which started the pairing installs the always-on service right after it, so the pairing does not
+ * print the «keep it running» help (its commands would be wrong: the service is already on its way).
+ */
+export declare const serviceFollowsFlag = "--service-follows";
+export interface SplitPairArgs {
+    /** The arguments without the flag, in their order. */
+    rest: string[];
+    isServiceFollowing: boolean;
+}
+/** @description Take the flag out of `args` wherever it stands. */
+export declare function splitServiceFollowsFlag(args: readonly string[]): SplitPairArgs;
+//# sourceMappingURL=pairArgs.d.ts.map

package/dist/runnerUtility/pairArgs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairArgs.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/pairArgs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,mEAAmE;AACnE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAE9E"}

package/dist/runnerUtility/pairArgs.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @description The one option of `charness-runner pair` that the admin line adds. Builtins only: `runnerCli.ts` reads it before any
+ * dependency is installed, and the hub (`runners/bootstrapLine.ts`) writes it.
+ *
+ * `--service-follows` says that the line which started the pairing installs the always-on service right after it, so the pairing does not
+ * print the «keep it running» help (its commands would be wrong: the service is already on its way).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceFollowsFlag = void 0;
+exports.splitServiceFollowsFlag = splitServiceFollowsFlag;
+exports.serviceFollowsFlag = '--service-follows';
+/** @description Take the flag out of `args` wherever it stands. */
+function splitServiceFollowsFlag(args) {
+    return { rest: args.filter((argument) => argument !== exports.serviceFollowsFlag), isServiceFollowing: args.includes(exports.serviceFollowsFlag) };
+}
+//# sourceMappingURL=pairArgs.js.map

package/dist/runnerUtility/pairArgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairArgs.js","sourceRoot":"","sources":["../../src/runnerUtility/pairArgs.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAWH,0DAEC;AAXY,QAAA,kBAAkB,GAAG,mBAAmB,CAAC;AAQtD,mEAAmE;AACnE,SAAgB,uBAAuB,CAAC,IAAuB;IAC7D,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,0BAAkB,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAAC,0BAAkB,CAAC,EAAE,CAAC;AACrI,CAAC"}

package/dist/runnerUtility/pairingRecovery.d.ts

@@ -0,0 +1,31 @@
+import { type RedeemReply } from '../runners/gateProtocol';
+import { type HubEndpoint } from './hubClient';
+import type { RunnerKeys } from './runnerKeys';
+/**
+ * @description Getting a pairing back whose answer was lost. The hub commits a redemption — the runner is registered, the code's
+ * temporary key is deleted — BEFORE the runner has the answer and writes `config.json`. If the answer never arrives (the connection
+ * drops, the process dies), the temporary key cannot be used again and a fresh code is refused (the runner's own key is already
+ * registered). What can still ask is the runner's PERMANENT key, so the runner writes `pairing.json` before it redeems and, whenever it
+ * finds that file without a `config.json`, asks the gate for its `identity`: the very answer `redeem` gave. A key the hub does not
+ * know is the other answer — nothing was committed, the half-done pairing is dropped.
+ */
+export type RecoveryOutcome = 
+/** The hub has this runner: here is what `redeem` answered. */
+{
+    kind: 'recovered';
+    reply: Extract<RedeemReply, {
+        ok: true;
+    }>;
+}
+/** The hub does not know this key (or no longer): nothing was committed there. */
+ | {
+    kind: 'not-registered';
+}
+/** The hub could not be asked right now; try again later. */
+ | {
+    kind: 'unreachable';
+    message: string;
+};
+/** @description Ask the hub, with the runner's own key, what it knows of this runner. */
+export declare function recoverPairing(endpoint: HubEndpoint, keys: RunnerKeys): Promise<RecoveryOutcome>;
+//# sourceMappingURL=pairingRecovery.d.ts.map

package/dist/runnerUtility/pairingRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingRecovery.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/pairingRecovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAqD,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;GAOG;AAEH,MAAM,MAAM,eAAe;AACzB,+DAA+D;AAC7D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;CAAE;AAClE,kFAAkF;GAChF;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE;AAC5B,6DAA6D;GAC3D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,yFAAyF;AACzF,wBAAsB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAatG"}

package/dist/runnerUtility/pairingRecovery.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoverPairing = recoverPairing;
+const gateProtocol_1 = require("../runners/gateProtocol");
+const hubClient_1 = require("./hubClient");
+/** @description Ask the hub, with the runner's own key, what it knows of this runner. */
+async function recoverPairing(endpoint, keys) {
+    try {
+        const client = await (0, hubClient_1.connectToHub)(endpoint, keys.client.privateKey);
+        try {
+            const reply = await (0, hubClient_1.requestGateJson)(client, 'identity', null, gateProtocol_1.redeemReplySchema);
+            return reply.ok ? { kind: 'recovered', reply } : { kind: 'not-registered' };
+        }
+        finally {
+            client.end();
+        }
+    }
+    catch (error) {
+        if (error instanceof hubClient_1.HubConnectionError && error.failure === 'auth')
+            return { kind: 'not-registered' };
+        return { kind: 'unreachable', message: error instanceof Error ? error.message : 'could not reach the hub' };
+    }
+}
+//# sourceMappingURL=pairingRecovery.js.map

package/dist/runnerUtility/pairingRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingRecovery.js","sourceRoot":"","sources":["../../src/runnerUtility/pairingRecovery.ts"],"names":[],"mappings":";;AAsBA,wCAaC;AAnCD,0DAA8E;AAC9E,2CAAkG;AAoBlG,yFAAyF;AAClF,KAAK,UAAU,cAAc,CAAC,QAAqB,EAAE,IAAgB;IAC1E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,wBAAY,EAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAA,2BAAe,EAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,gCAAiB,CAAC,CAAC;YACjF,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QAC9E,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,8BAAkB,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QACvG,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,yBAAyB,EAAE,CAAC;IAC9G,CAAC;AACH,CAAC"}

package/dist/runnerUtility/pueueDaemon.d.ts

@@ -0,0 +1,36 @@
+import { type CommandRunner } from '../selfUpdate/commandRunner';
+import type { RunnerHomePaths } from './runnerHome';
+export declare function renderPueueConfig(paths: RunnerHomePaths): string;
+/** @description Write the config (and its folders) when it is missing or differs. */
+export declare function ensurePueueConfig(paths: RunnerHomePaths): void;
+/** @description Is the daemon answering? */
+export declare function checkIsPueueRunning(paths: RunnerHomePaths, runner?: CommandRunner): Promise<boolean>;
+/** @description Start the daemon (daemonized, so it outlives this process) unless it answers; `false` when it could not be started. */
+export declare function ensurePueueDaemon(paths: RunnerHomePaths, runner?: CommandRunner): Promise<boolean>;
+/** @description When a service manages Pueue the link must not start a second daemon: wait (up to `timeoutMs`) for the service's to answer. */
+export declare function waitForPueueDaemon(paths: RunnerHomePaths, timeoutMs: number, runner?: CommandRunner): Promise<boolean>;
+/** What a Pueue daemon on this runner's private socket is doing. */
+export type PueueState = {
+    kind: 'absent';
+} | {
+    kind: 'idle';
+} | {
+    kind: 'busy';
+    activeJobs: number;
+} | {
+    kind: 'unreadable';
+};
+/** @description The tasks of `pueue status --json` that hold a process — `Running` and `Paused` — or `null` when the text is not that. */
+export declare function countActivePueueTasks(statusJson: string): number | null;
+/** @description Is a daemon answering on the runner's socket, and does it hold running jobs? */
+export declare function inspectPueue(paths: RunnerHomePaths, runner?: CommandRunner): Promise<PueueState>;
+/** @description Ask a daemon that no service manager owns to shut down, and wait for it to go. Pueue kills the jobs it runs when it stops: only for an IDLE one. */
+export declare function shutDownPueue(paths: RunnerHomePaths, runner?: CommandRunner): Promise<boolean>;
+/**
+ * @description Stop every job of the queue and empty it (`pueue reset --force`: it kills the running tasks and their children and removes the
+ * rest, so no queued task starts in their place), then wait until nothing is left running. `true` also when no daemon answers (its jobs died
+ * with it). The reset only ASKS: Pueue 4 answers at once and its task handler kills the tasks a moment later, so one look right after the
+ * command would still see them `Running` — it looks again, until `settleTimeoutMs` is over.
+ */
+export declare function stopAllPueueJobs(paths: RunnerHomePaths, runner?: CommandRunner, settleTimeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=pueueDaemon.d.ts.map

package/dist/runnerUtility/pueueDaemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pueueDaemon.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/pueueDaemon.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAWhE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAW9D;AAED,4CAA4C;AAC5C,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,aAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtH;AAED,uIAAuI;AACvI,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,aAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAKpH;AAED,+IAA+I;AAC/I,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,aAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAQxI;AAED,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B,0IAA0I;AAC1I,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWvE;AAED,gGAAgG;AAChG,wBAAsB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,aAA0B,GAAG,OAAO,CAAC,UAAU,CAAC,CAMlH;AAED,oKAAoK;AACpK,wBAAsB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,aAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhH;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,aAA0B,EAAE,eAAe,GAAE,MAA6B,GAAG,OAAO,CAAC,OAAO,CAAC,CAUnK"}

package/dist/runnerUtility/pueueDaemon.js

@@ -0,0 +1,165 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPueueConfig = renderPueueConfig;
+exports.ensurePueueConfig = ensurePueueConfig;
+exports.checkIsPueueRunning = checkIsPueueRunning;
+exports.ensurePueueDaemon = ensurePueueDaemon;
+exports.waitForPueueDaemon = waitForPueueDaemon;
+exports.countActivePueueTasks = countActivePueueTasks;
+exports.inspectPueue = inspectPueue;
+exports.shutDownPueue = shutDownPueue;
+exports.stopAllPueueJobs = stopAllPueueJobs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const configDirFile_1 = require("../configDirFile");
+const commandRunner_1 = require("../selfUpdate/commandRunner");
+/**
+ * @description The runner's private Pueue: its config under `~/.charness-runner/pueue/` (own directories and unix socket — never the
+ * account's default Pueue), and a daemon that is started if it is not running. Pueue is a service of its own: stopping or restarting the
+ * link never touches the queue or a running job.
+ */
+const probeTimeoutMs = 5000;
+const daemonStartTimeoutMs = 15 * 1000;
+const configMode = 0o600;
+const pueueWaitPollMs = 500;
+function renderPueueConfig(paths) {
+    const runtimeDir = path.join(paths.pueueDir, 'run');
+    return [
+        'shared:',
+        `  pueue_directory: ${path.join(paths.pueueDir, 'data')}`,
+        `  runtime_directory: ${runtimeDir}`,
+        '  use_unix_socket: true',
+        `  unix_socket_path: ${path.join(runtimeDir, 'pueue.socket')}`,
+        `  pid_path: ${path.join(runtimeDir, 'pueue.pid')}`,
+        '',
+    ].join('\n');
+}
+/** @description Write the config (and its folders) when it is missing or differs. */
+function ensurePueueConfig(paths) {
+    fs.mkdirSync(path.join(paths.pueueDir, 'run'), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(path.join(paths.pueueDir, 'data'), { recursive: true, mode: 0o700 });
+    const text = renderPueueConfig(paths);
+    let current = null;
+    try {
+        current = fs.readFileSync(paths.pueueConfig, 'utf8');
+    }
+    catch {
+        current = null;
+    }
+    if (current !== text)
+        (0, configDirFile_1.writeTextFileAtomically)(paths.pueueConfig, text, configMode);
+}
+/** @description Is the daemon answering? */
+async function checkIsPueueRunning(paths, runner = commandRunner_1.runCommand) {
+    const result = await runner(path.join(paths.binDir, 'pueue'), ['--config', paths.pueueConfig, 'status'], { timeoutMs: probeTimeoutMs });
+    return result.ok;
+}
+/** @description Start the daemon (daemonized, so it outlives this process) unless it answers; `false` when it could not be started. */
+async function ensurePueueDaemon(paths, runner = commandRunner_1.runCommand) {
+    ensurePueueConfig(paths);
+    if (await checkIsPueueRunning(paths, runner))
+        return true;
+    const started = await runner(path.join(paths.binDir, 'pueued'), ['--daemonize', '--config', paths.pueueConfig], { timeoutMs: daemonStartTimeoutMs });
+    return started.ok && await checkIsPueueRunning(paths, runner);
+}
+/** @description When a service manages Pueue the link must not start a second daemon: wait (up to `timeoutMs`) for the service's to answer. */
+async function waitForPueueDaemon(paths, timeoutMs, runner = commandRunner_1.runCommand) {
+    ensurePueueConfig(paths);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await checkIsPueueRunning(paths, runner))
+            return true;
+        await new Promise((resolve) => { setTimeout(resolve, pueueWaitPollMs); });
+    }
+    return false;
+}
+/** @description The tasks of `pueue status --json` that hold a process — `Running` and `Paused` — or `null` when the text is not that. */
+function countActivePueueTasks(statusJson) {
+    try {
+        const parsed = JSON.parse(statusJson);
+        if (parsed.tasks === undefined)
+            return null;
+        return Object.values(parsed.tasks).filter((task) => {
+            const status = typeof task.status === 'string' ? [task.status] : Object.keys(task.status ?? {});
+            return status.includes('Running') || status.includes('Paused');
+        }).length;
+    }
+    catch {
+        return null;
+    }
+}
+/** @description Is a daemon answering on the runner's socket, and does it hold running jobs? */
+async function inspectPueue(paths, runner = commandRunner_1.runCommand) {
+    const result = await runner(path.join(paths.binDir, 'pueue'), ['--config', paths.pueueConfig, 'status', '--json'], { timeoutMs: probeTimeoutMs });
+    if (!result.ok)
+        return { kind: 'absent' };
+    const activeJobs = countActivePueueTasks(result.stdout);
+    if (activeJobs === null)
+        return { kind: 'unreadable' };
+    return activeJobs === 0 ? { kind: 'idle' } : { kind: 'busy', activeJobs };
+}
+/** @description Ask a daemon that no service manager owns to shut down, and wait for it to go. Pueue kills the jobs it runs when it stops: only for an IDLE one. */
+async function shutDownPueue(paths, runner = commandRunner_1.runCommand) {
+    await runner(path.join(paths.binDir, 'pueue'), ['--config', paths.pueueConfig, 'shutdown'], { timeoutMs: probeTimeoutMs });
+    const deadline = Date.now() + daemonStartTimeoutMs;
+    while (Date.now() < deadline) {
+        if (!(await checkIsPueueRunning(paths, runner)))
+            return true;
+        await new Promise((resolve) => { setTimeout(resolve, pueueWaitPollMs); });
+    }
+    return false;
+}
+/**
+ * @description Stop every job of the queue and empty it (`pueue reset --force`: it kills the running tasks and their children and removes the
+ * rest, so no queued task starts in their place), then wait until nothing is left running. `true` also when no daemon answers (its jobs died
+ * with it). The reset only ASKS: Pueue 4 answers at once and its task handler kills the tasks a moment later, so one look right after the
+ * command would still see them `Running` — it looks again, until `settleTimeoutMs` is over.
+ */
+async function stopAllPueueJobs(paths, runner = commandRunner_1.runCommand, settleTimeoutMs = daemonStartTimeoutMs) {
+    if ((await inspectPueue(paths, runner)).kind === 'absent')
+        return true;
+    await runner(path.join(paths.binDir, 'pueue'), ['--config', paths.pueueConfig, 'reset', '--force'], { timeoutMs: daemonStartTimeoutMs });
+    const deadline = Date.now() + settleTimeoutMs;
+    for (;;) {
+        const after = await inspectPueue(paths, runner);
+        if (after.kind === 'absent' || after.kind === 'idle')
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => { setTimeout(resolve, pueueWaitPollMs); });
+    }
+}
+//# sourceMappingURL=pueueDaemon.js.map

package/dist/runnerUtility/pueueDaemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pueueDaemon.js","sourceRoot":"","sources":["../../src/runnerUtility/pueueDaemon.ts"],"names":[],"mappings":"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"}

package/dist/runnerUtility/rootServiceCli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `rootServiceCli.js install <account>` — the root step of the admin pairing line (`runners/bootstrapLine.ts`), run by it from a copy of
+ * the package that root unpacked into a folder of its own. Node built-ins only (that copy has no `node_modules`), and it never reads or
+ * runs anything from the account's home but through `sudo -u <account>` (see `adminService.ts`).
+ */
+export {};
+//# sourceMappingURL=rootServiceCli.d.ts.map

package/dist/runnerUtility/rootServiceCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rootServiceCli.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/rootServiceCli.ts"],"names":[],"mappings":";AAEA;;;;GAIG"}

package/dist/runnerUtility/rootServiceCli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `rootServiceCli.js install <account>` — the root step of the admin pairing line (`runners/bootstrapLine.ts`), run by it from a copy of
+ * the package that root unpacked into a folder of its own. Node built-ins only (that copy has no `node_modules`), and it never reads or
+ * runs anything from the account's home but through `sudo -u <account>` (see `adminService.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const adminService_1 = require("./adminService");
+const usageExitCode = 2;
+async function main() {
+    const [command, account, ...rest] = process.argv.slice(2);
+    if (command !== 'install' || account === undefined || rest.length > 0) {
+        process.stderr.write('Usage: rootServiceCli.js install <account>\n');
+        return usageExitCode;
+    }
+    const result = await (0, adminService_1.installServiceForAccount)(account, (0, adminService_1.createAdminServiceDeps)());
+    if (result.lines.length > 0)
+        (result.ok ? process.stdout : process.stderr).write(`${result.lines.join('\n')}\n`);
+    return result.ok ? 0 : 1;
+}
+// Only when this file IS the program (`node <copy>/rootServiceCli.js install <account>`): importing it, as the self-check does, installs nothing.
+if (require.main === module) {
+    main().then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        process.stderr.write(`charness-runner: ${error.message}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=rootServiceCli.js.map

package/dist/runnerUtility/rootServiceCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rootServiceCli.js","sourceRoot":"","sources":["../../src/runnerUtility/rootServiceCli.ts"],"names":[],"mappings":";;AAEA;;;;GAIG;;AAEH,iDAAkF;AAElF,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QACrE,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAA,uCAAwB,EAAC,OAAO,EAAE,IAAA,qCAAsB,GAAE,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjH,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED,kJAAkJ;AAClJ,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;QACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC,EACD,CAAC,KAAY,EAAE,EAAE;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/runnerUtility/runnerCli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * `charness-runner` — the program that attaches a machine to a charness hub as a runner (see `src/runners/README.md` for the hub side
+ * and `src/runnerUtility/README.md` for this one).
+ *
+ *   charness-runner                        what this account is attached to and what the link is doing (= `status`)
+ *   charness-runner pair <code>            attach this account with a pairing code (the line from /runners does it for you)
+ *   charness-runner run                    hold the link to the hub; Ctrl-C stops (a service does the same, see the pairing text)
+ *   charness-runner check                  look at this machine and install what a runner needs (Pueue, rsync)
+ *   charness-runner service install        keep it running without a terminal (see `serviceManager.ts`)
+ *   charness-runner pause | resume | unpair
+ *
+ * This file is the FIRST thing a pairing runs, from a package that has no `node_modules` yet (`pair --bootstrap <folder> <code>`,
+ * started by the pasted line): it imports Node built-ins only, installs the package's dependencies into a new app folder, and starts
+ * the installed copy to do the pairing. Everything else is loaded after that, on demand.
+ */
+export {};
+//# sourceMappingURL=runnerCli.d.ts.map

package/dist/runnerUtility/runnerCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerCli.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/runnerCli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG"}