charness 3.7.0 → 3.9.0

package/dist/runners/runnerServiceKind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerServiceKind.js","sourceRoot":"","sources":["../../src/runners/runnerServiceKind.ts"],"names":[],"mappings":";;AASA,sDAEC;AARD;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,MAAoB,EAAE,KAAyB;IACnF,OAAO,KAAK,EAAE,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC;AAClD,CAAC"}

package/dist/runners/runnersCli.d.ts

@@ -0,0 +1,25 @@
+import type { CliIo } from '../remoteRun/output';
+import { type HostKeyScanner } from './hubAddress';
+import { type HubContext } from './hubPaths';
+/**
+ * @description `charness runners [ls | pair | remove <name> | pause <name> | resume <name>]` — the headless twin of `/runners`, for an
+ * instance without Telegram (a Jira-only one) and for the flow tests. It works on the registry of the OS user
+ * (`~/.config/charness/runners/`), loads no env file and never touches `DATA_DIR`.
+ */
+/** What the admin line does to the machine it is pasted on, in the words every place that offers it uses (the Telegram message has it in each language). */
+export declare const adminLineTrustSentence = "It runs code from this charness host as root on that machine";
+export declare const runnersUsage = "Usage:\n  charness runners [ls]                       the machines paired as runners: online or not, OS, how they are kept running\n                                              (as each machine last reported it; no ssh call)\n  charness runners pair --host <host[:port]> [--label <text>] [--account <name>] [--wait]\n                                              make two pairing lines (valid 10 minutes, single use, the first one used wins) to run on\n                                              the runner machine: one for an ADMIN account there (it pairs <name>, default \"runner\", and\n                                              installs its always-on service), one for the runner account itself;\n                                              <host[:port]> is the address the runner dials to reach this machine's sshd;\n                                              --wait blocks until a line is used or the code expires (a line pasted for a machine that\n                                              was already paired ends it too, with exit 0: nothing new was paired)\n  charness runners remove <name>              detach a runner: its key is deleted and its link cut\n  charness runners pause <name>               keep a runner attached but send it no jobs\n  charness runners resume <name>\n";
+/** @description What the CLI needs from outside; tests replace the scanner, the clock and the wait. */
+export interface RunnersCliDeps {
+    ctx: HubContext;
+    /** Where remote-run keeps the last probe snapshot of each machine: `ls` reads them (it makes no ssh call). */
+    cacheDir: string;
+    scanHostKey: HostKeyScanner;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    sshUser?: string;
+}
+export declare function createRunnersCliDeps(io: Pick<CliIo, 'homeDir' | 'env'>): RunnersCliDeps;
+/** @description Run the command line (the words after `runners`); resolves with the exit code. */
+export declare function runRunnersCli(argv: readonly string[], io: CliIo, deps?: RunnersCliDeps): Promise<number>;
+//# sourceMappingURL=runnersCli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnersCli.d.ts","sourceRoot":"","sources":["../../src/runners/runnersCli.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAIjD,OAAO,EAAiD,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ/D;;;;GAIG;AAEH,4JAA4J;AAC5J,eAAO,MAAM,sBAAsB,iEAAiE,CAAC;AAMrG,eAAO,MAAM,YAAY,iyCAaxB,CAAC;AAEF,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,UAAU,CAAC;IAChB,8GAA8G;IAC9G,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,cAAc,CAAC;IAC5B,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG,cAAc,CAQvF;AAkID,kGAAkG;AAClG,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,GAAE,cAAyC,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BxI"}

package/dist/runners/runnersCli.js

@@ -0,0 +1,239 @@
+"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.runnersUsage = exports.adminLineTrustSentence = void 0;
+exports.createRunnersCliDeps = createRunnersCliDeps;
+exports.runRunnersCli = runRunnersCli;
+const os = __importStar(require("os"));
+const ssh_1 = require("../remoteRun/ssh");
+const bootstrapLine_1 = require("./bootstrapLine");
+const gateWrapper_1 = require("./gateWrapper");
+const hubAddress_1 = require("./hubAddress");
+const hubPaths_1 = require("./hubPaths");
+const hubPairing_1 = require("./hubPairing");
+const pairingTiming_1 = require("./pairingTiming");
+const hubRegistry_1 = require("./hubRegistry");
+const runnerRemoval_1 = require("./runnerRemoval");
+const runnersOverview_1 = require("./runnersOverview");
+const runnersList_1 = require("./runnersList");
+/**
+ * @description `charness runners [ls | pair | remove <name> | pause <name> | resume <name>]` — the headless twin of `/runners`, for an
+ * instance without Telegram (a Jira-only one) and for the flow tests. It works on the registry of the OS user
+ * (`~/.config/charness/runners/`), loads no env file and never touches `DATA_DIR`.
+ */
+/** What the admin line does to the machine it is pasted on, in the words every place that offers it uses (the Telegram message has it in each language). */
+exports.adminLineTrustSentence = 'It runs code from this charness host as root on that machine';
+const usageExitCode = 2;
+const failedExitCode = 1;
+const waitPollMs = 1000;
+exports.runnersUsage = `Usage:
+  charness runners [ls]                       the machines paired as runners: online or not, OS, how they are kept running
+                                              (as each machine last reported it; no ssh call)
+  charness runners pair --host <host[:port]> [--label <text>] [--account <name>] [--wait]
+                                              make two pairing lines (valid 10 minutes, single use, the first one used wins) to run on
+                                              the runner machine: one for an ADMIN account there (it pairs <name>, default "runner", and
+                                              installs its always-on service), one for the runner account itself;
+                                              <host[:port]> is the address the runner dials to reach this machine's sshd;
+                                              --wait blocks until a line is used or the code expires (a line pasted for a machine that
+                                              was already paired ends it too, with exit 0: nothing new was paired)
+  charness runners remove <name>              detach a runner: its key is deleted and its link cut
+  charness runners pause <name>               keep a runner attached but send it no jobs
+  charness runners resume <name>
+`;
+function createRunnersCliDeps(io) {
+    return {
+        ctx: (0, hubPaths_1.createHubContext)({ homeDir: io.homeDir }),
+        cacheDir: (0, ssh_1.getRemoteRunCacheDir)(io.env, io.homeDir),
+        scanHostKey: hubAddress_1.scanHostKey,
+        now: Date.now,
+        sleep: (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+    };
+}
+function parsePairOptions(args) {
+    const options = { host: null, label: null, account: bootstrapLine_1.defaultRunnerAccount, isWaiting: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--wait') {
+            options.isWaiting = true;
+        }
+        else if (argument === '--host' || argument === '--label' || argument === '--account') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return `${argument} needs a value`;
+            if (argument === '--host')
+                options.host = value;
+            else if (argument === '--label')
+                options.label = value;
+            else if ((0, bootstrapLine_1.checkIsAccountName)(value))
+                options.account = value;
+            else
+                return '--account must be a plain account name (letters, digits, ".", "_", "-")';
+            index += 1;
+        }
+        else {
+            return `unknown argument: ${argument}`;
+        }
+    }
+    return options;
+}
+async function runPairCommand(args, io, deps) {
+    const options = parsePairOptions(args);
+    if (typeof options === 'string' || options.host === null) {
+        io.stderr(`runners: ${typeof options === 'string' ? options : '--host <host[:port]> is required (the address runners dial to reach this machine over ssh)'}\n\n${exports.runnersUsage}`);
+        return usageExitCode;
+    }
+    const parsedAddress = (0, hubAddress_1.parseHubAddress)(options.host);
+    if (!parsedAddress.ok) {
+        io.stderr(`runners: ${parsedAddress.error}\n`);
+        return usageExitCode;
+    }
+    const check = await (0, hubAddress_1.checkHubAddress)(parsedAddress.address, deps.scanHostKey);
+    if (!check.ok) {
+        io.stderr(`runners: ${check.error}\n`);
+        return failedExitCode;
+    }
+    if (check.note !== null)
+        io.stderr(`runners: ${check.note}\n`);
+    (0, gateWrapper_1.ensureGateWrapper)(deps.ctx);
+    const pairing = await (0, hubPairing_1.createPairing)(deps.ctx, {
+        host: parsedAddress.address.host,
+        port: parsedAddress.address.port,
+        hostKey: check.hostKey,
+        label: options.label ?? os.hostname(),
+        nowMs: deps.now(),
+        lifetimeMs: (0, pairingTiming_1.readPairingLifetimeMs)(io.env),
+        sshUser: deps.sshUser,
+    });
+    io.stdout(`Pair a runner — valid ${(0, pairingTiming_1.formatLifetime)((0, pairingTiming_1.readPairingLifetimeMs)(io.env))}, single use.\n\n` +
+        `1) From an admin account of the runner machine: it pairs "${options.account}" (the last word of the line — change it if the account is named otherwise) and keeps it running. ${exports.adminLineTrustSentence}:\n\n` +
+        `${(0, bootstrapLine_1.buildAdminBootstrapLine)(pairing.payload, options.account)}\n\n` +
+        `2) Without admin rights: run this one in the terminal of the runner account itself:\n\n` +
+        `${(0, bootstrapLine_1.buildBootstrapLine)(pairing.payload)}\n\n` +
+        `The account must be an existing standard user, not your main account — it runs the agents' code.\n` +
+        `Anyone with either line can attach a machine to this charness until one of them is used or expires.\n`);
+    return options.isWaiting ? waitForPairing(pairing.pairId, io, deps) : 0;
+}
+async function waitForPairing(pairId, io, deps) {
+    for (;;) {
+        const runner = (0, hubRegistry_1.readPairedFile)(deps.ctx.dir).runners.find((candidate) => candidate.pairId === pairId);
+        if (runner !== undefined) {
+            io.stdout(`Runner "${runner.name}" paired ${(0, runnersList_1.formatListTimestamp)(runner.pairedAtMs)}.\n`);
+            return 0;
+        }
+        const pairing = (0, hubRegistry_1.readPendingFile)(deps.ctx.dir).pending.find((candidate) => candidate.pairId === pairId);
+        // A code closed unused is not a failure: its line was pasted for a machine that was already paired, and did its job (the service).
+        if (pairing === undefined) {
+            const { codes, problem } = (0, hubRegistry_1.readClosedCodes)(deps.ctx.dir);
+            if (problem !== null)
+                io.stderr(`runners: ${problem}\n`);
+            if (codes.some((entry) => entry.pairId === pairId)) {
+                io.stdout('The pairing line was used on a machine that was already paired: nothing new was paired.\n');
+                return 0;
+            }
+        }
+        if (pairing === undefined || pairing.expiresAtMs <= deps.now()) {
+            await (0, hubPairing_1.sweepExpiredPairings)(deps.ctx, deps.now());
+            io.stderr('runners: the pairing code expired unused.\n');
+            return failedExitCode;
+        }
+        await deps.sleep(waitPollMs);
+    }
+}
+async function runListCommand(io, deps) {
+    await (0, hubPairing_1.sweepExpiredPairings)(deps.ctx, deps.now());
+    // The screen's first step: the registry, which links are up and the last snapshot of each machine — no ssh call, so `ls` stays instant and a
+    // machine is online exactly when its link is (the screen's second step, the live probe, may demote one whose ssh does not answer).
+    const overview = await (0, runnersOverview_1.readRunnersOverview)(deps.ctx, deps.cacheDir, deps.now());
+    io.stdout((0, runnersList_1.formatRunnerList)(overview.entries, (0, hubRegistry_1.readPendingFile)(deps.ctx.dir).pending, deps.now()));
+    return 0;
+}
+async function runRemoveCommand(name, io, deps) {
+    const removal = await (0, runnerRemoval_1.removeRunnerAndEndItsWork)(deps.ctx, name, deps.now());
+    if (removal === null) {
+        io.stderr(`runners: no runner named "${name}"\n`);
+        return failedExitCode;
+    }
+    const jobsNote = {
+        stopped: 'the jobs it had running are stopped',
+        failed: 'the jobs it had running could not be stopped from here (it stops them itself once it finds out it was removed)',
+        offline: 'it is offline: it stops the jobs it had running itself once it finds out it was removed',
+    }[removal.jobs];
+    io.stdout(`Runner "${removal.runner.name}" removed: its key is deleted and its link cut; ${jobsNote}.\n`);
+    return 0;
+}
+async function runPauseCommand(name, isPaused, io, deps) {
+    const runner = (0, hubPairing_1.findPairedRunner)((0, hubRegistry_1.readPairedFile)(deps.ctx.dir).runners, name);
+    const updated = runner === undefined ? null : await (0, hubPairing_1.setPairedRunnerPaused)(deps.ctx, runner.id, isPaused);
+    if (updated === null) {
+        io.stderr(`runners: no runner named "${name}"\n`);
+        return failedExitCode;
+    }
+    io.stdout(`Runner "${updated.name}" ${isPaused ? 'paused: it gets no jobs until resumed' : 'resumed'}.\n`);
+    return 0;
+}
+/** @description Run the command line (the words after `runners`); resolves with the exit code. */
+async function runRunnersCli(argv, io, deps = createRunnersCliDeps(io)) {
+    const [command = 'ls', ...args] = argv;
+    try {
+        switch (command) {
+            case 'ls':
+                return await runListCommand(io, deps);
+            case 'pair':
+                return await runPairCommand(args, io, deps);
+            case 'remove':
+            case 'pause':
+            case 'resume': {
+                if (args.length !== 1) {
+                    io.stderr(`runners: ${command} needs exactly one runner name\n\n${exports.runnersUsage}`);
+                    return usageExitCode;
+                }
+                return command === 'remove' ? await runRemoveCommand(args[0], io, deps) : await runPauseCommand(args[0], command === 'pause', io, deps);
+            }
+            case '--help':
+            case '-h':
+            case 'help':
+                io.stdout(exports.runnersUsage);
+                return 0;
+            default:
+                io.stderr(`runners: unknown command: ${command}\n\n${exports.runnersUsage}`);
+                return usageExitCode;
+        }
+    }
+    catch (error) {
+        io.stderr(`runners: ${error instanceof hubRegistry_1.HubRegistryError ? error.message : `failed (${error instanceof Error ? error.name : 'unknown error'}: ${error instanceof Error ? error.message : ''})`}\n`);
+        return failedExitCode;
+    }
+}
+//# sourceMappingURL=runnersCli.js.map

package/dist/runners/runnersCli.js.map

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

package/dist/runners/runnersList.d.ts

@@ -0,0 +1,14 @@
+import type { RunnerScreenEntry } from '../utils/runnersScreenPlan';
+import type { PendingPairing, RunnerServiceKind } from './hubRegistry';
+/**
+ * @description The text of `charness runners ls`: one line per paired runner (name, online or offline since when, paused, OS, how it
+ * is kept running, version) and a line for each pairing code still open. Pure: the entries — the same ones the `/runners` screen is built
+ * from, with the probe — are read by the caller, and how a runner is kept running is the one rule of `getCurrentServiceKind`.
+ */
+export declare const serviceKindLabels: Record<RunnerServiceKind, string>;
+/** @description `2026-11-01 14:05` in the zone of this process. */
+export declare function formatListTimestamp(epochMs: number): string;
+export declare function formatRunnerListLine(entry: RunnerScreenEntry): string;
+/** @description The whole `ls` output. */
+export declare function formatRunnerList(entries: readonly RunnerScreenEntry[], pending: readonly PendingPairing[], nowMs: number): string;
+//# sourceMappingURL=runnersList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnersList.d.ts","sourceRoot":"","sources":["../../src/runners/runnersList.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGvE;;;;GAIG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAK/D,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI3D;AAOD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAWrE;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOjI"}

package/dist/runners/runnersList.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceKindLabels = void 0;
+exports.formatListTimestamp = formatListTimestamp;
+exports.formatRunnerListLine = formatRunnerListLine;
+exports.formatRunnerList = formatRunnerList;
+const runnerServiceKind_1 = require("./runnerServiceKind");
+/**
+ * @description The text of `charness runners ls`: one line per paired runner (name, online or offline since when, paused, OS, how it
+ * is kept running, version) and a line for each pairing code still open. Pure: the entries — the same ones the `/runners` screen is built
+ * from, with the probe — are read by the caller, and how a runner is kept running is the one rule of `getCurrentServiceKind`.
+ */
+exports.serviceKindLabels = {
+    foreground: 'run by hand',
+    'user-service': 'user service',
+    'system-service': 'system service',
+    unknown: 'service unknown',
+};
+/** @description `2026-11-01 14:05` in the zone of this process. */
+function formatListTimestamp(epochMs) {
+    const date = new Date(epochMs);
+    const pad = (value) => value.toString().padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+function describeConnection(entry) {
+    if (entry.isOnline)
+        return 'online';
+    return entry.lastSeenMs === null ? 'offline, never connected' : `offline since ${formatListTimestamp(entry.lastSeenMs)}`;
+}
+function formatRunnerListLine(entry) {
+    const { runner, probe } = entry;
+    const parts = [
+        describeConnection(entry),
+        ...(runner.isPaused ? ['paused'] : []),
+        `${runner.os} (${runner.arch})`,
+        exports.serviceKindLabels[(0, runnerServiceKind_1.getCurrentServiceKind)(runner, probe)],
+        `charness ${runner.version}`,
+        `paired ${formatListTimestamp(runner.pairedAtMs)}`,
+    ];
+    return `${runner.name} — ${parts.join(' · ')}`;
+}
+/** @description The whole `ls` output. */
+function formatRunnerList(entries, pending, nowMs) {
+    const lines = entries.length === 0 ? ['No runners paired yet. `charness runners pair --host <address>` makes a pairing line.'] : entries.map(formatRunnerListLine);
+    const open = pending.filter((pairing) => pairing.expiresAtMs > nowMs);
+    if (open.length > 0) {
+        lines.push('', ...open.map((pairing) => `Pairing code open until ${formatListTimestamp(pairing.expiresAtMs)} (${pairing.host}:${pairing.port})`));
+    }
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=runnersList.js.map

package/dist/runners/runnersList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnersList.js","sourceRoot":"","sources":["../../src/runners/runnersList.ts"],"names":[],"mappings":";;;AAkBA,kDAIC;AAOD,oDAWC;AAGD,4CAOC;AAhDD,2DAA4D;AAE5D;;;;GAIG;AAEU,QAAA,iBAAiB,GAAsC;IAClE,UAAU,EAAE,aAAa;IACzB,cAAc,EAAE,cAAc;IAC9B,gBAAgB,EAAE,gBAAgB;IAClC,OAAO,EAAE,iBAAiB;CAC3B,CAAC;AAEF,mEAAmE;AACnE,SAAgB,mBAAmB,CAAC,OAAe;IACjD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzE,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AACtI,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAwB;IAClD,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACpC,OAAO,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,iBAAiB,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;AAC3H,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAwB;IAC3D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAChC,MAAM,KAAK,GAAG;QACZ,kBAAkB,CAAC,KAAK,CAAC;QACzB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,GAAG;QAC/B,yBAAiB,CAAC,IAAA,yCAAqB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvD,YAAY,MAAM,CAAC,OAAO,EAAE;QAC5B,UAAU,mBAAmB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE;KACnD,CAAC;IACF,OAAO,GAAG,MAAM,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,0CAA0C;AAC1C,SAAgB,gBAAgB,CAAC,OAAqC,EAAE,OAAkC,EAAE,KAAa;IACvH,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,uFAAuF,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACnK,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,2BAA2B,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACpJ,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/runners/runnersOverview.d.ts

@@ -0,0 +1,20 @@
+import type { RunnerScreenEntry } from '../utils/runnersScreenPlan';
+import type { HubContext } from './hubPaths';
+/**
+ * @description What the `/runners` screen shows, read in two steps so it can open at once: {@link readRunnersOverview} is the registry,
+ * the links (does the socket accept?) and the last snapshot each machine left — no ssh, milliseconds — and
+ * {@link probeRunnersOverview} asks the machines that are online what they are like right now (one shared 20 s deadline, the phase-1
+ * probe), keeping the snapshot of a machine that does not answer.
+ */
+export interface RunnersOverview {
+    /** The registry revision (`paired.json` `rev`): what a keyboard built from this overview is valid for. */
+    revision: number;
+    entries: RunnerScreenEntry[];
+    /** Expiry of every pairing code that is still open. */
+    openPairingExpiries: number[];
+}
+/** @description The overview without any ssh call: the registry, which links are up, the last snapshots. */
+export declare function readRunnersOverview(ctx: HubContext, cacheDir: string, nowMs: number): Promise<RunnersOverview>;
+/** @description `overview` with the machines that are online asked for their live state. Offline ones are not called. */
+export declare function probeRunnersOverview(ctx: HubContext, overview: RunnersOverview, cacheDir: string, nowMs: number): Promise<RunnersOverview>;
+//# sourceMappingURL=runnersOverview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnersOverview.d.ts","sourceRoot":"","sources":["../../src/runners/runnersOverview.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AASD,4GAA4G;AAC5G,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAOpH;AASD,yHAAyH;AACzH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBhJ"}

package/dist/runners/runnersOverview.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRunnersOverview = readRunnersOverview;
+exports.probeRunnersOverview = probeRunnersOverview;
+const pairedRunners_1 = require("../remoteRun/pairedRunners");
+const runners_1 = require("../remoteRun/runners");
+const runnerClient_1 = require("../remoteRun/runnerClient");
+const ssh_1 = require("../remoteRun/ssh");
+const hubRegistry_1 = require("./hubRegistry");
+const linkControl_1 = require("./linkControl");
+async function readEntry(ctx, runner, cacheDir) {
+    const status = await (0, linkControl_1.getRunnerLinkStatus)(ctx.dir, runner.id);
+    // Only a report taken since this machine was paired is its own: its name may have belonged to a machine that was removed.
+    const snapshot = (0, runners_1.readLastProbe)(cacheDir, runner.name, runner.pairedAtMs);
+    return { runner, isOnline: status.isOnline, lastSeenMs: status.lastSeenMs ?? snapshot?.seenAtMs ?? null, probe: snapshot?.probe ?? null };
+}
+/** @description The overview without any ssh call: the registry, which links are up, the last snapshots. */
+async function readRunnersOverview(ctx, cacheDir, nowMs) {
+    const paired = (0, hubRegistry_1.readPairedFile)(ctx.dir);
+    return {
+        revision: paired.rev,
+        entries: await Promise.all(paired.runners.map((runner) => readEntry(ctx, runner, cacheDir))),
+        openPairingExpiries: (0, hubRegistry_1.readPendingFile)(ctx.dir).pending.filter((pairing) => pairing.expiresAtMs > nowMs).map((pairing) => pairing.expiresAtMs),
+    };
+}
+function applyReport(entry, report) {
+    if (report === undefined)
+        return entry;
+    if (report.status === 'online')
+        return { ...entry, probe: report.probe };
+    // It answered the socket probe but not the ssh one: it is shown as it was, offline.
+    return { ...entry, isOnline: false, lastSeenMs: report.lastSeenAtMs ?? entry.lastSeenMs, probe: report.lastProbe ?? entry.probe };
+}
+/** @description `overview` with the machines that are online asked for their live state. Offline ones are not called. */
+async function probeRunnersOverview(ctx, overview, cacheDir, nowMs) {
+    const hub = { hubDir: ctx.dir, nodePath: ctx.nodePath, cliPath: ctx.cliPath };
+    const clients = overview.entries
+        .filter((entry) => entry.isOnline)
+        .flatMap((entry) => {
+        try {
+            return [(0, runnerClient_1.createRunnerClient)((0, pairedRunners_1.buildPairedRunnerConfig)(entry.runner, hub), cacheDir)];
+        }
+        catch (error) {
+            // A path of this machine that ssh cannot be given safely: that machine is shown as its last snapshot says, not probed.
+            if (error instanceof pairedRunners_1.PairedRunnerSetupError)
+                return [];
+            throw error;
+        }
+    });
+    if (clients.length === 0)
+        return overview;
+    (0, ssh_1.ensureRemoteRunCacheDir)(cacheDir);
+    const reports = await (0, runners_1.probeRunners)(clients, nowMs);
+    return { ...overview, entries: overview.entries.map((entry) => applyReport(entry, reports.find((report) => report.name === entry.runner.name))) };
+}
+//# sourceMappingURL=runnersOverview.js.map

package/dist/runners/runnersOverview.js.map

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

package/dist/runners/sshKeys.d.ts

@@ -0,0 +1,26 @@
+export interface SshKeyPair {
+    /** OpenSSH private key text (what `ssh -i` reads). */
+    privateKey: string;
+    /** `ssh-ed25519 <base64>`. */
+    publicKey: string;
+}
+export interface ParsedPublicKey {
+    type: string;
+    /** The key as the ssh wire protocol carries it (what a host key verifier is handed). */
+    blob: Buffer;
+}
+/**
+ * @description A new ed25519 pair; `comment` is kept in the private key only. `ssh2`'s generator drops a leading zero byte of the key
+ * now and then (about 1 key in 300 comes out with a 31-byte public key, which neither `ssh2` nor OpenSSH can read), so every pair is
+ * read back before it is returned and a bad one is made again.
+ */
+export declare function generateEd25519KeyPair(comment: string): SshKeyPair;
+/** @description `value` as a public key, or `null` when it is not exactly `<type> <base64>`. */
+export declare function parsePublicKey(value: string): ParsedPublicKey | null;
+/** @description Is `value` a public key of the type charness issues to runners and the hub — ed25519 — in the strict form? */
+export declare function checkIsEd25519PublicKey(value: string): boolean;
+/** @description `SHA256:…`, the fingerprint `ssh-keygen -l` prints. */
+export declare function getPublicKeyFingerprint(publicKey: string): string;
+/** @description A random identifier (12 lowercase hex digits) safe in a file name, a shell word, an `authorized_keys` option and as the first word of an argument list. */
+export declare function createRandomId(): string;
+//# sourceMappingURL=sshKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sshKeys.d.ts","sourceRoot":"","sources":["../../src/runners/sshKeys.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CASlE;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAKpE;AAED,8HAA8H;AAC9H,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED,2KAA2K;AAC3K,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/runners/sshKeys.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEd25519KeyPair = generateEd25519KeyPair;
+exports.parsePublicKey = parsePublicKey;
+exports.checkIsEd25519PublicKey = checkIsEd25519PublicKey;
+exports.getPublicKeyFingerprint = getPublicKeyFingerprint;
+exports.createRandomId = createRandomId;
+const crypto_1 = require("crypto");
+const ssh2_1 = require("ssh2");
+/**
+ * @description The few things charness does with ssh keys: make an ed25519 pair (the runner's own, the hub's, a pairing's temporary
+ * one), write a public key the way `authorized_keys` and `known_hosts` read it, and its fingerprint. Public keys are kept as the
+ * two-field `<type> <base64>` text — no comment — and checked against a strict pattern before they are ever written into a file
+ * sshd reads: a key that carried a newline or an option would be a line of its own.
+ */
+const base64Alphabet = 'A-Za-z0-9+/';
+const publicKeyPattern = new RegExp(`^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa) ([${base64Alphabet}]+={0,2})$`);
+const ed25519Type = 'ssh-ed25519';
+const idByteLength = 6;
+/** The odds of a bad key are about 1 in 300: ten tries in a row failing is not luck. */
+const maxKeyGenerationAttempts = 10;
+/**
+ * @description A new ed25519 pair; `comment` is kept in the private key only. `ssh2`'s generator drops a leading zero byte of the key
+ * now and then (about 1 key in 300 comes out with a 31-byte public key, which neither `ssh2` nor OpenSSH can read), so every pair is
+ * read back before it is returned and a bad one is made again.
+ */
+function generateEd25519KeyPair(comment) {
+    for (let attempt = 0; attempt < maxKeyGenerationAttempts; attempt += 1) {
+        const generated = ssh2_1.utils.generateKeyPairSync('ed25519', { comment });
+        const publicKey = generated.public.split(' ').slice(0, 2).join(' ');
+        if (!(ssh2_1.utils.parseKey(publicKey) instanceof Error) && !(ssh2_1.utils.parseKey(generated.private) instanceof Error)) {
+            return { privateKey: generated.private, publicKey };
+        }
+    }
+    throw new Error('could not generate a readable ed25519 key');
+}
+/** @description `value` as a public key, or `null` when it is not exactly `<type> <base64>`. */
+function parsePublicKey(value) {
+    const match = publicKeyPattern.exec(value);
+    if (match === null)
+        return null;
+    const blob = Buffer.from(match[2], 'base64');
+    return blob.length === 0 ? null : { type: match[1], blob };
+}
+/** @description Is `value` a public key of the type charness issues to runners and the hub — ed25519 — in the strict form? */
+function checkIsEd25519PublicKey(value) {
+    return parsePublicKey(value)?.type === ed25519Type;
+}
+/** @description `SHA256:…`, the fingerprint `ssh-keygen -l` prints. */
+function getPublicKeyFingerprint(publicKey) {
+    const parsed = parsePublicKey(publicKey);
+    if (parsed === null)
+        throw new Error('not a public key');
+    return `SHA256:${(0, crypto_1.createHash)('sha256').update(parsed.blob).digest('base64').replace(/=+$/, '')}`;
+}
+/** @description A random identifier (12 lowercase hex digits) safe in a file name, a shell word, an `authorized_keys` option and as the first word of an argument list. */
+function createRandomId() {
+    return (0, crypto_1.randomBytes)(idByteLength).toString('hex');
+}
+//# sourceMappingURL=sshKeys.js.map

package/dist/runners/sshKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sshKeys.js","sourceRoot":"","sources":["../../src/runners/sshKeys.ts"],"names":[],"mappings":";;AAmCA,wDASC;AAGD,wCAKC;AAGD,0DAEC;AAGD,0DAIC;AAGD,wCAEC;AArED,mCAAiD;AACjD,+BAA6B;AAE7B;;;;;GAKG;AAEH,MAAM,cAAc,GAAG,aAAa,CAAC;AACrC,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,4DAA4D,cAAc,YAAY,CAAC,CAAC;AAC5H,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,wFAAwF;AACxF,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAepC;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,OAAe;IACpD,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,wBAAwB,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACvE,MAAM,SAAS,GAAG,YAAK,CAAC,mBAAmB,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACpE,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,IAAI,CAAC,CAAC,YAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,YAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,KAAK,CAAC,EAAE,CAAC;YAC3G,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;AAC/D,CAAC;AAED,gGAAgG;AAChG,SAAgB,cAAc,CAAC,KAAa;IAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED,8HAA8H;AAC9H,SAAgB,uBAAuB,CAAC,KAAa;IACnD,OAAO,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,WAAW,CAAC;AACrD,CAAC;AAED,uEAAuE;AACvE,SAAgB,uBAAuB,CAAC,SAAiB;IACvD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACzD,OAAO,UAAU,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;AAClG,CAAC;AAED,2KAA2K;AAC3K,SAAgB,cAAc;IAC5B,OAAO,IAAA,oBAAW,EAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC"}

package/dist/runners/tarArchive.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @description A minimal, DETERMINISTIC tar writer (ustar): the same entries always give the same bytes, so the hash of the archive is
+ * a stable id of the package it carries (a system `tar` writes its own timestamps and ordering). Regular files only — a runner
+ * extracts the archive with the `tar` of its machine, which creates the folders on the way.
+ */
+export interface TarEntry {
+    /** A relative path with `/` separators. */
+    path: string;
+    content: Buffer;
+    /** `0o755` for something that runs, else `0o644`. */
+    mode: number;
+}
+/** @description The ustar `name` and `prefix` fields for `entryPath`, or `null` when no `/` splits it into pieces that fit. */
+export declare function splitTarPath(entryPath: string): {
+    name: string;
+    prefix: string;
+} | null;
+/** @description The archive of `entries`, in the order given, ended by the two empty blocks tar expects. */
+export declare function createTarArchive(entries: readonly TarEntry[]): Buffer;
+//# sourceMappingURL=tarArchive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tarArchive.d.ts","sourceRoot":"","sources":["../../src/runners/tarArchive.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;CACd;AAWD,+HAA+H;AAC/H,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQvF;AAwBD,4GAA4G;AAC5G,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CASrE"}