charness 3.6.0 → 3.7.0

package/dist/remoteRun/foreground.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeEnd = describeEnd;
+exports.followForeground = followForeground;
+exports.runExec = runExec;
+const exitCodes_1 = require("./exitCodes");
+const interrupts_1 = require("./interrupts");
+const jobFiles_1 = require("./jobFiles");
+const jobQuery_1 = require("./jobQuery");
+const leaseTiming_1 = require("./leaseTiming");
+const output_1 = require("./output");
+const remoteRunError_1 = require("./remoteRunError");
+const runnerClient_1 = require("./runnerClient");
+const ssh_1 = require("./ssh");
+/**
+ * @description A foreground run and `exec`: the live ssh session that owns a job. The session runs the runner script's `lease`, which
+ * itself adds the job to Pueue (so no job ever exists without its lease), streams the job's log, and kills the job when the heartbeat
+ * byte this side writes stops (a SIGKILLed remote-run, a dead connection — a stock sshd never notices a half-open one). SIGINT, SIGTERM
+ * and SIGHUP kill the whole remote job over the shared connection first (TERM, SIGKILL after 10 s on the runner), then exit with the
+ * shell's code for the signal; the local `--timeout` does the same and exits 124.
+ */
+/** The reason `runner.sh kill` takes for a kill that is the caller's time limit running out. */
+const killReasonTimeout = 'timeout';
+/** After a kill or an interrupt the lease session ends by itself (the runner's grace time, and as long again); this long before the ssh process is cut. */
+const streamEndGraceMs = 2 * exitCodes_1.killGraceSeconds * 1000;
+/**
+ * @description Say why a job ended the way it did (when it is not simply its command's own code) and return remote-run's exit code for it.
+ * `runnerStderr` is what the runner script wrote on the session that ran the job: a job it refused at once (`pueue add` failed) has no
+ * state to show, and that last line is the only thing that says why.
+ */
+function describeEnd(outcome, jobId, io, runnerStderr = '') {
+    if (outcome.state !== 'done') {
+        const runnerSaid = (0, runnerClient_1.describeRunnerRefusal)(runnerStderr, '');
+        if (runnerSaid !== '')
+            (0, output_1.sayOwn)(io, `the runner said: ${runnerSaid}`);
+        (0, output_1.sayOwn)(io, `the state of job ${jobId} is unknown (${outcome.state}) — see \`charness remote-run status ${jobId}\``);
+        return exitCodes_1.remoteRunExitCodes.failed;
+    }
+    if (outcome.reason === 'deps-failed')
+        (0, output_1.sayOwn)(io, 'the dependencies step failed — its output is above');
+    else if (outcome.reason === 'timeout')
+        (0, output_1.sayOwn)(io, 'the job timed out and was killed');
+    else if (outcome.reason === 'killed')
+        (0, output_1.sayOwn)(io, `job ${jobId} was killed`);
+    else if (outcome.reason === 'lost')
+        (0, output_1.sayOwn)(io, `job ${jobId} ended without a result (its process was lost)`);
+    return outcome.code;
+}
+/** @description Follow a staged job in the foreground; resolves with remote-run's exit code. */
+async function followForeground(params) {
+    const { client, staged, io } = params;
+    const child = client.stream('lease', [staged.slug, staged.jobId, staged.group, `${params.leaseMs}`]);
+    const router = (0, output_1.createJobOutputRouter)(io);
+    let sshStderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => router.write(chunk));
+    child.stderr.on('data', (chunk) => { sshStderr += chunk; });
+    child.stdin.on('error', () => { });
+    let interrupt = null;
+    let isTimedOut = false;
+    let killing = null;
+    const closed = (0, interrupts_1.waitForChildEnd)(child, () => killing !== null);
+    const writeHeartbeat = () => {
+        child.stdin.write('h');
+    };
+    writeHeartbeat();
+    const heartbeatTimer = setInterval(writeHeartbeat, (0, leaseTiming_1.getHeartbeatIntervalMs)(params.leaseMs));
+    const killJob = () => {
+        killing ??= (async () => {
+            clearInterval(heartbeatTimer);
+            // A kill because the limit ran out is recorded as the limit (124), as the runner's own watchdog records it when it gets there first.
+            await client.call('kill', [staged.slug, staged.jobId, ...(isTimedOut ? [killReasonTimeout] : [])], { timeoutMs: interrupts_1.killCallTimeoutMs });
+            setTimeout(() => child.kill('SIGKILL'), streamEndGraceMs).unref();
+        })();
+        return killing;
+    };
+    const removeSignalHandlers = (0, interrupts_1.addInterruptHandler)((signal) => {
+        interrupt ??= signal;
+        void killJob();
+    });
+    const timeoutTimer = setTimeout(() => {
+        isTimedOut = true;
+        void killJob();
+    }, staged.timeoutSeconds * 1000);
+    await closed;
+    clearInterval(heartbeatTimer);
+    clearTimeout(timeoutTimer);
+    removeSignalHandlers();
+    router.flush();
+    if (killing !== null)
+        await killing;
+    if (interrupt !== null) {
+        (0, output_1.sayOwn)(io, `interrupted — job ${staged.jobId} was stopped on ${client.runner.name}`);
+        return (0, exitCodes_1.planInterrupt)(interrupt).exitCode;
+    }
+    let result;
+    try {
+        result = await (0, jobQuery_1.readJobOutcome)(client, staged.slug, staged.jobId);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : 'no answer';
+        (0, output_1.sayOwn)(io, `lost the connection to ${client.runner.name} (${sshStderr.trim().split('\n').pop() || detail}); the runner stops job ${staged.jobId} itself when its lease runs out`);
+        return exitCodes_1.remoteRunExitCodes.failed;
+    }
+    try {
+        await (0, jobFiles_1.fetchJobFiles)({ client, facts: result.facts, jobId: staged.jobId, target: params.target, io });
+    }
+    catch (error) {
+        (0, output_1.sayOwn)(io, error instanceof remoteRunError_1.RemoteRunError ? error.message : 'the result files could not be fetched');
+    }
+    if (isTimedOut) {
+        (0, output_1.sayOwn)(io, `timed out after ${staged.timeoutSeconds}s — job ${staged.jobId} was killed`);
+        return exitCodes_1.remoteRunExitCodes.timedOut;
+    }
+    return describeEnd(result.outcome, staged.jobId, io, sshStderr);
+}
+/** @description Run a one-off command in the runner's copy under the same lease; resolves with the command's exit code. */
+async function runExec(params) {
+    const { client, io } = params;
+    const child = client.stream('exec', [params.slug, params.subfolder, `${params.leaseMs}`, params.command]);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => io.stdout(chunk));
+    const stderr = (0, output_1.createExitMarkerFilter)(io.stderr);
+    child.stderr.on('data', (chunk) => stderr.write(chunk));
+    child.stdin.on('error', () => { });
+    let interrupt = null;
+    const closed = (0, interrupts_1.waitForChildEnd)(child, () => interrupt !== null);
+    const writeHeartbeat = () => {
+        child.stdin.write('h');
+    };
+    writeHeartbeat();
+    const heartbeatTimer = setInterval(writeHeartbeat, (0, leaseTiming_1.getHeartbeatIntervalMs)(params.leaseMs));
+    const removeSignalHandlers = (0, interrupts_1.addInterruptHandler)((signal) => {
+        interrupt ??= signal;
+        clearInterval(heartbeatTimer);
+        // The end of the stream without a "done" byte is what makes the runner kill the command's group.
+        child.stdin.end();
+        setTimeout(() => child.kill('SIGKILL'), streamEndGraceMs).unref();
+    });
+    const exitCode = await closed;
+    clearInterval(heartbeatTimer);
+    removeSignalHandlers();
+    stderr.flush();
+    if (interrupt !== null)
+        return (0, exitCodes_1.planInterrupt)(interrupt).exitCode;
+    // The command's own code, as the runner reported it: a command that exits 255 is not a lost connection. Without the report the session
+    // died before the command ended, or ssh itself failed.
+    const reportedCode = stderr.getExitCode();
+    if (reportedCode !== null)
+        return reportedCode;
+    if ((0, ssh_1.checkIsConnectionLost)(exitCode)) {
+        (0, output_1.sayOwn)(io, `the connection to ${client.runner.name} failed while the command ran`);
+        return exitCodes_1.remoteRunExitCodes.failed;
+    }
+    return exitCode ?? exitCodes_1.remoteRunExitCodes.failed;
+}
+//# sourceMappingURL=foreground.js.map

package/dist/remoteRun/foreground.js.map

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

package/dist/remoteRun/interrupts.d.ts

@@ -0,0 +1,17 @@
+import type { ChildProcess } from 'child_process';
+import { type InterruptSignal } from './exitCodes';
+export declare const killCallTimeoutMs: number;
+/**
+ * @description Run `handler` for SIGINT, SIGTERM and SIGHUP — a listener also keeps Node from ending the process by itself, so the
+ * command decides how it ends (kill the remote job first). Returns the function that removes the listeners.
+ */
+export declare function addInterruptHandler(handler: (signal: InterruptSignal) => void): () => void;
+/**
+ * @description Resolves with the exit code when `child` has ended. Normally that is its `close` (the process is gone AND its output
+ * has been read to the end). Once `getIsStopped()` says the caller ended it on purpose, its `exit` is enough and the caller's end of
+ * its pipes is released: an ssh client that shares a master connection passes its stdio to the master, which keeps those pipes open
+ * until the REMOTE command ends — so after a kill the process is dead, `close` never comes, and the command would hang for as long as
+ * the remote side runs (hours, for a `wait`).
+ */
+export declare function waitForChildEnd(child: ChildProcess, getIsStopped: () => boolean): Promise<number | null>;
+//# sourceMappingURL=interrupts.d.ts.map

package/dist/remoteRun/interrupts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupts.d.ts","sourceRoot":"","sources":["../../src/remoteRun/interrupts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAsC,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAIvF,eAAO,MAAM,iBAAiB,QAAoD,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAO1F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAUxG"}

package/dist/remoteRun/interrupts.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killCallTimeoutMs = void 0;
+exports.addInterruptHandler = addInterruptHandler;
+exports.waitForChildEnd = waitForChildEnd;
+const exitCodes_1 = require("./exitCodes");
+/** A `kill` call waits for the runner's grace time, then its own SIGKILL and the call itself. */
+const killCallMarginSeconds = 30;
+exports.killCallTimeoutMs = (exitCodes_1.killGraceSeconds + killCallMarginSeconds) * 1000;
+/**
+ * @description Run `handler` for SIGINT, SIGTERM and SIGHUP — a listener also keeps Node from ending the process by itself, so the
+ * command decides how it ends (kill the remote job first). Returns the function that removes the listeners.
+ */
+function addInterruptHandler(handler) {
+    const listeners = exitCodes_1.interruptSignals.map((signal) => {
+        const listener = () => handler(signal);
+        process.on(signal, listener);
+        return { signal, listener };
+    });
+    return () => listeners.forEach(({ signal, listener }) => process.off(signal, listener));
+}
+/**
+ * @description Resolves with the exit code when `child` has ended. Normally that is its `close` (the process is gone AND its output
+ * has been read to the end). Once `getIsStopped()` says the caller ended it on purpose, its `exit` is enough and the caller's end of
+ * its pipes is released: an ssh client that shares a master connection passes its stdio to the master, which keeps those pipes open
+ * until the REMOTE command ends — so after a kill the process is dead, `close` never comes, and the command would hang for as long as
+ * the remote side runs (hours, for a `wait`).
+ */
+function waitForChildEnd(child, getIsStopped) {
+    return new Promise((resolve) => {
+        child.once('close', (exitCode) => resolve(exitCode));
+        child.once('exit', (exitCode) => {
+            if (!getIsStopped())
+                return;
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            resolve(exitCode);
+        });
+    });
+}
+//# sourceMappingURL=interrupts.js.map

package/dist/remoteRun/interrupts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupts.js","sourceRoot":"","sources":["../../src/remoteRun/interrupts.ts"],"names":[],"mappings":";;;AAWA,kDAOC;AASD,0CAUC;AApCD,2CAAuF;AAEvF,iGAAiG;AACjG,MAAM,qBAAqB,GAAG,EAAE,CAAC;AACpB,QAAA,iBAAiB,GAAG,CAAC,4BAAgB,GAAG,qBAAqB,CAAC,GAAG,IAAI,CAAC;AAEnF;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,OAA0C;IAC5E,MAAM,SAAS,GAAG,4BAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAChD,MAAM,QAAQ,GAAG,GAAS,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,KAAmB,EAAE,YAA2B;IAC9E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;YAC9B,IAAI,CAAC,YAAY,EAAE;gBAAE,OAAO;YAC5B,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACxB,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/remoteRun/jobFiles.d.ts

@@ -0,0 +1,31 @@
+import type { JobFacts } from './jobState';
+import { type CliIo } from './output';
+import type { RunnerClient } from './runnerClient';
+import type { LocalJobRecord } from './jobRecords';
+/**
+ * @description Bring a finished job's result files back. The job kept them on the runner under `jobs/<job>/artifacts/` (only what it
+ * created or changed and `pull:` names); they are rsynced without symlinks into a temp folder and copied into the project by
+ * `safeCopy.ts`. The project is the one the job was submitted from, as the MAIN BOX recorded it (`jobRecords.ts`) — never what the
+ * runner says — and the `pull:` patterns are those of that project's LOCAL `.remote-run`.
+ */
+export interface FetchTarget {
+    root: string;
+    /** The project's folder name on the runner, from the local record. */
+    slug: string;
+    patterns: string[];
+    /** Folders of the project git takes hooks from (`getHookDirectories`): nothing a runner returns lands in them. */
+    hookDirectories: string[];
+}
+/** @description The target for the project at `root`: its hook folders are read now, from the project's own git configuration. */
+export declare function createFetchTarget(root: string, slug: string, patterns: string[]): FetchTarget;
+/** @description The local project a job's files go back to, from the local record; an error says why there is none. */
+export declare function resolveFetchTarget(record: LocalJobRecord | null): FetchTarget;
+/** @description Fetch `jobId`'s result files into `target`; says how many came back. A job with none, or a project that names none, is not an error. */
+export declare function fetchJobFiles(params: {
+    client: RunnerClient;
+    facts: JobFacts;
+    jobId: string;
+    target: FetchTarget;
+    io: Pick<CliIo, 'stderr'>;
+}): Promise<void>;
+//# sourceMappingURL=jobFiles.d.ts.map

package/dist/remoteRun/jobFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobFiles.d.ts","sourceRoot":"","sources":["../../src/remoteRun/jobFiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAI9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kHAAkH;IAClH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,kIAAkI;AAClI,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,CAE7F;AAED,uHAAuH;AACvH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,WAAW,CAI7E;AAED,wJAAwJ;AACxJ,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnK"}

package/dist/remoteRun/jobFiles.js

@@ -0,0 +1,84 @@
+"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.createFetchTarget = createFetchTarget;
+exports.resolveFetchTarget = resolveFetchTarget;
+exports.fetchJobFiles = fetchJobFiles;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const output_1 = require("./output");
+const project_1 = require("./project");
+const remoteRunError_1 = require("./remoteRunError");
+const rsync_1 = require("./rsync");
+const safeCopy_1 = require("./safeCopy");
+const sendPlan_1 = require("./sendPlan");
+/** @description The target for the project at `root`: its hook folders are read now, from the project's own git configuration. */
+function createFetchTarget(root, slug, patterns) {
+    return { root, slug, patterns, hookDirectories: (0, project_1.getHookDirectories)(root) };
+}
+/** @description The local project a job's files go back to, from the local record; an error says why there is none. */
+function resolveFetchTarget(record) {
+    if (record === null)
+        throw new remoteRunError_1.RemoteRunError('this machine did not submit the job as this user (or its record is gone) — its files are not fetched');
+    if (!fs.existsSync(record.projectRoot) || !fs.statSync(record.projectRoot).isDirectory())
+        throw new remoteRunError_1.RemoteRunError(`the job's project folder is gone from this machine: ${record.projectRoot}`);
+    return createFetchTarget(record.projectRoot, record.slug, (0, project_1.readProjectConfig)(record.projectRoot).pull);
+}
+/** @description Fetch `jobId`'s result files into `target`; says how many came back. A job with none, or a project that names none, is not an error. */
+async function fetchJobFiles(params) {
+    const { client, facts, target } = params;
+    if (!facts.isWithArtifacts || target.patterns.length === 0)
+        return;
+    const workDir = await client.getAbsoluteWorkDir();
+    const fetchedRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'remote-run-files-'));
+    try {
+        const fetched = await (0, rsync_1.runRsync)((0, sendPlan_1.buildRsyncFetchArgs)({
+            sshCommand: client.rsyncSshCommand,
+            source: `${client.runner.ssh}:${workDir}/p/${target.slug}/jobs/${params.jobId}/artifacts`,
+            destinationDirectory: fetchedRoot,
+        }));
+        if (!fetched.isOk)
+            throw new remoteRunError_1.RemoteRunError(`fetching the result files from "${client.runner.name}" failed — ${fetched.errorTail}`);
+        const copied = (0, safeCopy_1.copyFetchedFiles)({ fetchedRoot, projectRoot: target.root, patterns: target.patterns, hookDirectories: target.hookDirectories });
+        if (copied.copied.length > 0 || copied.refusedCount > 0) {
+            (0, output_1.sayOwn)(params.io, `${copied.copied.length} result file${copied.copied.length === 1 ? '' : 's'} came back${copied.refusedCount > 0 ? `, ${copied.refusedCount} refused (not a regular file a "pull:" pattern names, or inside a .git, the project's .remote-run or a git hooks folder)` : ''}`);
+        }
+    }
+    finally {
+        fs.rmSync(fetchedRoot, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=jobFiles.js.map

package/dist/remoteRun/jobFiles.js.map

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

package/dist/remoteRun/jobFormat.d.ts

@@ -0,0 +1,16 @@
+import { type JobFacts, type JobOutcome } from './jobState';
+import type { JobMeta } from './jobMeta';
+/** @description `45s`, `3m12s`, `2h05m`, `1d3h`. */
+export declare function formatDuration(totalSeconds: number): string;
+/** @description `just now`, `5m ago`, `2h ago`, `3d ago`. */
+export declare function formatAge(elapsedSeconds: number): string;
+export interface JobEntry {
+    meta: JobMeta;
+    facts: JobFacts;
+    outcome: JobOutcome;
+}
+/** @description The lines of `ls`: columns aligned, newest job first. */
+export declare function formatJobList(entries: readonly JobEntry[], nowMs: number): string[];
+/** @description The block of `status <id>`. */
+export declare function formatJobStatus(entry: JobEntry, nowMs: number): string;
+//# sourceMappingURL=jobFormat.d.ts.map

package/dist/remoteRun/jobFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobFormat.d.ts","sourceRoot":"","sources":["../../src/remoteRun/jobFormat.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAazC,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAMxD;AAMD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,UAAU,CAAC;CACrB;AAuBD,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBnF;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBtE"}

package/dist/remoteRun/jobFormat.js

@@ -0,0 +1,130 @@
+"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.formatDuration = formatDuration;
+exports.formatAge = formatAge;
+exports.formatJobList = formatJobList;
+exports.formatJobStatus = formatJobStatus;
+const path = __importStar(require("path"));
+const jobState_1 = require("./jobState");
+/**
+ * @description How `ls` and `status` show a job: one aligned line per job newest first, and a short block for one. Times are UTC and
+ * written out (`2026-10-31 22:10 UTC`), ages and durations short (`3m12s`, `2h ago`).
+ */
+const secondsPerMinute = 60;
+const secondsPerHour = 3600;
+const secondsPerDay = 86400;
+const commandColumnLimit = 70;
+const twoDigits = 2;
+/** @description `45s`, `3m12s`, `2h05m`, `1d3h`. */
+function formatDuration(totalSeconds) {
+    const seconds = Math.max(0, Math.round(totalSeconds));
+    if (seconds < secondsPerMinute)
+        return `${seconds}s`;
+    if (seconds < secondsPerHour)
+        return `${Math.floor(seconds / secondsPerMinute)}m${(seconds % secondsPerMinute).toString().padStart(twoDigits, '0')}s`;
+    if (seconds < secondsPerDay)
+        return `${Math.floor(seconds / secondsPerHour)}h${Math.floor((seconds % secondsPerHour) / secondsPerMinute).toString().padStart(twoDigits, '0')}m`;
+    return `${Math.floor(seconds / secondsPerDay)}d${Math.floor((seconds % secondsPerDay) / secondsPerHour)}h`;
+}
+/** @description `just now`, `5m ago`, `2h ago`, `3d ago`. */
+function formatAge(elapsedSeconds) {
+    const seconds = Math.max(0, Math.round(elapsedSeconds));
+    if (seconds < secondsPerMinute)
+        return 'just now';
+    if (seconds < secondsPerHour)
+        return `${Math.floor(seconds / secondsPerMinute)}m ago`;
+    if (seconds < secondsPerDay)
+        return `${Math.floor(seconds / secondsPerHour)}h ago`;
+    return `${Math.floor(seconds / secondsPerDay)}d ago`;
+}
+function formatTimestamp(milliseconds) {
+    return `${new Date(milliseconds).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+function getProjectLabel(meta) {
+    const name = path.basename(meta.projectRoot);
+    return meta.subfolder === '' ? name : `${name}/${meta.subfolder}`;
+}
+/** The seconds the job has run (or ran): from its own start to its end, or to now while it runs. */
+function getRunSeconds(entry, nowMs) {
+    if (entry.facts.startedAtSeconds === null)
+        return null;
+    const endSeconds = entry.facts.finishedAtSeconds ?? Math.floor(nowMs / 1000);
+    return endSeconds - entry.facts.startedAtSeconds;
+}
+function getExitText(outcome) {
+    return outcome.state === 'done' ? `exit ${outcome.code}` : '';
+}
+function truncate(text, limit) {
+    const singleLine = text.replace(/\s+/g, ' ');
+    return singleLine.length > limit ? `${singleLine.slice(0, limit - 1)}…` : singleLine;
+}
+/** @description The lines of `ls`: columns aligned, newest job first. */
+function formatJobList(entries, nowMs) {
+    const sorted = [...entries].sort((first, second) => second.meta.submittedAtMs - first.meta.submittedAtMs);
+    const rows = sorted.map((entry) => {
+        const runSeconds = getRunSeconds(entry, nowMs);
+        return [
+            entry.meta.id,
+            (0, jobState_1.describeJobState)(entry.outcome),
+            getExitText(entry.outcome),
+            runSeconds === null ? '' : formatDuration(runSeconds),
+            formatAge((nowMs - entry.meta.submittedAtMs) / 1000),
+            getProjectLabel(entry.meta),
+            truncate(entry.meta.command, commandColumnLimit),
+        ];
+    });
+    const widths = rows.length === 0 ? [] : rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows.map((row) => row.map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column]))).join('  ').trimEnd());
+}
+/** @description The block of `status <id>`. */
+function formatJobStatus(entry, nowMs) {
+    const runSeconds = getRunSeconds(entry, nowMs);
+    const state = (0, jobState_1.describeJobState)(entry.outcome);
+    const exitText = getExitText(entry.outcome);
+    const times = [
+        `submitted ${formatTimestamp(entry.meta.submittedAtMs)}`,
+        entry.facts.startedAtSeconds === null ? 'not started' : `started ${formatTimestamp(entry.facts.startedAtSeconds * 1000)}`,
+        runSeconds === null ? null : `${entry.outcome.state === 'running' ? 'running for' : 'took'} ${formatDuration(runSeconds)}`,
+    ].filter((part) => part !== null);
+    return [
+        `job ${entry.meta.id} — ${state}${exitText === '' ? '' : ` (${exitText})`}`,
+        `  runner: ${entry.meta.runner}`,
+        `  project: ${getProjectLabel(entry.meta)}`,
+        `  command: ${entry.meta.command}`,
+        `  ${times.join(' · ')}`,
+    ].join('\n');
+}
+//# sourceMappingURL=jobFormat.js.map

package/dist/remoteRun/jobFormat.js.map

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

package/dist/remoteRun/jobId.d.ts

@@ -0,0 +1,15 @@
+export declare const pueueLabelPrefix = "rr-";
+/** @description A fresh id for a job that goes to `runnerName`. `random` is injectable for the tests. */
+export declare function createJobId(runnerName: string, random?: (size: number) => Buffer): string;
+/** @description The runner name inside a job id, or `null` when `text` is not a job id. */
+export declare function parseJobId(text: string): {
+    runnerName: string;
+} | null;
+/** @description The Pueue label that ties a Pueue task to its job. */
+export declare function getJobLabel(jobId: string): string;
+/** @description The runner-side folder name of the project at `projectRoot` for this main-box user. */
+export declare function getProjectSlug(projectRoot: string, owner: {
+    hostname: string;
+    uid: number;
+}): string;
+//# sourceMappingURL=jobId.d.ts.map

package/dist/remoteRun/jobId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobId.d.ts","sourceRoot":"","sources":["../../src/remoteRun/jobId.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAItC,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAoB,GAAG,MAAM,CAStG;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGtE;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAIpG"}

package/dist/remoteRun/jobId.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.pueueLabelPrefix = void 0;
+exports.createJobId = createJobId;
+exports.parseJobId = parseJobId;
+exports.getJobLabel = getJobLabel;
+exports.getProjectSlug = getProjectSlug;
+const crypto_1 = require("crypto");
+const path = __importStar(require("path"));
+/**
+ * @description Job ids and project slugs.
+ *
+ * A job id is `<runner>-<6 base32>`, made on the main box and stored on the runner as the Pueue label `rr-<id>` (Pueue's own ids
+ * restart after a reset, so they never name a job). The project slug names the runner-side copy of a project:
+ * `<basename>-<10 hex of sha256(hostname:uid:absolute root)>` — two main-box users or two checkouts of one project never share a copy.
+ */
+const base32Alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+const jobSuffixLength = 6;
+const slugHashLength = 10;
+const slugBasenameMaxLength = 40;
+const bitsPerBase32Digit = 5;
+const bitMask = 0b11111;
+const bytesPerSuffix = 4;
+exports.pueueLabelPrefix = 'rr-';
+const jobIdPattern = /^([a-z0-9]+(?:-[a-z0-9]+)*)-([a-z2-7]{6})$/;
+/** @description A fresh id for a job that goes to `runnerName`. `random` is injectable for the tests. */
+function createJobId(runnerName, random = crypto_1.randomBytes) {
+    const bytes = random(bytesPerSuffix);
+    let value = bytes.readUInt32BE(0);
+    let suffix = '';
+    for (let digit = 0; digit < jobSuffixLength; digit += 1) {
+        suffix += base32Alphabet[value & bitMask];
+        value = Math.floor(value / 2 ** bitsPerBase32Digit);
+    }
+    return `${runnerName}-${suffix}`;
+}
+/** @description The runner name inside a job id, or `null` when `text` is not a job id. */
+function parseJobId(text) {
+    const match = jobIdPattern.exec(text);
+    return match === null ? null : { runnerName: match[1] };
+}
+/** @description The Pueue label that ties a Pueue task to its job. */
+function getJobLabel(jobId) {
+    return `${exports.pueueLabelPrefix}${jobId}`;
+}
+/** @description The runner-side folder name of the project at `projectRoot` for this main-box user. */
+function getProjectSlug(projectRoot, owner) {
+    const baseName = path.basename(projectRoot).replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '_').slice(0, slugBasenameMaxLength) || 'project';
+    const hash = (0, crypto_1.createHash)('sha256').update(`${owner.hostname}:${owner.uid}:${projectRoot}`).digest('hex').slice(0, slugHashLength);
+    return `${baseName}-${hash}`;
+}
+//# sourceMappingURL=jobId.js.map