@runinfra/cli 0.1.0

package/dist/artifact-name.js

@@ -0,0 +1,62 @@
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const WINDOWS_RESERVED = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    "com1",
+    "com2",
+    "com3",
+    "com4",
+    "com5",
+    "com6",
+    "com7",
+    "com8",
+    "com9",
+    "lpt1",
+    "lpt2",
+    "lpt3",
+    "lpt4",
+    "lpt5",
+    "lpt6",
+    "lpt7",
+    "lpt8",
+    "lpt9",
+]);
+const MAX_NAME_LENGTH = 120;
+export function fallbackArtifactName(slug, packageVersion) {
+    const safeSlug = slug
+        .replace(/[^A-Za-z0-9-]+/gu, "-")
+        .replace(/-{2,}/gu, "-")
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, MAX_NAME_LENGTH);
+    return `${safeSlug || "package"}-v${packageVersion}.kit`;
+}
+export function artifactFileName(input) {
+    let candidate = null;
+    try {
+        const pathname = new URL(input.url).pathname;
+        const segment = pathname.split("/").filter(Boolean).pop();
+        if (segment !== undefined) {
+            candidate = decodeURIComponent(segment);
+        }
+    }
+    catch {
+        candidate = null;
+    }
+    if (candidate === null)
+        return fallbackArtifactName(input.slug, input.packageVersion);
+    const cleaned = candidate.trim().slice(0, MAX_NAME_LENGTH);
+    if (!SAFE_NAME.test(cleaned))
+        return fallbackArtifactName(input.slug, input.packageVersion);
+    const stem = (cleaned.split(".")[0] ?? "").toLowerCase();
+    if (WINDOWS_RESERVED.has(stem))
+        return fallbackArtifactName(input.slug, input.packageVersion);
+    return cleaned;
+}
+export function partFileName(finalName) {
+    return `${finalName}.part`;
+}
+export function sidecarFileName(finalName) {
+    return `${finalName}.part.json`;
+}

package/dist/auth-api.js

@@ -0,0 +1,177 @@
+import { CliError } from "./errors.js";
+import { requestJson } from "./http.js";
+const TOKEN_REFUSALS = new Set([
+    "invalid_request",
+    "invalid_grant",
+    "expired_token",
+    "access_denied",
+    "authorization_pending",
+    "slow_down",
+    "rate_limited",
+    "temporarily_unavailable",
+    "server_error",
+    "unsupported_code_challenge_method",
+    "invalid_scope",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+export function parseSession(body) {
+    if (!isRecord(body))
+        return null;
+    const apiKey = readString(body.apiKey);
+    const workspaceId = readString(body.workspaceId);
+    const expiresAt = readString(body.expiresAt);
+    if (!apiKey || !workspaceId || !expiresAt)
+        return null;
+    if (!Number.isFinite(Date.parse(expiresAt)))
+        return null;
+    return {
+        apiKey,
+        keyPrefix: readString(body.keyPrefix) ?? apiKey.slice(0, 8),
+        scope: readString(body.scope) ?? "",
+        workspaceId,
+        expiresAt,
+    };
+}
+export function parseTokenRefusal(body, headers = {}) {
+    const raw = isRecord(body) && typeof body.error === "string" ? body.error : null;
+    if (raw === null || !TOKEN_REFUSALS.has(raw))
+        return null;
+    const advertised = Number.parseInt(headers["retry-after"] ?? "", 10);
+    return {
+        code: raw,
+        retryAfterSeconds: Number.isFinite(advertised) && advertised > 0 ? advertised : null,
+    };
+}
+export function tokenRefusalError(code) {
+    switch (code) {
+        case "access_denied":
+            return new CliError("auth_denied", "The sign-in was rejected in the browser. Nothing was granted.", "Run `runinfra login` again if that was not you.");
+        case "expired_token":
+            return new CliError("auth_expired", "The sign-in request expired before it was approved.", "Run `runinfra login` again.");
+        case "invalid_grant":
+            return new CliError("auth_failed", "That sign-in could not be completed. The code was already used, was never approved, or does not belong to this terminal.", "Run `runinfra login` again to start a fresh request.");
+        case "invalid_request":
+            return new CliError("auth_failed", "The server refused the sign-in request as malformed.", "Update the CLI (`npm i -g @runinfra/cli`) and try again.");
+        case "unsupported_code_challenge_method":
+            return new CliError("auth_failed", "The server does not accept this CLI's PKCE method.", "Update the CLI (`npm i -g @runinfra/cli`) and try again.");
+        case "invalid_scope":
+            return new CliError("auth_failed", "The server does not recognise the access this CLI asked for.", "Update the CLI (`npm i -g @runinfra/cli`) and try again.");
+        case "temporarily_unavailable":
+            return new CliError("server_error", "Sign-in is temporarily unavailable. Nothing was granted, and nothing was consumed.", "Try again in a few minutes.");
+        case "rate_limited":
+            return new CliError("rate_limited", "Too many sign-in attempts from this machine.", "Wait a minute and run `runinfra login` again.");
+        case "authorization_pending":
+        case "slow_down":
+            return new CliError("auth_timeout", "The sign-in was not approved in time.", "Run `runinfra login` again.");
+        case "server_error":
+            return new CliError("server_error", "The sign-in failed on the server.", "Try again shortly. If it keeps failing, contact support.");
+    }
+}
+function unexpected(status, what) {
+    return new CliError("server_error", `${what} failed with HTTP ${status}.`, "Try again shortly. If it keeps failing, contact support with this status.");
+}
+function malformed(what) {
+    return new CliError("server_error", `${what} did not return a response this CLI understands. The endpoint answered, but not with RunInfra data.`, "Check RUNINFRA_API_BASE, and whether a proxy is intercepting the request.");
+}
+function outcomeFor(status, body, headers, what) {
+    if (status === 200) {
+        const session = parseSession(body);
+        if (session === null)
+            throw malformed(what);
+        return { ok: true, session };
+    }
+    const refusal = parseTokenRefusal(body, headers);
+    if (refusal === null)
+        throw unexpected(status, what);
+    return { ok: false, ...refusal };
+}
+export async function startLoopbackAuthorization(input) {
+    const response = await requestJson({
+        method: "POST",
+        url: input.endpoints.loopbackInit,
+        json: {
+            codeChallenge: input.codeChallenge,
+            codeChallengeMethod: "S256",
+            scope: input.scope,
+            redirectUri: input.redirectUri,
+            deviceLabel: input.deviceLabel,
+        },
+    });
+    if (response.status === 404 || response.status === 501 || response.status === 405) {
+        return { ok: false, reason: "not_available" };
+    }
+    if (response.status !== 200 && response.status !== 201) {
+        const refusal = parseTokenRefusal(response.body, response.headers);
+        if (refusal !== null)
+            throw tokenRefusalError(refusal.code);
+        throw unexpected(response.status, "Starting the browser sign-in");
+    }
+    const body = response.body;
+    const requestId = isRecord(body) ? readString(body.requestId) : null;
+    if (requestId === null)
+        throw malformed("Starting the browser sign-in");
+    return { ok: true, requestId };
+}
+export async function exchangeAuthorizationCode(input) {
+    const response = await requestJson({
+        method: "POST",
+        url: input.endpoints.token,
+        json: {
+            code: input.code,
+            codeVerifier: input.codeVerifier,
+            redirectUri: input.redirectUri,
+        },
+    });
+    return outcomeFor(response.status, response.body, response.headers, "The sign-in exchange");
+}
+export async function startDeviceAuthorization(input) {
+    const response = await requestJson({
+        method: "POST",
+        url: input.endpoints.deviceInit,
+        json: {
+            codeChallenge: input.codeChallenge,
+            codeChallengeMethod: "S256",
+            scope: input.scope,
+            ...(input.deviceLabel === null ? {} : { deviceLabel: input.deviceLabel }),
+        },
+    });
+    if (response.status !== 200 && response.status !== 201) {
+        const refusal = parseTokenRefusal(response.body, response.headers);
+        if (refusal !== null)
+            throw tokenRefusalError(refusal.code);
+        throw unexpected(response.status, "Starting the device sign-in");
+    }
+    const authorization = parseDeviceAuthorization(response.body);
+    if (authorization === null)
+        throw malformed("Starting the device sign-in");
+    return authorization;
+}
+export function parseDeviceAuthorization(body) {
+    if (!isRecord(body))
+        return null;
+    const deviceCode = readString(body.deviceCode);
+    const userCode = readString(body.userCode);
+    const verificationUri = readString(body.verificationUri);
+    if (!deviceCode || !userCode || !verificationUri)
+        return null;
+    const expiresInSeconds = typeof body.expiresIn === "number" && body.expiresIn > 0
+        ? Math.floor(body.expiresIn)
+        : 900;
+    const intervalSeconds = typeof body.interval === "number" && body.interval > 0
+        ? Math.ceil(body.interval)
+        : 5;
+    return { deviceCode, userCode, verificationUri, expiresInSeconds, intervalSeconds };
+}
+export async function pollDeviceCode(input) {
+    const response = await requestJson({
+        method: "POST",
+        url: input.endpoints.devicePoll,
+        json: { deviceCode: input.deviceCode },
+    });
+    return outcomeFor(response.status, response.body, response.headers, "The device sign-in");
+}

package/dist/browser.js

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+export function browserCommandFor(platform, url) {
+    if (platform === "win32") {
+        return {
+            command: "cmd.exe",
+            args: ["/d", "/s", "/c", `start "" "${url}"`],
+            verbatim: true,
+        };
+    }
+    if (platform === "darwin") {
+        return { command: "open", args: [url], verbatim: false };
+    }
+    if (platform === "linux" || platform === "freebsd" || platform === "openbsd") {
+        return { command: "xdg-open", args: [url], verbatim: false };
+    }
+    return null;
+}
+export function headlessReason(platform, env) {
+    if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) {
+        return "this is an SSH session";
+    }
+    if (env.CI) {
+        return "this is a CI environment";
+    }
+    if (browserCommandFor(platform, "https://example.com") === null) {
+        return `there is no known way to open a browser on ${platform}`;
+    }
+    if (platform !== "win32" && platform !== "darwin") {
+        if (!env.DISPLAY && !env.WAYLAND_DISPLAY) {
+            return "there is no graphical display on this machine";
+        }
+    }
+    return null;
+}
+export async function openBrowser(url, platform = process.platform, env = process.env) {
+    const blocked = headlessReason(platform, env);
+    if (blocked !== null)
+        return { opened: false, reason: blocked };
+    const command = browserCommandFor(platform, url);
+    if (command === null) {
+        return { opened: false, reason: `there is no known way to open a browser on ${platform}` };
+    }
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        try {
+            const child = spawn(command.command, [...command.args], {
+                stdio: "ignore",
+                detached: platform !== "win32",
+                windowsVerbatimArguments: command.verbatim,
+            });
+            child.on("error", (error) => {
+                finish({ opened: false, reason: error.message });
+            });
+            child.unref();
+            setTimeout(() => finish({ opened: true, reason: null }), 250);
+        }
+        catch (error) {
+            finish({
+                opened: false,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+}

package/dist/catalog-api.js

@@ -0,0 +1,89 @@
+import { headResource, streamRange } from "./http.js";
+import { CliError } from "./errors.js";
+import { downloadFailure, parseLeaseResponse } from "./lease.js";
+import { requestJson } from "./http.js";
+export async function requestLease(endpoints, apiKey, slug, signal) {
+    const response = await requestJson({
+        method: "GET",
+        url: endpoints.download(slug),
+        headers: { authorization: `Bearer ${apiKey}` },
+        ...(signal ? { signal } : {}),
+    });
+    if (response.status !== 200) {
+        throw downloadFailure(response.status, response.body, slug);
+    }
+    const lease = parseLeaseResponse(response.body);
+    if (lease === null) {
+        throw new CliError("server_error", `The download response for ${slug} was not in the expected format.`, "Try again shortly. If it keeps failing, contact support.");
+    }
+    return lease;
+}
+export function parseContentRangeTotal(value) {
+    if (!value)
+        return null;
+    const match = /^bytes\s+\d+-\d+\/(\d+)$/iu.exec(value.trim());
+    if (!match)
+        return null;
+    const total = Number.parseInt(match[1] ?? "", 10);
+    return Number.isSafeInteger(total) && total > 0 ? total : null;
+}
+export function parseContentLength(value) {
+    if (!value)
+        return null;
+    const length = Number.parseInt(value.trim(), 10);
+    return Number.isSafeInteger(length) && length >= 0 ? length : null;
+}
+export function supportsRanges(headers) {
+    const value = headers["accept-ranges"];
+    return typeof value === "string" && value.toLowerCase().includes("bytes");
+}
+export function readEtag(headers) {
+    const value = headers.etag;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+export async function probeArtifact(url, signal) {
+    const head = await headResource(url, signal ? { signal } : {});
+    if (head.status === 200) {
+        const sizeBytes = parseContentLength(head.headers["content-length"]);
+        if (sizeBytes !== null && sizeBytes > 0) {
+            return {
+                ok: true,
+                probe: {
+                    sizeBytes,
+                    etag: readEtag(head.headers),
+                    rangesSupported: supportsRanges(head.headers),
+                },
+            };
+        }
+    }
+    const probe = await streamRange({
+        url,
+        start: 0,
+        endInclusive: 0,
+        onChunk: () => undefined,
+        ...(signal ? { signal } : {}),
+    });
+    if (probe.status === 206) {
+        const total = parseContentRangeTotal(probe.headers["content-range"]);
+        if (total === null)
+            return { ok: false, reason: "unusable", status: probe.status };
+        return {
+            ok: true,
+            probe: { sizeBytes: total, etag: readEtag(probe.headers), rangesSupported: true },
+        };
+    }
+    if (probe.status === 200) {
+        const sizeBytes = parseContentLength(probe.headers["content-length"]);
+        if (sizeBytes === null || sizeBytes <= 0) {
+            return { ok: false, reason: "unusable", status: probe.status };
+        }
+        return {
+            ok: true,
+            probe: { sizeBytes, etag: readEtag(probe.headers), rangesSupported: false },
+        };
+    }
+    if (probe.status === 401 || probe.status === 403) {
+        return { ok: false, reason: "lease_expired" };
+    }
+    return { ok: false, reason: "unusable", status: probe.status };
+}

package/dist/checksum.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+export function isSha256Hex(value) {
+    return /^[a-f0-9]{64}$/iu.test(value);
+}
+export function judgeChecksum(expected, actual) {
+    if (expected === null || !isSha256Hex(expected))
+        return "unverifiable";
+    if (!isSha256Hex(actual))
+        return "unverifiable";
+    return expected.toLowerCase() === actual.toLowerCase() ? "match" : "mismatch";
+}
+export async function sha256File(path, onProgress, signal) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path, signal ? { signal } : {});
+    let hashed = 0;
+    await new Promise((resolve, reject) => {
+        stream.on("data", (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            hash.update(buffer);
+            hashed += buffer.length;
+            onProgress?.(hashed);
+        });
+        stream.on("end", resolve);
+        stream.on("error", reject);
+    });
+    return hash.digest("hex");
+}

package/dist/context.js

@@ -0,0 +1,52 @@
+import { homedir, hostname, userInfo } from "node:os";
+import { CliError } from "./errors.js";
+import { endpointsFor, resolveApiBase } from "./endpoints.js";
+import { credentialsExpired, readCredentials, } from "./credentials.js";
+import { credentialLocation } from "./paths.js";
+export function createContext(input) {
+    const env = input.env ?? process.env;
+    const platform = input.platform ?? process.platform;
+    const base = resolveApiBase(env);
+    if (!base.ok)
+        throw new CliError("usage", base.message, null);
+    return {
+        apiBase: base.base,
+        endpoints: endpointsFor(base.base),
+        location: credentialLocation({ platform, env, homeDir: input.homeDir ?? homedir() }),
+        output: input.output,
+        env,
+        platform,
+    };
+}
+export async function requireCredentials(context) {
+    const credentials = await readCredentials(context.location);
+    if (credentials === null) {
+        throw new CliError("not_authenticated", "This machine is not signed in.", "Run `runinfra login` first.");
+    }
+    if (credentialsExpired(credentials)) {
+        throw new CliError("auth_expired", `This terminal's access expired on ${credentials.expiresAt}.`, "Run `runinfra login` to connect it again.");
+    }
+    if (credentials.apiBase !== context.apiBase) {
+        context.output.warn(`Signed in against ${credentials.apiBase}, which is not the configured ${context.apiBase}. Using the one the key belongs to.`);
+    }
+    return { credentials, endpoints: endpointsFor(credentials.apiBase) };
+}
+export function deviceLabel() {
+    let user = null;
+    try {
+        user = userInfo().username || null;
+    }
+    catch {
+        user = null;
+    }
+    let host = null;
+    try {
+        host = hostname() || null;
+    }
+    catch {
+        host = null;
+    }
+    if (user && host)
+        return `${user}@${host}`;
+    return user ?? host;
+}

package/dist/credentials.js

@@ -0,0 +1,136 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { CliError } from "./errors.js";
+export const CREDENTIALS_FORMAT = 1;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function serializeCredentials(credentials) {
+    return `${JSON.stringify(credentials, null, 2)}\n`;
+}
+export function parseCredentials(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value))
+        return null;
+    if (value.format !== CREDENTIALS_FORMAT)
+        return null;
+    const { apiBase, apiKey, keyPrefix, workspaceId, expiresAt, createdAt } = value;
+    for (const field of [apiBase, apiKey, keyPrefix, workspaceId, expiresAt, createdAt]) {
+        if (typeof field !== "string" || field.length === 0)
+            return null;
+    }
+    if (typeof value.scope !== "string")
+        return null;
+    if (!Number.isFinite(Date.parse(expiresAt)))
+        return null;
+    return {
+        format: CREDENTIALS_FORMAT,
+        apiBase: apiBase,
+        apiKey: apiKey,
+        keyPrefix: keyPrefix,
+        workspaceId: workspaceId,
+        scope: value.scope,
+        expiresAt: expiresAt,
+        createdAt: createdAt,
+    };
+}
+export function credentialsExpired(credentials, nowMs = Date.now()) {
+    const expiresAtMs = Date.parse(credentials.expiresAt);
+    if (!Number.isFinite(expiresAtMs))
+        return false;
+    return expiresAtMs <= nowMs;
+}
+export async function readCredentials(location) {
+    let raw;
+    try {
+        raw = await readFile(location.file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new CliError("storage_unwritable", `Could not read ${location.file}: ${error.message}`, "Check the file's permissions, or delete it and run `runinfra login` again.");
+    }
+    return parseCredentials(raw);
+}
+export function windowsAclArgs(dir, principal) {
+    return [dir, "/inheritance:r", "/grant:r", `${principal}:(OI)(CI)F`];
+}
+export function windowsPrincipal(env) {
+    const user = env.USERNAME?.trim();
+    if (!user)
+        return null;
+    const domain = env.USERDOMAIN?.trim();
+    return domain ? `${domain}\\${user}` : user;
+}
+async function restrictWindowsDirectory(dir, env) {
+    const principal = windowsPrincipal(env);
+    if (principal === null) {
+        return {
+            restricted: false,
+            warning: "USERNAME is not set, so the credentials directory keeps its inherited permissions.",
+        };
+    }
+    const failed = await new Promise((resolve) => {
+        const child = spawn("icacls", windowsAclArgs(dir, principal), { stdio: "ignore" });
+        child.on("error", (error) => resolve(error.message));
+        child.on("close", (code) => resolve(code === 0 ? null : `icacls exited with code ${code ?? "unknown"}`));
+    });
+    if (failed === null)
+        return { restricted: true, warning: null };
+    return {
+        restricted: false,
+        warning: `Could not restrict ${dir} (${failed}). The API key is protected only by your Windows profile permissions.`,
+    };
+}
+export async function writeCredentials(input) {
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    const { dir, file } = input.location;
+    const isWindows = platform === "win32";
+    try {
+        await mkdir(dir, { recursive: true, ...(isWindows ? {} : { mode: 0o700 }) });
+        if (!isWindows) {
+            await chmod(dir, 0o700);
+        }
+    }
+    catch (error) {
+        throw new CliError("storage_unwritable", `Could not create ${dir}: ${error.message}`, "Set RUNINFRA_CONFIG_DIR to a directory you can write to, then try again.");
+    }
+    const restriction = isWindows
+        ? await restrictWindowsDirectory(dir, env)
+        : { restricted: true, warning: null };
+    const temp = `${file}.tmp`;
+    try {
+        await writeFile(temp, serializeCredentials(input.credentials), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        if (!isWindows)
+            await chmod(temp, 0o600);
+        await rename(temp, file);
+        if (!isWindows)
+            await chmod(file, 0o600);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        throw new CliError("storage_unwritable", `Could not write ${file}: ${error.message}`, "Set RUNINFRA_CONFIG_DIR to a directory you can write to, then try again.");
+    }
+    return restriction;
+}
+export async function deleteCredentials(location) {
+    try {
+        await rm(location.file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new CliError("storage_unwritable", `Could not remove ${location.file}: ${error.message}`, "Delete the file by hand to finish signing out.");
+    }
+}

package/dist/disk.js

@@ -0,0 +1,33 @@
+import { statfs } from "node:fs/promises";
+import { CliError } from "./errors.js";
+import { formatBytes } from "./progress.js";
+export const FREE_SPACE_HEADROOM = 1.05;
+export function requiredFreeBytes(remainingBytes) {
+    if (!Number.isFinite(remainingBytes) || remainingBytes <= 0)
+        return 0;
+    return Math.ceil(remainingBytes * FREE_SPACE_HEADROOM);
+}
+export function judgeFreeSpace(freeBytes, remainingBytes) {
+    const required = requiredFreeBytes(remainingBytes);
+    if (freeBytes === null)
+        return { ok: true, freeBytes: null };
+    if (freeBytes >= required)
+        return { ok: true, freeBytes };
+    return { ok: false, freeBytes, requiredBytes: required };
+}
+export async function readFreeBytes(dir) {
+    try {
+        const stats = await statfs(dir);
+        const free = Number(stats.bavail) * Number(stats.bsize);
+        return Number.isFinite(free) && free >= 0 ? free : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertFreeSpace(dir, remainingBytes) {
+    const verdict = judgeFreeSpace(await readFreeBytes(dir), remainingBytes);
+    if (verdict.ok)
+        return;
+    throw new CliError("disk_space", `Not enough free space in ${dir}: ${formatBytes(verdict.freeBytes)} available, ${formatBytes(verdict.requiredBytes)} needed.`, "Free some space or pass --out to a larger volume, then run the same command again to resume.");
+}