charness 3.6.1 → 3.8.0

package/dist/runnerUtility/hubClient.d.ts

@@ -0,0 +1,30 @@
+import { Client, type ClientChannel } from 'ssh2';
+import type { z } from 'zod';
+import { type GateMarker, type GateRequest } from '../runners/gateProtocol';
+export interface HubEndpoint {
+    host: string;
+    port: number;
+    user: string;
+    /** `<type> <base64>`: the only host key that is accepted. */
+    hostKey: string;
+}
+export type HubConnectionFailure = 'auth' | 'hostKey' | 'network';
+/** @description Why the hub could not be reached: the key was refused (`auth` — for a paired runner, it was removed), the host key is not the pinned one, or the network/sshd. */
+export declare class HubConnectionError extends Error {
+    readonly failure: HubConnectionFailure;
+    constructor(failure: HubConnectionFailure, message: string);
+}
+/** @description Connect and log in; resolves with the ready client. The caller ends it. */
+export declare function connectToHub(endpoint: HubEndpoint, privateKey: string): Promise<Client>;
+export interface GateAnswer {
+    marker: GateMarker;
+    /** The channel, positioned right after the marker line (what came with it is put back). */
+    channel: ClientChannel;
+}
+/** @description Run the gate request `request` and read its marker line; `null` when the answer has none (the hub refused, or the key line is gone). `body` is sent as stdin and ends it; without one stdin stays open (`link`). */
+export declare function callGate(client: Client, request: GateRequest, body: string | null): Promise<GateAnswer | null>;
+/** @description Everything the channel still sends, as text. */
+export declare function readChannelText(channel: ClientChannel): Promise<string>;
+/** @description A gate request whose answer is one JSON line (`redeem`, `identity`, `unpair`), parsed with `schema`. */
+export declare function requestGateJson<TReply>(client: Client, request: 'redeem' | 'unpair' | 'identity', body: string | null, schema: z.ZodType<TReply>): Promise<TReply>;
+//# sourceMappingURL=hubClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubClient.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/hubClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAA+B,MAAM,MAAM,CAAC;AAC/E,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAejG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE,kLAAkL;AAClL,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;gBAE3B,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAK3D;AAiBD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BvF;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,2FAA2F;IAC3F,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,oOAAoO;AACpO,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAkB9G;AAED,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;AAED,wHAAwH;AACxH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAaxK"}

package/dist/runnerUtility/hubClient.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubConnectionError = void 0;
+exports.connectToHub = connectToHub;
+exports.callGate = callGate;
+exports.readChannelText = readChannelText;
+exports.requestGateJson = requestGateJson;
+const ssh2_1 = require("ssh2");
+const gateProtocol_1 = require("../runners/gateProtocol");
+const sshKeys_1 = require("../runners/sshKeys");
+/**
+ * @description The runner's side of every conversation with the hub's sshd: an ssh2 client that pins the hub's host key (the one in the
+ * pairing code, then in `config.json`), logs in with a key, and runs one of the gate's request words (`redeem`, `package`, `link`,
+ * `unpair`). Whatever the hub's shell printed before the gate ran is skipped up to the marker line (`readUntilGateMarker`).
+ */
+const connectReadyTimeoutMs = 20 * 1000;
+const keepaliveIntervalMs = 15 * 1000;
+const keepaliveCountMax = 3;
+const clientAuthenticationLevel = 'client-authentication';
+const hostDeniedText = 'Host denied';
+/** @description Why the hub could not be reached: the key was refused (`auth` — for a paired runner, it was removed), the host key is not the pinned one, or the network/sshd. */
+class HubConnectionError extends Error {
+    failure;
+    constructor(failure, message) {
+        super(message);
+        this.name = 'HubConnectionError';
+        this.failure = failure;
+    }
+}
+exports.HubConnectionError = HubConnectionError;
+/** The signature algorithms the client offers for each key type: only those of the pinned key, so a hub with several host keys cannot answer with another one. */
+const hostKeyAlgorithms = {
+    'ssh-ed25519': ['ssh-ed25519'],
+    'ecdsa-sha2-nistp256': ['ecdsa-sha2-nistp256'],
+    'ecdsa-sha2-nistp384': ['ecdsa-sha2-nistp384'],
+    'ecdsa-sha2-nistp521': ['ecdsa-sha2-nistp521'],
+    'ssh-rsa': ['rsa-sha2-512', 'rsa-sha2-256', 'ssh-rsa'],
+};
+function classifyFailure(error) {
+    if (error.level === clientAuthenticationLevel)
+        return new HubConnectionError('auth', 'the hub refused the runner\'s key');
+    if (error.message.includes(hostDeniedText))
+        return new HubConnectionError('hostKey', 'the hub\'s ssh host key is not the one pinned at pairing');
+    return new HubConnectionError('network', error.message);
+}
+/** @description Connect and log in; resolves with the ready client. The caller ends it. */
+function connectToHub(endpoint, privateKey) {
+    const pinned = (0, sshKeys_1.parsePublicKey)(endpoint.hostKey);
+    const serverHostKey = pinned === null ? undefined : hostKeyAlgorithms[pinned.type];
+    if (pinned === null || serverHostKey === undefined)
+        return Promise.reject(new HubConnectionError('hostKey', 'the pinned hub host key does not read'));
+    const pinnedBlob = pinned.blob;
+    return new Promise((resolve, reject) => {
+        const client = new ssh2_1.Client();
+        let isReady = false;
+        client.once('ready', () => {
+            isReady = true;
+            resolve(client);
+        });
+        // Kept for the life of the client: an error after `ready` (a reset connection) must never be an unhandled event; whoever uses the
+        // client listens for `close` / `error` itself.
+        client.on('error', (error) => {
+            if (isReady)
+                return;
+            client.end();
+            reject(classifyFailure(error));
+        });
+        client.connect({
+            host: endpoint.host,
+            port: endpoint.port,
+            username: endpoint.user,
+            privateKey,
+            algorithms: { serverHostKey },
+            hostVerifier: (key) => Buffer.isBuffer(key) && key.equals(pinnedBlob),
+            keepaliveInterval: keepaliveIntervalMs,
+            keepaliveCountMax,
+            readyTimeout: connectReadyTimeoutMs,
+        });
+    });
+}
+/** @description Run the gate request `request` and read its marker line; `null` when the answer has none (the hub refused, or the key line is gone). `body` is sent as stdin and ends it; without one stdin stays open (`link`). */
+function callGate(client, request, body) {
+    return new Promise((resolve, reject) => {
+        client.exec(request, async (error, channel) => {
+            if (error !== undefined) {
+                reject(new HubConnectionError('network', error.message));
+                return;
+            }
+            if (body !== null)
+                channel.end(body);
+            const read = await (0, gateProtocol_1.readUntilGateMarker)(channel);
+            if (read === null || read.marker.request !== request) {
+                channel.destroy();
+                resolve(null);
+                return;
+            }
+            channel.unshift(read.rest);
+            resolve({ marker: read.marker, channel });
+        });
+    });
+}
+/** @description Everything the channel still sends, as text. */
+async function readChannelText(channel) {
+    const chunks = [];
+    for await (const chunk of channel)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** @description A gate request whose answer is one JSON line (`redeem`, `identity`, `unpair`), parsed with `schema`. */
+async function requestGateJson(client, request, body, schema) {
+    const answer = await callGate(client, request, body ?? '');
+    if (answer === null)
+        throw new HubConnectionError('network', 'the hub did not answer the request');
+    const text = await readChannelText(answer.channel);
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(text);
+    }
+    catch {
+        throw new HubConnectionError('network', 'the hub\'s answer is not valid JSON');
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (!parsed.success)
+        throw new HubConnectionError('network', 'the hub\'s answer is not what this version expects');
+    return parsed.data;
+}
+//# sourceMappingURL=hubClient.js.map

package/dist/runnerUtility/hubClient.js.map

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

package/dist/runnerUtility/injectStream.d.ts

@@ -0,0 +1,9 @@
+import type { Duplex } from 'stream';
+import type { Server } from 'ssh2';
+/**
+ * @description ssh2's `Server.injectSocket` is typed for a `net.Socket` but takes any bidirectional stream «as though it were a TCP
+ * socket connection» — the channel the hub's gate speaks over, and a `direct-tcpip` channel of that session, are such streams; this is
+ * how the runner serves ssh over a link. The one cast the library's typing needs is here.
+ */
+export declare function injectStreamIntoSshServer(server: Server, stream: Duplex): void;
+//# sourceMappingURL=injectStream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"injectStream.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/injectStream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9E"}

package/dist/runnerUtility/injectStream.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectStreamIntoSshServer = injectStreamIntoSshServer;
+/**
+ * @description ssh2's `Server.injectSocket` is typed for a `net.Socket` but takes any bidirectional stream «as though it were a TCP
+ * socket connection» — the channel the hub's gate speaks over, and a `direct-tcpip` channel of that session, are such streams; this is
+ * how the runner serves ssh over a link. The one cast the library's typing needs is here.
+ */
+function injectStreamIntoSshServer(server, stream) {
+    server.injectSocket(stream);
+}
+//# sourceMappingURL=injectStream.js.map

package/dist/runnerUtility/injectStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectStream.js","sourceRoot":"","sources":["../../src/runnerUtility/injectStream.ts"],"names":[],"mappings":";;AASA,8DAEC;AAPD;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,MAAc,EAAE,MAAc;IACtE,MAAM,CAAC,YAAY,CAAC,MAAgB,CAAC,CAAC;AACxC,CAAC"}

package/dist/runnerUtility/iosCheck.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { type CommandRunner } from '../selfUpdate/commandRunner';
+import type { RunnerHomePaths } from './runnerHome';
+export declare const iosCheckBudgetMs: number;
+/**
+ * How the reason of a `fail` record that is the Simulator's own boot refusal begins. `runner.sh` tells the operator «needs the runner
+ * user's login session» for those — Apple gives no Simulator to a daemon — and shows the reason itself for every other failure (no
+ * runtime installed, the device could not be created); a test pins that the script carries this very text.
+ */
+export declare const iosBootFailureReasonPrefix = "the Simulator did not";
+declare const iosCheckSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        skipped: "skipped";
+        fail: "fail";
+        pass: "pass";
+    }>;
+    checkedAtMs: z.ZodNumber;
+    xcode: z.ZodNullable<z.ZodString>;
+    reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** @name IosCheckRecord @description `ios-check.json`. */
+export type IosCheckRecord = z.infer<typeof iosCheckSchema>;
+export interface SimulatorChoice {
+    deviceTypeId: string;
+    runtimeId: string;
+}
+/** @description The newest available iOS runtime and an iPhone device type (the newest the list names), out of `simctl list runtimes -j` and `list devicetypes -j`. */
+export declare function chooseSimulator(runtimesJson: string, deviceTypesJson: string): SimulatorChoice | null;
+/** @description `16.2 (16C5032a)` out of `xcodebuild -version`, or `null`. */
+export declare function parseXcodeVersion(output: string): string | null;
+export interface IosCheckDeps {
+    runner: CommandRunner;
+    platform: NodeJS.Platform;
+    now: () => number;
+}
+export declare function createIosCheckDeps(): IosCheckDeps;
+export declare function readXcodeVersion(deps: IosCheckDeps): Promise<string | null>;
+/** @description Run the boot check: create → boot → bootstatus → delete. Never throws; the device is deleted whatever happened. */
+export declare function runIosBootCheck(deps: IosCheckDeps): Promise<IosCheckRecord>;
+export declare function readIosCheck(paths: RunnerHomePaths): IosCheckRecord | null;
+/** @description One line, so `runner.sh probe` can read it with `grep`. */
+export declare function writeIosCheck(paths: RunnerHomePaths, record: IosCheckRecord): void;
+/** @description Check again when there is no result yet or Xcode is another one than the last result saw (a version, a build, gone). */
+export declare function checkShouldRunIosCheck(last: IosCheckRecord | null, currentXcode: string | null): boolean;
+export interface IosRefreshOptions {
+    /**
+     * The link just started (a terminal, a LaunchAgent, a LaunchDaemon): check regardless of what the last result says. Whether the Simulator
+     * boots depends on WHO runs the link — a result from an interactive login proves nothing for a daemon that replaced it, and a daemon's
+     * «fail» must not outlive a switch to a login session — so the same Xcode version is no reason to trust an older result. Within one run
+     * (the hourly look) only a different Xcode starts a check.
+     */
+    isStartup: boolean;
+}
+/**
+ * @description At the link's start (always) and then once an hour (when Xcode is not what the last result saw): run the boot check and record it.
+ * At the start the old record is deleted first: a paired Mac with no record answers «being checked», so an answer given by another account or
+ * kind of service is never offered while the new check runs. (`runIosBootCheck` never throws — a failed boot is a `fail` record; what can
+ * throw here is writing the record, and the callers log that.)
+ */
+export declare function refreshIosCheck(paths: RunnerHomePaths, deps: IosCheckDeps, options: IosRefreshOptions): Promise<IosCheckRecord | null>;
+export {};
+//# sourceMappingURL=iosCheck.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"iosCheck.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/iosCheck.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAgBpD,eAAO,MAAM,gBAAgB,QAAa,CAAC;AAG3C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE,QAAA,MAAM,cAAc;;;;;;;;;kBAMlB,CAAC;AAEH,0DAA0D;AAC1D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAgCD,uKAAuK;AACvK,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAOrG;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/D;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIjF;AAQD,mIAAmI;AACnI,wBAAsB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA2BjF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,GAAG,IAAI,CAO1E;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAElF;AAED,wIAAwI;AACxI,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGxG;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQ5I"}

package/dist/runnerUtility/iosCheck.js

@@ -0,0 +1,200 @@
+"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.iosBootFailureReasonPrefix = exports.iosCheckBudgetMs = void 0;
+exports.chooseSimulator = chooseSimulator;
+exports.parseXcodeVersion = parseXcodeVersion;
+exports.createIosCheckDeps = createIosCheckDeps;
+exports.readXcodeVersion = readXcodeVersion;
+exports.runIosBootCheck = runIosBootCheck;
+exports.readIosCheck = readIosCheck;
+exports.writeIosCheck = writeIosCheck;
+exports.checkShouldRunIosCheck = checkShouldRunIosCheck;
+exports.refreshIosCheck = refreshIosCheck;
+const fs = __importStar(require("fs"));
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const commandRunner_1 = require("../selfUpdate/commandRunner");
+/**
+ * @description Can this runner drive the iOS Simulator? Apple: the Simulator is not available to a LaunchDaemon or a process started as
+ * another user — it needs the account's own login session. So the runner does not guess from «Xcode is installed»: it really boots one.
+ * A bounded check (create a device → boot it → wait for the boot to finish → delete it) runs when the link starts and whenever Xcode
+ * changes, and its result is written to `ios-check.json`, one line, for `runner.sh probe` to turn into the `ios` capability:
+ *
+ *   pass     the Simulator boots here → `ios`
+ *   fail     it does not → «ios: no — needs the runner user's login session» (a helper in that user's GUI session is a follow-up)
+ *   skipped  not macOS, or no Xcode → nothing to say
+ *
+ * Whatever happens, the simulator device the check made is deleted again.
+ */
+const stepTimeoutMs = 60 * 1000;
+exports.iosCheckBudgetMs = 180 * 1000;
+const checkDeviceName = 'charness-runner-boot-check';
+/**
+ * How the reason of a `fail` record that is the Simulator's own boot refusal begins. `runner.sh` tells the operator «needs the runner
+ * user's login session» for those — Apple gives no Simulator to a daemon — and shows the reason itself for every other failure (no
+ * runtime installed, the device could not be created); a test pins that the script carries this very text.
+ */
+exports.iosBootFailureReasonPrefix = 'the Simulator did not';
+const iosCheckSchema = zod_1.z.strictObject({
+    status: zod_1.z.enum(['pass', 'fail', 'skipped']),
+    checkedAtMs: zod_1.z.number().int().nonnegative(),
+    /** `16.2 (16C5032a)`: what Xcode was when this was checked; a different one means check again. */
+    xcode: zod_1.z.string().nullable(),
+    reason: zod_1.z.string().nullable(),
+});
+function compareVersions(left, right) {
+    const leftParts = left.split('.').map(Number);
+    const rightParts = right.split('.').map(Number);
+    for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+        const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function parseJsonObject(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** @description The newest available iOS runtime and an iPhone device type (the newest the list names), out of `simctl list runtimes -j` and `list devicetypes -j`. */
+function chooseSimulator(runtimesJson, deviceTypesJson) {
+    const runtimes = parseJsonObject(runtimesJson)?.runtimes ?? [];
+    const deviceTypes = parseJsonObject(deviceTypesJson)?.devicetypes ?? [];
+    const ios = runtimes.filter((runtime) => runtime.platform === 'iOS' && runtime.isAvailable !== false).sort((left, right) => compareVersions(right.version, left.version));
+    const iphones = deviceTypes.filter((deviceType) => deviceType.productFamily === 'iPhone');
+    const iphone = iphones.at(-1);
+    return ios.length === 0 || iphone === undefined ? null : { runtimeId: ios[0].identifier, deviceTypeId: iphone.identifier };
+}
+/** @description `16.2 (16C5032a)` out of `xcodebuild -version`, or `null`. */
+function parseXcodeVersion(output) {
+    const version = /Xcode\s+(\S+)/.exec(output)?.[1];
+    const build = /Build version\s+(\S+)/.exec(output)?.[1];
+    return version === undefined ? null : build === undefined ? version : `${version} (${build})`;
+}
+function createIosCheckDeps() {
+    return { runner: commandRunner_1.runCommand, platform: process.platform, now: Date.now };
+}
+async function readXcodeVersion(deps) {
+    if (deps.platform !== 'darwin')
+        return null;
+    const result = await deps.runner('xcodebuild', ['-version'], { timeoutMs: stepTimeoutMs });
+    return result.ok ? parseXcodeVersion(result.stdout) : null;
+}
+/** `simctl <step> failed: <last line of its stderr>` (or how it ended): the reason for a simctl command that did not work at all, which is not the same as «nothing installed». */
+function describeSimctlFailure(stepName, result) {
+    const lastErrorLine = result.stderr.trim().split('\n').slice(-1)[0];
+    return `simctl ${stepName} failed: ${lastErrorLine !== '' ? lastErrorLine : result.isTimedOut ? 'no answer in time' : `exit ${result.exitCode ?? 'none'}`}`;
+}
+/** @description Run the boot check: create → boot → bootstatus → delete. Never throws; the device is deleted whatever happened. */
+async function runIosBootCheck(deps) {
+    const xcode = await readXcodeVersion(deps);
+    const record = (status, reason) => ({ status, checkedAtMs: deps.now(), xcode, reason });
+    if (deps.platform !== 'darwin')
+        return record('skipped', 'not macOS');
+    if (xcode === null)
+        return record('skipped', 'no Xcode');
+    const deadline = deps.now() + exports.iosCheckBudgetMs;
+    const step = (args) => deps.runner('xcrun', ['simctl', ...args], { timeoutMs: Math.max(1000, Math.min(stepTimeoutMs, deadline - deps.now())) });
+    const runtimes = await step(['list', 'runtimes', '-j']);
+    const deviceTypes = await step(['list', 'devicetypes', '-j']);
+    // A simctl that cannot be run (it cannot reach CoreSimulator, for one) is told as that — «no runtime installed» is only for a list that worked.
+    if (!runtimes.ok)
+        return record('fail', describeSimctlFailure('list runtimes', runtimes));
+    if (!deviceTypes.ok)
+        return record('fail', describeSimctlFailure('list devicetypes', deviceTypes));
+    const choice = chooseSimulator(runtimes.stdout, deviceTypes.stdout);
+    if (choice === null)
+        return record('fail', 'no iOS simulator runtime and iPhone device type are installed');
+    const created = await step(['create', checkDeviceName, choice.deviceTypeId, choice.runtimeId]);
+    if (!created.ok)
+        return record('fail', describeSimctlFailure('create', created));
+    const udid = created.stdout.trim();
+    if (udid === '')
+        return record('fail', 'the Simulator device could not be created');
+    try {
+        const boot = await step(['boot', udid]);
+        if (!boot.ok)
+            return record('fail', `${exports.iosBootFailureReasonPrefix} boot: ${boot.stderr.trim().split('\n').slice(-1)[0]}`);
+        const status = await step(['bootstatus', udid, '-b']);
+        return status.ok ? record('pass', null) : record('fail', `${exports.iosBootFailureReasonPrefix} finish booting: ${status.stderr.trim().split('\n').slice(-1)[0]}`);
+    }
+    finally {
+        await step(['shutdown', udid]);
+        await step(['delete', udid]);
+    }
+}
+function readIosCheck(paths) {
+    try {
+        const parsed = iosCheckSchema.safeParse(JSON.parse(fs.readFileSync(paths.iosCheck, 'utf8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** @description One line, so `runner.sh probe` can read it with `grep`. */
+function writeIosCheck(paths, record) {
+    (0, configDirFile_1.writeTextFileAtomically)(paths.iosCheck, `${JSON.stringify(iosCheckSchema.parse(record))}\n`, 0o644);
+}
+/** @description Check again when there is no result yet or Xcode is another one than the last result saw (a version, a build, gone). */
+function checkShouldRunIosCheck(last, currentXcode) {
+    if (currentXcode === null)
+        return last === null || last.status !== 'skipped' || last.xcode !== null;
+    return last === null || last.xcode !== currentXcode;
+}
+/**
+ * @description At the link's start (always) and then once an hour (when Xcode is not what the last result saw): run the boot check and record it.
+ * At the start the old record is deleted first: a paired Mac with no record answers «being checked», so an answer given by another account or
+ * kind of service is never offered while the new check runs. (`runIosBootCheck` never throws — a failed boot is a `fail` record; what can
+ * throw here is writing the record, and the callers log that.)
+ */
+async function refreshIosCheck(paths, deps, options) {
+    if (deps.platform !== 'darwin')
+        return null;
+    if (options.isStartup)
+        fs.rmSync(paths.iosCheck, { force: true });
+    const current = await readXcodeVersion(deps);
+    if (!options.isStartup && !checkShouldRunIosCheck(readIosCheck(paths), current))
+        return null;
+    const record = await runIosBootCheck(deps);
+    writeIosCheck(paths, record);
+    return record;
+}
+//# sourceMappingURL=iosCheck.js.map

package/dist/runnerUtility/iosCheck.js.map

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

package/dist/runnerUtility/launcher.d.ts

@@ -0,0 +1,5 @@
+import type { RunnerHomePaths } from './runnerHome';
+export declare function renderLauncher(paths: Pick<RunnerHomePaths, 'currentApp'>, nodePath: string): string;
+/** @description Write the launcher (when it differs) and return its path. */
+export declare function ensureLauncher(paths: RunnerHomePaths, nodePath: string): string;
+//# sourceMappingURL=launcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/launcher.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkBnG;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW/E"}

package/dist/runnerUtility/launcher.js

@@ -0,0 +1,85 @@
+"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.renderLauncher = renderLauncher;
+exports.ensureLauncher = ensureLauncher;
+const fs = __importStar(require("fs"));
+const configDirFile_1 = require("../configDirFile");
+const tmuxExec_1 = require("../utils/tmuxExec");
+const appInstall_1 = require("./appInstall");
+/**
+ * @description `~/.charness-runner/bin/charness-runner`: a two-line `sh` loop that starts the app `current` points at and starts it
+ * AGAIN when it exits with {@link restartExitCode} (an update installed a newer copy). The app runs in the background of the
+ * script so that the script can pass TERM / INT / HUP on to it: under systemd's `KillMode=process` only the script is signalled, and
+ * without the forwarding the app would be left running unsupervised. Terminal runs, the systemd unit and the launchd
+ * job all start this one file, so an update needs no service reinstall. `node` is the one that made the file; if it has moved, the
+ * `node` on PATH is tried.
+ */
+const launcherMode = 0o755;
+function renderLauncher(paths, nodePath) {
+    const cli = `${paths.currentApp}/dist/runnerUtility/runnerCli.js`;
+    return [
+        '#!/bin/sh',
+        '# Written by charness-runner. Exit code 75 asks for a restart onto an updated copy; TERM / INT / HUP go to the app.',
+        `NODE=${(0, tmuxExec_1.shellSingleQuote)(nodePath)}`,
+        '[ -x "$NODE" ] || NODE=node',
+        'child=',
+        'trap \'[ -n "$child" ] && kill -TERM "$child" 2>/dev/null\' TERM INT HUP',
+        'while :; do',
+        `  "$NODE" ${(0, tmuxExec_1.shellSingleQuote)(cli)} "$@" &`,
+        '  child=$!',
+        '  code=0',
+        '  while kill -0 "$child" 2>/dev/null; do wait "$child"; code=$?; done',
+        `  [ "$code" = ${appInstall_1.restartExitCode} ] || exit "$code"`,
+        'done',
+        '',
+    ].join('\n');
+}
+/** @description Write the launcher (when it differs) and return its path. */
+function ensureLauncher(paths, nodePath) {
+    fs.mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+    const text = renderLauncher(paths, nodePath);
+    let current = null;
+    try {
+        current = fs.readFileSync(paths.launcher, 'utf8');
+    }
+    catch {
+        current = null;
+    }
+    if (current !== text)
+        (0, configDirFile_1.writeTextFileAtomically)(paths.launcher, text, launcherMode);
+    return paths.launcher;
+}
+//# sourceMappingURL=launcher.js.map

package/dist/runnerUtility/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/runnerUtility/launcher.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBA,wCAkBC;AAGD,wCAWC;AAjDD,uCAAyB;AACzB,oDAA2D;AAC3D,gDAAqD;AACrD,6CAA+C;AAG/C;;;;;;;GAOG;AAEH,MAAM,YAAY,GAAG,KAAK,CAAC;AAE3B,SAAgB,cAAc,CAAC,KAA0C,EAAE,QAAgB;IACzF,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,UAAU,kCAAkC,CAAC;IAClE,OAAO;QACL,WAAW;QACX,qHAAqH;QACrH,QAAQ,IAAA,2BAAgB,EAAC,QAAQ,CAAC,EAAE;QACpC,6BAA6B;QAC7B,QAAQ;QACR,0EAA0E;QAC1E,aAAa;QACb,aAAa,IAAA,2BAAgB,EAAC,GAAG,CAAC,SAAS;QAC3C,YAAY;QACZ,UAAU;QACV,uEAAuE;QACvE,iBAAiB,4BAAe,oBAAoB;QACpD,MAAM;QACN,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,SAAgB,cAAc,CAAC,KAAsB,EAAE,QAAgB;IACrE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,KAAK,IAAI;QAAE,IAAA,uCAAuB,EAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;IAClF,OAAO,KAAK,CAAC,QAAQ,CAAC;AACxB,CAAC"}

package/dist/runnerUtility/linkLoop.d.ts

@@ -0,0 +1,47 @@
+import { updateFromHub } from './appUpdate';
+import { connectToHub } from './hubClient';
+import { type RunnerConfig } from './runnerConfig';
+import type { RunnerHomePaths } from './runnerHome';
+import type { RunnerKeys } from './runnerKeys';
+import type { RunnerServers } from './runnerServers';
+export declare const removedRetryMs: number;
+/** How long after the first refusal of the key a second one confirms that the runner was removed. */
+export declare const removalConfirmMs: number;
+/**
+ * How long the hub must have been refusing the key, without ever saying «this runner is not paired», before the runner takes the refusal
+ * for a removal worth killing its jobs for. A refused key alone is also what a hub with a locked home folder, a changed file mode or an
+ * edited sshd setting looks like, and those last hours (a night, until someone unlocks the volume); killing a long run for them is the
+ * wrong mistake. A hub that removes an ONLINE runner stops its jobs itself over the link (`runners/runnerRemoval.ts`), and a hub that can
+ * answer says so (`identity`), so this only covers a machine that was off when it was removed.
+ */
+export declare const unconfirmedRemovalStopAfterMs: number;
+/** @description The wait before attempt number `failures + 1` (0 failures: the first retry); `random` is in [0, 1). */
+export declare function computeBackoffMs(failures: number, random: number): number;
+export interface LinkLoopDeps {
+    paths: RunnerHomePaths;
+    config: RunnerConfig;
+    keys: RunnerKeys;
+    servers: RunnerServers;
+    now?: () => number;
+    /** How often a linked runner asks the hub for its package (default: {@link readRunnerVersionPollMs}). */
+    versionPollMs?: number;
+    /** Stops the jobs of the queue; called when the runner learns it was removed. */
+    stopJobs?: () => Promise<void>;
+    /** The wait between the two refusals that confirm a removal (default {@link removalConfirmMs}). */
+    removalConfirmMs?: number;
+    /** How long a bare refusal of the key must last before it stops the jobs (default {@link unconfirmedRemovalStopAfterMs}). */
+    unconfirmedRemovalStopAfterMs?: number;
+    random?: () => number;
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    connect?: typeof connectToHub;
+    update?: typeof updateFromHub;
+    log?: (line: string) => void;
+}
+export interface LinkLoopHandle {
+    /** Run until aborted (resolves 0) or until an update asks for a restart (resolves {@link restartExitCode}). */
+    run: (signal: AbortSignal) => Promise<number>;
+    /** The built-in server calls this whenever the number of running commands changes. */
+    notifyActiveCountChange: () => void;
+}
+export declare function createLinkLoop(deps: LinkLoopDeps): LinkLoopHandle;
+//# sourceMappingURL=linkLoop.d.ts.map