charness 3.7.0 → 3.9.0

package/dist/runners/hubPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubPaths.d.ts","sourceRoot":"","sources":["../../src/runners/hubPaths.ts"],"names":[],"mappings":"AAeA,8GAA8G;AAC9G,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,sIAAsI;IACtI,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qHAAqH;AACrH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAOD,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,SAAS,GAAE,OAAO,CAAC,UAAU,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAWvG;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAYzD;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAGjF;AAED,0HAA0H;AAC1H,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/runners/hubPaths.js

@@ -0,0 +1,96 @@
+"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.getHandMadeRunnersPath = getHandMadeRunnersPath;
+exports.createHubContext = createHubContext;
+exports.getHubFilePaths = getHubFilePaths;
+exports.getRunnerLinkPaths = getRunnerLinkPaths;
+exports.getRunnerHostAlias = getRunnerHostAlias;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+/**
+ * @description Where the hub keeps what paired runners need. ONE folder per OS user — `~/.config/charness/runners/`, beside the
+ * hand-made `runners.json` — and every `authorized_keys` line NAMES it (`gate --dir <dir>`), so nothing the gate does depends on
+ * `$HOME`, `DATA_DIR` or which instance runs it: any charness instance of the user, the bot and the CLI alike, shares one registry.
+ */
+const runnersDirName = 'runners';
+const sshDirName = '.ssh';
+const authorizedKeysFileName = 'authorized_keys';
+const cliFileName = 'cli.js';
+/** @description The hand-made `runners.json` that sits beside the registry folder (see {@link createHubContext}). */
+function getHandMadeRunnersPath(dir) {
+    return path.join(path.dirname(dir), 'runners.json');
+}
+/** @description `dist/cli.js` of the running charness: this file is `dist/runners/hubPaths.js`. */
+function getOwnCliPath() {
+    return path.resolve(__dirname, '..', cliFileName);
+}
+/** @description The context of the real machine for `homeDir`; every field can be overridden. */
+function createHubContext(overrides = {}) {
+    const homeDir = overrides.homeDir ?? os.homedir();
+    const cliPath = overrides.cliPath ?? getOwnCliPath();
+    return {
+        dir: overrides.dir ?? path.join(path.dirname((0, runnersConfig_1.getRunnersConfigPath)(homeDir)), runnersDirName),
+        authorizedKeysPath: overrides.authorizedKeysPath ?? path.join(homeDir, sshDirName, authorizedKeysFileName),
+        nodePath: overrides.nodePath ?? process.execPath,
+        cliPath,
+        packageRoot: overrides.packageRoot ?? path.resolve(path.dirname(cliPath), '..'),
+        log: overrides.log ?? ((line) => { console.warn(`[runners] ${line}`); }),
+    };
+}
+function getHubFilePaths(dir) {
+    return {
+        paired: path.join(dir, 'paired.json'),
+        pending: path.join(dir, 'pending.json'),
+        closed: path.join(dir, 'closed.json'),
+        hubKey: path.join(dir, 'hub_ed25519'),
+        hubPublicKey: path.join(dir, 'hub_ed25519.pub'),
+        knownHosts: path.join(dir, 'known_hosts'),
+        gate: path.join(dir, 'gate'),
+        linkDir: path.join(dir, 'link'),
+        packageDir: path.join(dir, 'package'),
+    };
+}
+/** @description The socket the gate of runner `runnerId` listens on, and the file that says who holds it. */
+function getRunnerLinkPaths(dir, runnerId) {
+    const linkDir = getHubFilePaths(dir).linkDir;
+    return { socket: path.join(linkDir, `${runnerId}.sock`), state: path.join(linkDir, `${runnerId}.json`) };
+}
+/** @description The host alias of a runner in the hub's `known_hosts` (and the `HostKeyAlias` of the ssh calls to it). */
+function getRunnerHostAlias(runnerId) {
+    return `charness-runner-${runnerId}`;
+}
+//# sourceMappingURL=hubPaths.js.map

package/dist/runners/hubPaths.js.map

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

package/dist/runners/hubRegistry.d.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { type HubContext } from './hubPaths';
+/** @description How the runner utility says it is kept running (reported at pairing). */
+export declare const runnerServiceKinds: readonly ["foreground", "user-service", "system-service", "unknown"];
+export type RunnerServiceKind = (typeof runnerServiceKinds)[number];
+declare const pairedRunnerSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    publicKey: z.ZodString;
+    keyFingerprint: z.ZodString;
+    hostKey: z.ZodString;
+    workDir: z.ZodString;
+    os: z.ZodString;
+    arch: z.ZodString;
+    version: z.ZodString;
+    serviceKind: z.ZodEnum<{
+        unknown: "unknown";
+        foreground: "foreground";
+        "user-service": "user-service";
+        "system-service": "system-service";
+    }>;
+    pairedAtMs: z.ZodNumber;
+    pairId: z.ZodString;
+    label: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    isPaused: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const pairedFileSchema: z.ZodObject<{
+    rev: z.ZodNumber;
+    runners: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        publicKey: z.ZodString;
+        keyFingerprint: z.ZodString;
+        hostKey: z.ZodString;
+        workDir: z.ZodString;
+        os: z.ZodString;
+        arch: z.ZodString;
+        version: z.ZodString;
+        serviceKind: z.ZodEnum<{
+            unknown: "unknown";
+            foreground: "foreground";
+            "user-service": "user-service";
+            "system-service": "system-service";
+        }>;
+        pairedAtMs: z.ZodNumber;
+        pairId: z.ZodString;
+        label: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        isPaused: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const pendingPairingSchema: z.ZodObject<{
+    pairId: z.ZodString;
+    publicKey: z.ZodString;
+    keyFingerprint: z.ZodString;
+    expiresAtMs: z.ZodNumber;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    label: z.ZodString;
+    messageRef: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+declare const pendingFileSchema: z.ZodObject<{
+    pending: z.ZodArray<z.ZodObject<{
+        pairId: z.ZodString;
+        publicKey: z.ZodString;
+        keyFingerprint: z.ZodString;
+        expiresAtMs: z.ZodNumber;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        label: z.ZodString;
+        messageRef: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const closedCodeSchema: z.ZodObject<{
+    pairId: z.ZodString;
+    closedAtMs: z.ZodNumber;
+}, z.core.$strict>;
+/** @name PairedRunner @description One attached machine. */
+export type PairedRunner = z.infer<typeof pairedRunnerSchema>;
+/** @name PairedFile @description `paired.json`. */
+export type PairedFile = z.infer<typeof pairedFileSchema>;
+/** @name PendingPairing @description One pairing code that is out. */
+export type PendingPairing = z.infer<typeof pendingPairingSchema>;
+/** @name PendingFile @description `pending.json`. */
+export type PendingFile = z.infer<typeof pendingFileSchema>;
+/** @name ClosedCode @description A pairing code that was closed unused, and when. */
+export type ClosedCode = z.infer<typeof closedCodeSchema>;
+/** @name ClosedCodesRead @description What `closed.json` holds, and — when it could not be used — why (the caller says it, once). */
+export interface ClosedCodesRead {
+    codes: ClosedCode[];
+    problem: string | null;
+}
+export declare class HubRegistryError extends Error {
+    constructor(message: string);
+}
+/** @description The registry files were written but a file derived from them could not be; the next locked operation repairs it. */
+export declare class HubDerivedFilesError extends HubRegistryError {
+    constructor(fileName: string, errnoCode: string);
+}
+/** @description `paired.json` right now (missing = nobody paired). */
+export declare function readPairedFile(dir: string): PairedFile;
+/** @description `pending.json` right now (missing = no code out). */
+export declare function readPendingFile(dir: string): PendingFile;
+/**
+ * @description `closed.json` right now: its codes, or none — with the problem named — when it cannot be read or does not validate. A trace
+ * must never stop the caller, so unlike the registry files this does not throw; the caller says the problem once.
+ */
+export declare function readClosedCodes(dir: string): ClosedCodesRead;
+/**
+ * @description Note that the code `pairId` was closed at `nowMs` (the newest {@link maxClosedCodes} are kept); the registry lock must be held. BEST
+ * EFFORT: a trace that cannot be written is said through `ctx.log` and costs only the nicer text («this line was used on a machine that was
+ * already paired» reads «expired»), never the closing it describes. A file that cannot be used is replaced.
+ */
+export declare function recordClosedCode(ctx: HubContext, pairId: string, nowMs: number): void;
+/** @description Write `paired.json`; the registry lock must be held. */
+export declare function writePairedFile(dir: string, file: PairedFile): void;
+/** @description Write `pending.json`; the registry lock must be held. */
+export declare function writePendingFile(dir: string, file: PendingFile): void;
+/** @description The `known_hosts` text for the ssh calls through the links: one line per runner, under its alias. */
+export declare function renderKnownHosts(runners: readonly PairedRunner[]): string;
+/** @description The lines of the managed `authorized_keys` block: every pairing code still open, then every paired runner. */
+export declare function renderManagedBlockLines(ctx: HubContext, pending: readonly PendingPairing[], runners: readonly PairedRunner[], nowMs: number): string[];
+/**
+ * @description Bring the derived files in line with the two registry files: `known_hosts` and the `authorized_keys` block, each written
+ * only when it differs, and the link files of runners that are no longer registered deleted. The registry lock must be held. The block goes LAST, so a key is never allowed before the files its gate reads
+ * are in place. The registry files are authoritative and are written BEFORE this runs; a failure here is reported as
+ * {@link HubDerivedFilesError} and mends itself, because every locked operation ends with this same call.
+ */
+export declare function syncDerivedHubFiles(ctx: HubContext, pending: PendingFile, paired: PairedFile, nowMs: number): void;
+export {};
+//# sourceMappingURL=hubRegistry.d.ts.map

package/dist/runners/hubRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubRegistry.d.ts","sourceRoot":"","sources":["../../src/runners/hubRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA4BlF,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,sEAAuE,CAAC;AACvG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;kBAsBtB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;kBAI3B,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;;;;;;;kBAYxB,CAAC;AAEH,QAAA,MAAM,iBAAiB;;;;;;;;;;;kBAA6D,CAAC;AAErF,QAAA,MAAM,gBAAgB;;;kBAAsF,CAAC;AAK7G,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,qIAAqI;AACrI,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,oIAAoI;AACpI,qBAAa,oBAAqB,SAAQ,gBAAgB;gBAC5C,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAIhD;AAqBD,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAEtD;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAExD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAO5D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CASrF;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAGnE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAGrE;AAED,qHAAqH;AACrH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAEzE;AAED,8HAA8H;AAC9H,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtJ;AAUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAelH"}

package/dist/runners/hubRegistry.js

@@ -0,0 +1,256 @@
+"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.HubDerivedFilesError = exports.HubRegistryError = exports.pairedFileSchema = exports.runnerServiceKinds = void 0;
+exports.readPairedFile = readPairedFile;
+exports.readPendingFile = readPendingFile;
+exports.readClosedCodes = readClosedCodes;
+exports.recordClosedCode = recordClosedCode;
+exports.writePairedFile = writePairedFile;
+exports.writePendingFile = writePendingFile;
+exports.renderKnownHosts = renderKnownHosts;
+exports.renderManagedBlockLines = renderManagedBlockLines;
+exports.syncDerivedHubFiles = syncDerivedHubFiles;
+const fs = __importStar(require("fs"));
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+const authorizedKeys_1 = require("./authorizedKeys");
+const hubIds_1 = require("./hubIds");
+const hubPaths_1 = require("./hubPaths");
+const hubLock_1 = require("./hubLock");
+const linkControl_1 = require("./linkControl");
+const configDirFile_2 = require("../configDirFile");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The hub's registry files and what is derived from them. `paired.json` is the machines that are attached,
+ * `pending.json` the pairing codes that are out. Both are read freely (every write is a rename, a reader sees a whole file) and
+ * written only under the registry lock (`hubLock.ts`). `known_hosts` (the runners' host keys, for the ssh calls through the link)
+ * and the managed `authorized_keys` block are DERIVED from the two on every change — never edited on their own.
+ *
+ * A file that does not parse or validate stops the caller with the problem named (field and rule, no values): a registry that is
+ * silently treated as empty would be rewritten empty and lose every pairing.
+ *
+ * `closed.json` is the odd one out: a TRACE, not part of the registry's truth — the codes that were closed unused, so a code that was
+ * closed (its line was pasted for a machine that was already paired) can be told from one that ran out. Nothing depends on it for
+ * correctness, so it is read leniently (a file that cannot be used reads as none, and the problem is handed to the caller to say once) and
+ * its write never blocks the close it describes. It is a file of its own, not a field of a pending entry: the sweep drops pending entries
+ * at expiry, which would lose the trace for an instance that was down, and every reader of the pending list would have to honour it.
+ */
+const registryFileMode = 0o600;
+const knownHostsMode = 0o644;
+const maxTextLength = 200;
+const publicKeySchema = zod_1.z.string().refine(sshKeys_1.checkIsEd25519PublicKey, 'must be an ed25519 public key (type and key, no comment)');
+/** @description How the runner utility says it is kept running (reported at pairing). */
+exports.runnerServiceKinds = ['foreground', 'user-service', 'system-service', 'unknown'];
+const pairedRunnerSchema = zod_1.z.strictObject({
+    id: hubIds_1.hubIdSchema,
+    name: zod_1.z.string().regex(runnersConfig_1.runnerNamePattern, 'must be lowercase letters, digits and single dashes').max(40),
+    /** The runner's own client key: what its `authorized_keys` line holds. */
+    publicKey: publicKeySchema,
+    keyFingerprint: zod_1.z.string().max(maxTextLength),
+    /** The host key of the runner's built-in ssh server: pinned by the gate and by `known_hosts`. */
+    hostKey: publicKeySchema,
+    workDir: runnersConfig_1.runnerWorkDirSchema,
+    os: zod_1.z.string().max(maxTextLength),
+    arch: zod_1.z.string().max(maxTextLength),
+    version: zod_1.z.string().max(maxTextLength),
+    serviceKind: zod_1.z.enum(exports.runnerServiceKinds),
+    pairedAtMs: zod_1.z.number().int().nonnegative(),
+    /** The pairing that made it: how the instance that offered the code finds out that it was used, and what makes a retry of `redeem` idempotent. */
+    pairId: hubIds_1.hubIdSchema,
+    /** What the runner was told about this hub (kept so a retried `redeem` is answered the same way after the pending entry is gone). */
+    label: zod_1.z.string().min(1).max(maxTextLength),
+    host: hubIds_1.hubHostSchema,
+    port: hubIds_1.hubPortSchema,
+    /** Set from the hub: the runner stays attached, but no job is sent to it. */
+    isPaused: zod_1.z.boolean(),
+});
+exports.pairedFileSchema = zod_1.z.strictObject({
+    /** Counts every change: a keyboard built from one revision never acts on a later list. */
+    rev: zod_1.z.number().int().nonnegative(),
+    runners: zod_1.z.array(pairedRunnerSchema),
+});
+const pendingPairingSchema = zod_1.z.strictObject({
+    pairId: hubIds_1.hubIdSchema,
+    /** The temporary key's PUBLIC half (the private half is in the code only). */
+    publicKey: publicKeySchema,
+    keyFingerprint: zod_1.z.string().max(maxTextLength),
+    expiresAtMs: zod_1.z.number().int().nonnegative(),
+    host: hubIds_1.hubHostSchema,
+    port: hubIds_1.hubPortSchema,
+    /** Whose charness it is, as the runner shows it (`@ExampleBot`, a host name). */
+    label: zod_1.z.string().min(1).max(maxTextLength),
+    /** The message the offering instance edits when the code is used or expires (opaque to the hub); `null` for the CLI. */
+    messageRef: zod_1.z.string().max(maxTextLength).nullable(),
+});
+const pendingFileSchema = zod_1.z.strictObject({ pending: zod_1.z.array(pendingPairingSchema) });
+const closedCodeSchema = zod_1.z.strictObject({ pairId: hubIds_1.hubIdSchema, closedAtMs: zod_1.z.number().int().nonnegative() });
+const closedFileSchema = zod_1.z.strictObject({ closed: zod_1.z.array(closedCodeSchema) });
+/** The newest this many closings are kept: a closing is rare and its trace is wanted by a message that is still unsettled, so a cap is all the bound it needs. */
+const maxClosedCodes = 50;
+class HubRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HubRegistryError';
+    }
+}
+exports.HubRegistryError = HubRegistryError;
+/** @description The registry files were written but a file derived from them could not be; the next locked operation repairs it. */
+class HubDerivedFilesError extends HubRegistryError {
+    constructor(fileName, errnoCode) {
+        super(`the registry was updated but ${fileName} could not be written (${errnoCode}); the next runners command repairs it`);
+        this.name = 'HubDerivedFilesError';
+    }
+}
+exports.HubDerivedFilesError = HubDerivedFilesError;
+function readRegistryFile(filePath, fileName, schema, createEmpty) {
+    let text;
+    try {
+        text = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return createEmpty();
+        throw new HubRegistryError(`${fileName} could not be read`);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(text);
+    }
+    catch {
+        throw new HubRegistryError(`${fileName} is not valid JSON; fix or remove it by hand (nothing was changed)`);
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (parsed.success)
+        return parsed.data;
+    throw new HubRegistryError(`${fileName} is invalid: ${parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; ')}`);
+}
+/** @description `paired.json` right now (missing = nobody paired). */
+function readPairedFile(dir) {
+    return readRegistryFile((0, hubPaths_1.getHubFilePaths)(dir).paired, 'paired.json', exports.pairedFileSchema, () => ({ rev: 0, runners: [] }));
+}
+/** @description `pending.json` right now (missing = no code out). */
+function readPendingFile(dir) {
+    return readRegistryFile((0, hubPaths_1.getHubFilePaths)(dir).pending, 'pending.json', pendingFileSchema, () => ({ pending: [] }));
+}
+/**
+ * @description `closed.json` right now: its codes, or none — with the problem named — when it cannot be read or does not validate. A trace
+ * must never stop the caller, so unlike the registry files this does not throw; the caller says the problem once.
+ */
+function readClosedCodes(dir) {
+    try {
+        return { codes: readRegistryFile((0, hubPaths_1.getHubFilePaths)(dir).closed, 'closed.json', closedFileSchema, () => ({ closed: [] })).closed, problem: null };
+    }
+    catch (error) {
+        if (error instanceof HubRegistryError)
+            return { codes: [], problem: `${error.message}; the codes in it read as expired` };
+        throw error;
+    }
+}
+/**
+ * @description Note that the code `pairId` was closed at `nowMs` (the newest {@link maxClosedCodes} are kept); the registry lock must be held. BEST
+ * EFFORT: a trace that cannot be written is said through `ctx.log` and costs only the nicer text («this line was used on a machine that was
+ * already paired» reads «expired»), never the closing it describes. A file that cannot be used is replaced.
+ */
+function recordClosedCode(ctx, pairId, nowMs) {
+    const { codes, problem } = readClosedCodes(ctx.dir);
+    if (problem !== null)
+        ctx.log(`${problem}; it is written anew`);
+    try {
+        (0, hubLock_1.ensureHubDir)(ctx.dir);
+        (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getHubFilePaths)(ctx.dir).closed, closedFileSchema.parse({ closed: [...codes.filter((entry) => entry.pairId !== pairId), { pairId, closedAtMs: nowMs }].slice(-maxClosedCodes) }), registryFileMode);
+    }
+    catch (error) {
+        ctx.log(`closed.json could not be written (${(0, configDirFile_2.getCaughtErrnoCode)(error)}); the messages of the code that was just closed will read as expired`);
+    }
+}
+/** @description Write `paired.json`; the registry lock must be held. */
+function writePairedFile(dir, file) {
+    (0, hubLock_1.ensureHubDir)(dir);
+    (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getHubFilePaths)(dir).paired, exports.pairedFileSchema.parse(file), registryFileMode);
+}
+/** @description Write `pending.json`; the registry lock must be held. */
+function writePendingFile(dir, file) {
+    (0, hubLock_1.ensureHubDir)(dir);
+    (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getHubFilePaths)(dir).pending, pendingFileSchema.parse(file), registryFileMode);
+}
+/** @description The `known_hosts` text for the ssh calls through the links: one line per runner, under its alias. */
+function renderKnownHosts(runners) {
+    return runners.map((runner) => `${(0, hubPaths_1.getRunnerHostAlias)(runner.id)} ${runner.hostKey}\n`).join('');
+}
+/** @description The lines of the managed `authorized_keys` block: every pairing code still open, then every paired runner. */
+function renderManagedBlockLines(ctx, pending, runners, nowMs) {
+    const gatePath = (0, hubPaths_1.getHubFilePaths)(ctx.dir).gate;
+    const common = { gatePath, keysPath: ctx.authorizedKeysPath, dir: ctx.dir };
+    return [
+        ...pending.filter((pairing) => pairing.expiresAtMs > nowMs).map((pairing) => (0, authorizedKeys_1.buildTempKeyLine)({ ...common, publicKey: pairing.publicKey, expiresAtMs: pairing.expiresAtMs, pairId: pairing.pairId })),
+        ...runners.map((runner) => (0, authorizedKeys_1.buildRunnerKeyLine)({ ...common, publicKey: runner.publicKey, runnerId: runner.id })),
+    ];
+}
+function readTextIfPresent(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description Bring the derived files in line with the two registry files: `known_hosts` and the `authorized_keys` block, each written
+ * only when it differs, and the link files of runners that are no longer registered deleted. The registry lock must be held. The block goes LAST, so a key is never allowed before the files its gate reads
+ * are in place. The registry files are authoritative and are written BEFORE this runs; a failure here is reported as
+ * {@link HubDerivedFilesError} and mends itself, because every locked operation ends with this same call.
+ */
+function syncDerivedHubFiles(ctx, pending, paired, nowMs) {
+    const knownHostsPath = (0, hubPaths_1.getHubFilePaths)(ctx.dir).knownHosts;
+    const knownHosts = renderKnownHosts(paired.runners);
+    try {
+        if (readTextIfPresent(knownHostsPath) !== knownHosts)
+            (0, configDirFile_1.writeTextFileAtomically)(knownHostsPath, knownHosts, knownHostsMode);
+    }
+    catch (error) {
+        throw new HubDerivedFilesError('known_hosts', (0, configDirFile_2.getCaughtErrnoCode)(error));
+    }
+    try {
+        (0, authorizedKeys_1.writeManagedBlock)(ctx.authorizedKeysPath, renderManagedBlockLines(ctx, pending.pending, paired.runners, nowMs));
+    }
+    catch (error) {
+        throw new HubDerivedFilesError('authorized_keys', (0, configDirFile_2.getCaughtErrnoCode)(error));
+    }
+    // The link files of a runner the registry does not know are leftovers: best effort, it cannot fail the operation that has already written its files.
+    (0, linkControl_1.sweepOrphanLinkRecords)(ctx.dir, paired.runners.map((runner) => runner.id), ctx.log);
+}
+//# sourceMappingURL=hubRegistry.js.map

package/dist/runners/hubRegistry.js.map

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

package/dist/runners/linkControl.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+declare const linkStateSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    sinceMs: z.ZodNumber;
+    lastBeatMs: z.ZodNumber;
+    endedAtMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+/** @name LinkState @description `link/<id>.json`. */
+export type LinkState = z.infer<typeof linkStateSchema>;
+export interface RunnerLinkStatus {
+    isOnline: boolean;
+    /** When the link in force started (only while online). */
+    sinceMs: number | null;
+    /** The last time the hub knew the link alive; `null` if it never was. */
+    lastSeenMs: number | null;
+}
+export declare function readLinkState(dir: string, runnerId: string): LinkState | null;
+export declare function writeLinkState(dir: string, runnerId: string, state: LinkState): void;
+/** @description Does anything accept a connection on the unix socket `socketPath` right now? */
+export declare function probeSocket(socketPath: string, timeoutMs?: number): Promise<boolean>;
+export declare function getRunnerLinkStatus(dir: string, runnerId: string): Promise<RunnerLinkStatus>;
+/** @description Is `pid` a charness gate serving runner `runnerId`? (A pid in an old json may belong to anything by now.) */
+export declare function checkIsGateProcessOf(pid: number, runnerId: string): boolean;
+/** @description Cut the link of a runner that was removed: no new connection reaches it, its gate leaves, and its link files are deleted. */
+export declare function cutRunnerLink(dir: string, runnerId: string): void;
+/**
+ * @description Delete the link files (`<id>.json`, `<id>.sock`) of every runner that is not in `registeredRunnerIds`: a removal that was cut
+ * short, a gate that wrote its status after the removal, a runner dropped from the registry by hand. Records of a runner whose gate is still
+ * running are kept — it is on its way out, and {@link cutRunnerLink} still needs the pid to stop it.
+ *
+ * Best effort, and it NEVER throws: the registry operation that calls it has already written its files, and a folder that cannot be listed
+ * or a file that cannot be deleted is only leftover clutter, tried again by the next operation. What went wrong is handed to `onProblem`,
+ * which the caller must give (a sweep that cannot say what failed would hide exactly what it exists to report); a missing folder is not a
+ * problem: nothing was ever linked. Returns the names deleted.
+ */
+export declare function sweepOrphanLinkRecords(dir: string, registeredRunnerIds: readonly string[], onProblem: (message: string) => void): string[];
+export {};
+//# sourceMappingURL=linkControl.d.ts.map

package/dist/runners/linkControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkControl.d.ts","sourceRoot":"","sources":["../../src/runners/linkControl.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,QAAA,MAAM,eAAe;;;;;kBAMnB,CAAC;AAEH,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO7E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAGpF;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,MAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAYpG;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlG;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,6IAA6I;AAC7I,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAajE;AAUD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,mBAAmB,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,EAAE,CAwB1I"}