@almyty/runner 1.5.3 → 1.5.4

package/dist/enroll.d.ts

@@ -0,0 +1,91 @@
+import { RunnerConfig, RunnerRuntimeInfo } from './types.js';
+/** Where a pod finds the token: the Secret, through envFrom. */
+export declare const ENROLLMENT_TOKEN_ENV = "ALMYTY_ENROLLMENT_TOKEN";
+/** Or a file, for a pod that mounts the Secret instead of injecting it. */
+export declare const ENROLLMENT_TOKEN_FILE_ENV = "ALMYTY_ENROLLMENT_TOKEN_FILE";
+export declare const DEFAULT_ENROLL_PATH = "/runners/enroll";
+export declare const DEFAULT_HOSTED_STREAM_PATH = "/runners/hosted/stream";
+export declare const DEFAULT_HOSTED_RENEW_PATH = "/runners/hosted/credential";
+/** Enrollment could not happen; the process should exit non-zero. */
+export declare class EnrollmentError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface EnrollSettings {
+    backendUrl: string;
+    enrollPath: string;
+    /** Kept off every log line and error message. */
+    token: string;
+}
+type Env = Record<string, string | undefined>;
+/**
+ * The token and where to send it, from the environment the Deployment
+ * sets. Removes the token variables from `env` once read, so nothing the
+ * runner spawns later inherits them.
+ */
+export declare function readEnrollSettings(env?: Env, opts?: {
+    url?: string;
+    readFile?: (path: string) => string;
+}): EnrollSettings;
+export interface EnrollResult {
+    runnerId: string;
+    credential: string;
+    expiresAt: Date;
+    effectiveConfig: RunnerConfig;
+    streamPath: string;
+    renewPath: string;
+}
+/**
+ * Trade the token for a runner credential, once. Throws EnrollmentError
+ * on any refusal or malformed answer; the message never carries the token
+ * or a credential.
+ */
+export declare function enroll(settings: EnrollSettings, body: {
+    runtimeInfo: RunnerRuntimeInfo;
+    config?: Partial<RunnerConfig>;
+}, fetchImpl?: typeof globalThis.fetch): Promise<EnrollResult>;
+export interface RunnerCredentialOptions {
+    backendUrl: string;
+    renewPath: string;
+    credential: string;
+    expiresAt: Date;
+    /** Renewal is impossible: the process should stop. */
+    onFatal: (reason: string) => void;
+    log?: (line: string) => void;
+    fetch?: typeof globalThis.fetch;
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+    now?: () => number;
+}
+/**
+ * Holds the runner credential and renews it before it expires. `current()`
+ * is what every request reads, so a renewed credential is used from the
+ * next request on without reconnecting.
+ */
+export declare class RunnerCredential {
+    private readonly opts;
+    private credential;
+    private expiresAt;
+    private timer;
+    private stopped;
+    private readonly fetchImpl;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly now;
+    constructor(opts: RunnerCredentialOptions);
+    current(): string;
+    expiry(): Date;
+    /** Arm the renewal timer for the current credential. */
+    start(): void;
+    stop(): void;
+    /** When the current credential should be renewed, from now. */
+    renewDelay(): number;
+    /**
+     * One renewal attempt. Resolves true when a new credential is in place;
+     * otherwise schedules a retry, or reports fatal when the server refused
+     * or the credential will expire before another try.
+     */
+    renew(): Promise<boolean>;
+    private schedule;
+}
+export {};

package/dist/enroll.js

@@ -0,0 +1,261 @@
+/**
+ * Enroll mode: how a runner inside a hosted pod gets its identity.
+ *
+ * A hosted pod never holds anybody's login (docs/hosted-runners.md). The
+ * reconcile loop writes a single-use enrollment token into the pod's
+ * Secret, which the Deployment hands to the container as
+ * ALMYTY_ENROLLMENT_TOKEN (envFrom). This module trades that token once,
+ * at POST /runners/enroll, for a runner credential that only works on the
+ * runner's own stream and its renewal, and then keeps the credential fresh.
+ *
+ * The rules this file keeps:
+ *
+ *   - The credential lives in memory only. It is never written to disk,
+ *     never put in process.env (where every spawned command would inherit
+ *     it) and never printed: errors name the status and the server's
+ *     words, not the request.
+ *   - The enrollment token is removed from process.env as soon as it is
+ *     read, for the same reason. It is spent after one use anyway.
+ *   - Enrollment failing is fatal (EnrollmentError). The CLI exits
+ *     non-zero, Kubernetes restarts the container, and the reconcile loop
+ *     writes a fresh token if the pod does not enroll in time.
+ *   - The credential is renewed well before it expires. A renewal the
+ *     server refuses (401, 404: the hosted runner is gone) or one that
+ *     cannot succeed before expiry is fatal too.
+ */
+import { readFileSync } from 'node:fs';
+import { assertSecureBackendUrl } from './config.js';
+/** Where a pod finds the token: the Secret, through envFrom. */
+export const ENROLLMENT_TOKEN_ENV = 'ALMYTY_ENROLLMENT_TOKEN';
+/** Or a file, for a pod that mounts the Secret instead of injecting it. */
+export const ENROLLMENT_TOKEN_FILE_ENV = 'ALMYTY_ENROLLMENT_TOKEN_FILE';
+export const DEFAULT_ENROLL_PATH = '/runners/enroll';
+export const DEFAULT_HOSTED_STREAM_PATH = '/runners/hosted/stream';
+export const DEFAULT_HOSTED_RENEW_PATH = '/runners/hosted/credential';
+/** Renew once this share of the credential's lifetime has passed. */
+const RENEW_AT_FRACTION = 0.75;
+/** Delay between renewal attempts that failed for a reason worth retrying. */
+const RENEW_RETRY_MS = 30_000;
+/** Enrollment could not happen; the process should exit non-zero. */
+export class EnrollmentError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'EnrollmentError';
+    }
+}
+/**
+ * The token and where to send it, from the environment the Deployment
+ * sets. Removes the token variables from `env` once read, so nothing the
+ * runner spawns later inherits them.
+ */
+export function readEnrollSettings(env = process.env, opts = {}) {
+    const readFile = opts.readFile ?? ((p) => readFileSync(p, 'utf-8'));
+    let token = (env[ENROLLMENT_TOKEN_ENV] ?? '').trim();
+    const file = (env[ENROLLMENT_TOKEN_FILE_ENV] ?? '').trim();
+    if (!token && file) {
+        try {
+            token = readFile(file).trim();
+        }
+        catch (err) {
+            throw new EnrollmentError(`cannot read ${ENROLLMENT_TOKEN_FILE_ENV} (${file}): ${err?.code ?? err?.message ?? err}`);
+        }
+    }
+    delete env[ENROLLMENT_TOKEN_ENV];
+    delete env[ENROLLMENT_TOKEN_FILE_ENV];
+    if (!token) {
+        throw new EnrollmentError(`no enrollment token: set ${ENROLLMENT_TOKEN_ENV} or ${ENROLLMENT_TOKEN_FILE_ENV}`);
+    }
+    const backendUrl = (opts.url ?? env.ALMYTY_API_URL ?? env.ALMYTY_URL ?? '').trim().replace(/\/+$/, '');
+    if (!backendUrl)
+        throw new EnrollmentError('no API URL: set ALMYTY_API_URL (or pass --url)');
+    try {
+        assertSecureBackendUrl(backendUrl);
+    }
+    catch (err) {
+        throw new EnrollmentError(err.message);
+    }
+    return { backendUrl, enrollPath: pathOr(env.ALMYTY_ENROLL_PATH, DEFAULT_ENROLL_PATH), token };
+}
+function pathOr(value, fallback) {
+    const v = (value ?? '').trim();
+    return v.startsWith('/') ? v : fallback;
+}
+/**
+ * Trade the token for a runner credential, once. Throws EnrollmentError
+ * on any refusal or malformed answer; the message never carries the token
+ * or a credential.
+ */
+export async function enroll(settings, body, fetchImpl = globalThis.fetch) {
+    let res;
+    try {
+        res = await fetchImpl(`${settings.backendUrl}${settings.enrollPath}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token: settings.token, runtimeInfo: body.runtimeInfo, ...(body.config ? { config: body.config } : {}) }),
+        });
+    }
+    catch (err) {
+        throw new EnrollmentError(`enrollment request failed: ${networkReason(err)}`);
+    }
+    if (!res.ok) {
+        throw new EnrollmentError(`enrollment refused: ${res.status} ${serverMessage(await safeText(res), settings.token)}`, res.status);
+    }
+    const json = (await res.json().catch(() => null));
+    const d = json?.data;
+    const expiresAt = new Date(d?.expiresAt);
+    if (!d || typeof d.runnerId !== 'string' || typeof d.credential !== 'string' || !d.credential ||
+        Number.isNaN(expiresAt.getTime()) || !d.effectiveConfig || typeof d.effectiveConfig !== 'object') {
+        throw new EnrollmentError('enrollment answered without a runner id, credential, expiry and config');
+    }
+    return {
+        runnerId: d.runnerId,
+        credential: d.credential,
+        expiresAt,
+        effectiveConfig: d.effectiveConfig,
+        streamPath: pathOr(d.streamPath, DEFAULT_HOSTED_STREAM_PATH),
+        renewPath: pathOr(d.renewPath, DEFAULT_HOSTED_RENEW_PATH),
+    };
+}
+/**
+ * Holds the runner credential and renews it before it expires. `current()`
+ * is what every request reads, so a renewed credential is used from the
+ * next request on without reconnecting.
+ */
+export class RunnerCredential {
+    opts;
+    credential;
+    expiresAt;
+    timer = null;
+    stopped = false;
+    fetchImpl;
+    setTimeoutFn;
+    clearTimeoutFn;
+    now;
+    constructor(opts) {
+        this.opts = opts;
+        this.credential = opts.credential;
+        this.expiresAt = opts.expiresAt;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        this.setTimeoutFn = opts.setTimeoutFn ?? setTimeout;
+        this.clearTimeoutFn = opts.clearTimeoutFn ?? clearTimeout;
+        this.now = opts.now ?? Date.now;
+    }
+    current() {
+        return this.credential;
+    }
+    expiry() {
+        return this.expiresAt;
+    }
+    /** Arm the renewal timer for the current credential. */
+    start() {
+        this.schedule(this.renewDelay());
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            this.clearTimeoutFn(this.timer);
+        this.timer = null;
+    }
+    /** When the current credential should be renewed, from now. */
+    renewDelay() {
+        const left = this.expiresAt.getTime() - this.now();
+        return Math.max(0, Math.floor(left * RENEW_AT_FRACTION));
+    }
+    /**
+     * One renewal attempt. Resolves true when a new credential is in place;
+     * otherwise schedules a retry, or reports fatal when the server refused
+     * or the credential will expire before another try.
+     */
+    async renew() {
+        if (this.stopped)
+            return false;
+        let status = 0;
+        let detail = '';
+        try {
+            const res = await this.fetchImpl(`${this.opts.backendUrl}${this.opts.renewPath}`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${this.credential}` },
+            });
+            status = res.status;
+            if (res.ok) {
+                const json = (await res.json().catch(() => null));
+                const next = json?.data?.credential;
+                const expiresAt = new Date(json?.data?.expiresAt);
+                if (typeof next === 'string' && next && !Number.isNaN(expiresAt.getTime())) {
+                    this.credential = next;
+                    this.expiresAt = expiresAt;
+                    this.opts.log?.(`runner credential renewed; next renewal in ${Math.round(this.renewDelay() / 1000)}s`);
+                    this.schedule(this.renewDelay());
+                    return true;
+                }
+                detail = 'answer carried no credential';
+            }
+            else {
+                detail = serverMessage(await safeText(res), this.credential);
+            }
+        }
+        catch (err) {
+            detail = networkReason(err);
+        }
+        if (this.stopped)
+            return false;
+        // 401: the credential is no longer accepted. 404: the hosted runner is
+        // gone or being torn down. Neither gets better by asking again.
+        if (status === 401 || status === 403 || status === 404) {
+            this.opts.onFatal(`credential renewal refused: ${status} ${detail}`.trim());
+            return false;
+        }
+        const left = this.expiresAt.getTime() - this.now();
+        if (left <= RENEW_RETRY_MS) {
+            this.opts.onFatal(`credential renewal failed and the credential expires before another try: ${status || ''} ${detail}`.trim());
+            return false;
+        }
+        this.opts.log?.(`credential renewal failed (${status || 'no answer'} ${detail}); retrying in ${RENEW_RETRY_MS / 1000}s`);
+        this.schedule(RENEW_RETRY_MS);
+        return false;
+    }
+    schedule(delay) {
+        if (this.stopped)
+            return;
+        if (this.timer)
+            this.clearTimeoutFn(this.timer);
+        this.timer = this.setTimeoutFn(() => {
+            this.timer = null;
+            void this.renew();
+        }, delay);
+        // Not the keep-alive: the heartbeat timer holds the process up.
+        this.timer?.unref?.();
+    }
+}
+/** The server's words, short, with anything secret-shaped removed. */
+function serverMessage(text, ...secrets) {
+    let out = text;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed?.message === 'string')
+            out = parsed.message;
+        else if (Array.isArray(parsed?.message))
+            out = parsed.message.join('; ');
+    }
+    catch { /* plain text */ }
+    for (const s of secrets)
+        if (s)
+            out = out.split(s).join('[redacted]');
+    return out.replace(/\s+/g, ' ').slice(0, 200);
+}
+/** fetch's own "fetch failed" says nothing; the cause names the socket error. */
+function networkReason(err) {
+    const code = err?.cause?.code ?? err?.cause?.errors?.[0]?.code;
+    return [err?.message ?? String(err), code].filter(Boolean).join(': ');
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=enroll.js.map

package/dist/enroll.js.map

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

package/dist/hosted-setup.d.ts

@@ -0,0 +1,43 @@
+/** Where the volume is mounted when the Deployment does not say. */
+export declare const DEFAULT_WORKSPACE_ROOT = "/workspace";
+/** The checkout's folder inside the workspace. */
+export declare const REPO_DIR_NAME = "repo";
+export interface CommandResult {
+    code: number | null;
+    timedOut?: boolean;
+}
+/** Runs one command with its output going to the runner's log. */
+export type RunCommand = (command: string, args: string[], opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}) => Promise<CommandResult>;
+export interface PrepareInputs {
+    env?: Record<string, string | undefined>;
+    run?: RunCommand;
+    log?: (line: string) => void;
+    warn?: (line: string) => void;
+    /** Where the script file is written before it runs. */
+    tmpDir?: string;
+}
+export interface PrepareOutcome {
+    /** Nothing to do: this volume already carries this environment version. */
+    upToDate: boolean;
+    cloned: boolean;
+    setupRan: boolean;
+    /** Clone and setup both succeeded (or were not needed) and the version was recorded. */
+    ok: boolean;
+    repoDir: string | null;
+}
+export declare function workspaceRoot(env: Record<string, string | undefined>): string;
+export declare function prepareHostedWorkspace(inputs?: PrepareInputs): Promise<PrepareOutcome>;
+/**
+ * The token as an HTTP Authorization header for the repository's origin,
+ * passed through git's GIT_CONFIG_COUNT/KEY/VALUE variables (git 2.31+).
+ * Empty for no token or a URL that is not https.
+ */
+export declare function gitAuthEnv(url: string, token: string | undefined, base?: Record<string, string | undefined>): Record<string, string>;
+/** A URL with any user:password part removed, for log lines. */
+export declare function redactUrl(url: string): string;
+/** The real runner: inherits stdout/stderr, so setup output lands in the pod log. */
+export declare const runCommand: RunCommand;

package/dist/hosted-setup.js

@@ -0,0 +1,196 @@
+/**
+ * First start of a hosted workspace: clone the environment's repository
+ * and run its setup script, once per environment version.
+ *
+ * Runs in enroll mode after the runner has its credential and before it
+ * opens its stream, so the machine reports ready only once the checkout
+ * and setup are in place (docs/hosted-runners.md, "Images and enroll
+ * mode"). The design's rule: on the first start of a volume, or when the
+ * environment version changed, clone `repo` at `ref`, run `setupScript`,
+ * and write `<workspace>/.almyty/env-version`.
+ *
+ * The inputs are the plain variables the Deployment sets
+ * (ALMYTY_WORKSPACE_ROOT, ALMYTY_ENVIRONMENT_VERSION, ALMYTY_REPO_URL,
+ * ALMYTY_REPO_REF, ALMYTY_SETUP_SCRIPT) and one from the Secret,
+ * ALMYTY_GIT_TOKEN. The git token reaches git through GIT_CONFIG_*
+ * variables of that one child process: never on its command line, never
+ * in a file, never in the clone's remote URL.
+ *
+ * A failed clone or setup is reported and the version is not recorded, so
+ * the next start tries again; the runner still comes online, so the
+ * person can look at what went wrong from a shell instead of watching a
+ * pod restart in a loop.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where the volume is mounted when the Deployment does not say. */
+export const DEFAULT_WORKSPACE_ROOT = '/workspace';
+/** The checkout's folder inside the workspace. */
+export const REPO_DIR_NAME = 'repo';
+/** A setup script running longer than this is stopped. Override: ALMYTY_SETUP_TIMEOUT_SECONDS. */
+const DEFAULT_SETUP_TIMEOUT_SECONDS = 1800;
+export function workspaceRoot(env) {
+    const root = (env.ALMYTY_WORKSPACE_ROOT ?? '').trim();
+    return root.startsWith('/') ? root : DEFAULT_WORKSPACE_ROOT;
+}
+export async function prepareHostedWorkspace(inputs = {}) {
+    const env = inputs.env ?? process.env;
+    const run = inputs.run ?? runCommand;
+    const log = inputs.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const warn = inputs.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const root = workspaceRoot(env);
+    const stateDir = join(root, '.almyty');
+    const versionFile = join(stateDir, 'env-version');
+    const version = (env.ALMYTY_ENVIRONMENT_VERSION ?? '').trim() || 'unversioned';
+    const repoUrl = (env.ALMYTY_REPO_URL ?? '').trim();
+    const repoDir = join(root, REPO_DIR_NAME);
+    const recorded = existsSync(versionFile) ? readFileSync(versionFile, 'utf-8').trim() : null;
+    if (recorded === version) {
+        log(`workspace: environment version ${version} already set up`);
+        return { upToDate: true, cloned: false, setupRan: false, ok: true, repoDir: repoUrl ? repoDir : null };
+    }
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    // A spawned step gets the runner's own variables (the environment's
+    // bindings among them); the enrollment token is already gone (enroll.ts).
+    const childEnv = { ...env, GIT_TERMINAL_PROMPT: '0' };
+    let ok = true;
+    let cloned = false;
+    if (repoUrl) {
+        if (existsSync(join(repoDir, '.git'))) {
+            // An existing checkout is the person's work; a new version does not
+            // overwrite it. Only the setup script runs again.
+            log(`workspace: ${repoDir} already holds a checkout; leaving it as it is`);
+        }
+        else {
+            const result = await cloneRepo({ url: repoUrl, ref: (env.ALMYTY_REPO_REF ?? '').trim(), dir: repoDir, token: env.ALMYTY_GIT_TOKEN, env: childEnv, cwd: root, run, log });
+            cloned = result;
+            if (!result) {
+                ok = false;
+                warn(`workspace: cloning ${redactUrl(repoUrl)} failed; it is tried again on the next start`);
+            }
+        }
+    }
+    const script = env.ALMYTY_SETUP_SCRIPT ?? '';
+    let setupRan = false;
+    if (script.trim() && ok) {
+        setupRan = true;
+        const tmp = inputs.tmpDir ?? '/tmp';
+        const file = join(tmp, `almyty-setup-${process.pid}-${Date.now()}.sh`);
+        writeFileSync(file, script, { mode: 0o700 });
+        const cwd = repoUrl && existsSync(repoDir) ? repoDir : root;
+        const timeoutS = positiveInt(env.ALMYTY_SETUP_TIMEOUT_SECONDS) ?? DEFAULT_SETUP_TIMEOUT_SECONDS;
+        log(`workspace: running the setup script in ${cwd}`);
+        try {
+            const res = await run('bash', [file], { cwd, env: childEnv, timeoutMs: timeoutS * 1000 });
+            if (res.code !== 0) {
+                ok = false;
+                warn(res.timedOut
+                    ? `workspace: the setup script ran past ${timeoutS}s and was stopped; it runs again on the next start`
+                    : `workspace: the setup script exited ${res.code}; it runs again on the next start`);
+            }
+        }
+        finally {
+            rmSync(file, { force: true });
+        }
+    }
+    if (ok) {
+        writeFileSync(versionFile, `${version}\n`, { mode: 0o600 });
+        log(`workspace: environment version ${version} set up`);
+    }
+    return { upToDate: false, cloned, setupRan, ok, repoDir: repoUrl ? repoDir : null };
+}
+async function cloneRepo(o) {
+    const env = { ...o.env, ...gitAuthEnv(o.url, o.token, o.env) };
+    o.log(`workspace: cloning ${redactUrl(o.url)}${o.ref ? ` at ${o.ref}` : ''} into ${o.dir}`);
+    const clone = await o.run('git', ['clone', '--', o.url, o.dir], { cwd: o.cwd, env });
+    if (clone.code !== 0) {
+        rmSync(o.dir, { recursive: true, force: true });
+        return false;
+    }
+    if (!o.ref)
+        return true;
+    // A branch or tag checks out directly; a commit or another ref may need
+    // fetching first.
+    const checkout = await o.run('git', ['-C', o.dir, 'checkout', o.ref, '--'], { cwd: o.cwd, env });
+    if (checkout.code === 0)
+        return true;
+    const fetch = await o.run('git', ['-C', o.dir, 'fetch', 'origin', o.ref], { cwd: o.cwd, env });
+    if (fetch.code !== 0)
+        return false;
+    const detached = await o.run('git', ['-C', o.dir, 'checkout', 'FETCH_HEAD', '--'], { cwd: o.cwd, env });
+    return detached.code === 0;
+}
+/**
+ * The token as an HTTP Authorization header for the repository's origin,
+ * passed through git's GIT_CONFIG_COUNT/KEY/VALUE variables (git 2.31+).
+ * Empty for no token or a URL that is not https.
+ */
+export function gitAuthEnv(url, token, base = {}) {
+    if (!token)
+        return {};
+    let origin;
+    try {
+        const u = new URL(url);
+        if (u.protocol !== 'https:')
+            return {};
+        origin = `${u.protocol}//${u.host}/`;
+    }
+    catch {
+        return {};
+    }
+    const n = positiveInt(base.GIT_CONFIG_COUNT) ?? 0;
+    const basic = Buffer.from(`x-access-token:${token}`).toString('base64');
+    return {
+        GIT_CONFIG_COUNT: String(n + 1),
+        [`GIT_CONFIG_KEY_${n}`]: `http.${origin}.extraHeader`,
+        [`GIT_CONFIG_VALUE_${n}`]: `Authorization: Basic ${basic}`,
+    };
+}
+/** A URL with any user:password part removed, for log lines. */
+export function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        if (u.username || u.password) {
+            u.username = '';
+            u.password = '';
+        }
+        return u.toString();
+    }
+    catch {
+        return url.replace(/\/\/[^@/]*@/, '//');
+    }
+}
+function positiveInt(value) {
+    const n = Number((value ?? '').trim());
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/** The real runner: inherits stdout/stderr, so setup output lands in the pod log. */
+export const runCommand = (command, args, opts) => new Promise((resolve) => {
+    // Its own process group, so a timeout stops everything it started,
+    // not only the shell.
+    const child = spawn(command, args, { cwd: opts.cwd, env: opts.env, stdio: ['ignore', 'inherit', 'inherit'], detached: true });
+    let timedOut = false;
+    const timer = opts.timeoutMs
+        ? setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        }, opts.timeoutMs)
+        : null;
+    child.on('error', () => {
+        if (timer)
+            clearTimeout(timer);
+        resolve({ code: -1, timedOut });
+    });
+    child.on('close', (code) => {
+        if (timer)
+            clearTimeout(timer);
+        resolve({ code, timedOut });
+    });
+});
+//# sourceMappingURL=hosted-setup.js.map

package/dist/hosted-setup.js.map

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

package/dist/policy.d.ts

@@ -1,6 +1,32 @@
 import { RunnerConfig } from './types.js';
 /** Drop env keys a payload must not be allowed to set. */
 export declare function sanitizeEnv(env?: Record<string, string>): Record<string, string> | undefined;
+/**
+ * Parse an allowBinaries list from its environment form: a JSON array of
+ * strings (what the backend writes). Anything else throws, so a runner
+ * with a list it cannot read refuses to start rather than running
+ * unrestricted.
+ */
+export declare function parseAllowBinaries(raw: string | undefined): string[] | undefined;
+/**
+ * The config with an allowBinaries list applied. Only ever narrows: when
+ * the config already has a list, the result is the intersection, and an
+ * empty intersection throws rather than lifting the restriction.
+ */
+export declare function withAllowBinaries(config: RunnerConfig, allow: string[] | undefined): RunnerConfig;
+/**
+ * The command names a shell command line would start: the first word of
+ * every simple command, including those inside $( ), backticks, ( ), <( )
+ * and >( ), after variable assignments, redirections and keywords. Quotes
+ * and backslashes are removed from the word (`"rm"` is rm). A word that is
+ * built at run time ($VAR, a glob) is returned as is and never matches an
+ * entry, so it is refused.
+ *
+ * Best effort by design: separators inside quotes split too, which can
+ * refuse a harmless line (`echo "a; b"` checks `b`) but never lets a
+ * command through unseen.
+ */
+export declare function commandHeads(cmd: string): string[];
 /** Enforce policy for a process.spawn; returns the sanitized env to use. */
 export declare function enforceSpawnPolicy(config: RunnerConfig, opts: {
     binary: string;