@termfleet/core 0.1.0

package/dist/contracts/console-layout.js

@@ -0,0 +1,135 @@
+export function parseConsoleLayout(payload) {
+    if (!payload || typeof payload !== "object") {
+        return { providerGroups: {} };
+    }
+    const source = payload;
+    const viewport = parseViewport(source.viewport);
+    const providerGroupsPayload = source.providerGroups;
+    if (!providerGroupsPayload || typeof providerGroupsPayload !== "object" || Array.isArray(providerGroupsPayload)) {
+        return { providerGroups: {}, viewport };
+    }
+    const providerGroups = {};
+    for (const [providerGroupId, providerGroupPayload] of Object.entries(providerGroupsPayload)) {
+        if (!providerGroupPayload || typeof providerGroupPayload !== "object") {
+            continue;
+        }
+        const providerGroupSource = providerGroupPayload;
+        const appearance = parseProviderGroupAppearance(providerGroupSource.appearance);
+        const positionPayload = providerGroupPayload.position;
+        if (!positionPayload || typeof positionPayload !== "object") {
+            if (appearance) {
+                providerGroups[providerGroupId] = { appearance };
+            }
+            continue;
+        }
+        const positionSource = positionPayload;
+        const x = Number(positionSource.x);
+        const y = Number(positionSource.y);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            if (appearance) {
+                providerGroups[providerGroupId] = { appearance };
+            }
+            continue;
+        }
+        providerGroups[providerGroupId] = { ...(appearance ? { appearance } : {}), position: { x, y } };
+    }
+    return { providerGroups, viewport };
+}
+export function parseConsoleLayoutPatch(payload) {
+    const layout = parseConsoleLayout(payload);
+    if (Object.keys(layout.providerGroups).length === 0 && !layout.viewport) {
+        throw new Error("Console layout patch must include at least one provider group position or viewport.");
+    }
+    return layout;
+}
+function parseViewport(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const source = payload;
+    const x = Number(source.x);
+    const y = Number(source.y);
+    const zoom = Number(source.zoom);
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(zoom) || zoom <= 0) {
+        return undefined;
+    }
+    return { x, y, zoom };
+}
+function parseProviderGroupAppearance(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const source = payload;
+    const appearance = {};
+    // `title` is intentionally NOT parsed here: a machine's name lives on its
+    // registry record, never in appearance. A legacy title in the file is dropped.
+    if (typeof source.backgroundColor === "string" && /^#[0-9a-f]{6}$/i.test(source.backgroundColor.trim())) {
+        appearance.backgroundColor = source.backgroundColor.trim();
+    }
+    if (typeof source.accentColor === "string" && /^#[0-9a-f]{6}$/i.test(source.accentColor.trim())) {
+        appearance.accentColor = source.accentColor.trim();
+    }
+    if (typeof source.wallpaper === "string" && /^[a-z0-9-]{1,32}$/.test(source.wallpaper.trim())) {
+        appearance.wallpaper = source.wallpaper.trim();
+    }
+    const backgroundOpacity = Number(source.backgroundOpacity);
+    if (Number.isFinite(backgroundOpacity)) {
+        appearance.backgroundOpacity = Math.min(1, Math.max(0, backgroundOpacity));
+    }
+    const backgroundBlur = Number(source.backgroundBlur);
+    if (Number.isFinite(backgroundBlur)) {
+        appearance.backgroundBlur = Math.min(40, Math.max(0, backgroundBlur));
+    }
+    if (typeof source.icon === "string" && /^[a-z0-9-]{1,24}$/.test(source.icon.trim())) {
+        appearance.icon = source.icon.trim();
+    }
+    if (source.windowTitlebar === "minimal" || source.windowTitlebar === "plain" || source.windowTitlebar === "traffic") {
+        appearance.windowTitlebar = source.windowTitlebar;
+    }
+    const windowCornerRadius = Number(source.windowCornerRadius);
+    if (Number.isFinite(windowCornerRadius)) {
+        appearance.windowCornerRadius = Math.min(24, Math.max(0, Math.round(windowCornerRadius)));
+    }
+    const windowOpacity = Number(source.windowOpacity);
+    if (Number.isFinite(windowOpacity)) {
+        appearance.windowOpacity = Math.min(1, Math.max(0.4, windowOpacity));
+    }
+    const windowFrost = Number(source.windowFrost);
+    if (Number.isFinite(windowFrost)) {
+        appearance.windowFrost = Math.min(24, Math.max(0, windowFrost));
+    }
+    if (source.mode === "dark" || source.mode === "light") {
+        appearance.mode = source.mode;
+    }
+    if (typeof source.desktopGrid === "boolean") {
+        appearance.desktopGrid = source.desktopGrid;
+    }
+    if (typeof source.terminalFontFamily === "string" && /^[a-z0-9-]{1,24}$/.test(source.terminalFontFamily.trim())) {
+        appearance.terminalFontFamily = source.terminalFontFamily.trim();
+    }
+    if (source.terminalCursorStyle === "bar" || source.terminalCursorStyle === "block" || source.terminalCursorStyle === "underline") {
+        appearance.terminalCursorStyle = source.terminalCursorStyle;
+    }
+    if (typeof source.terminalCursorBlink === "boolean") {
+        appearance.terminalCursorBlink = source.terminalCursorBlink;
+    }
+    if (source.wallpaperFit === "center" || source.wallpaperFit === "fill" || source.wallpaperFit === "fit" || source.wallpaperFit === "tile") {
+        appearance.wallpaperFit = source.wallpaperFit;
+    }
+    if (typeof source.wallpaperUrl === "string") {
+        const wallpaperUrl = source.wallpaperUrl.trim();
+        if (wallpaperUrl.length <= 600 && isHttpUrl(wallpaperUrl)) {
+            appearance.wallpaperUrl = wallpaperUrl;
+        }
+    }
+    return Object.keys(appearance).length > 0 ? appearance : undefined;
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/contracts/files.d.ts

@@ -0,0 +1,38 @@
+export type ProviderFileStat = {
+    bytes: number;
+    mode?: string;
+    path: string;
+    terminalId: string;
+};
+export type ProviderFileKind = "directory" | "file" | "other";
+export type ProviderDirectoryEntry = {
+    bytes: number;
+    kind: ProviderFileKind;
+    modifiedAt?: string;
+    mode?: string;
+    name: string;
+    path: string;
+};
+export type ProviderDirectoryList = {
+    entries: ProviderDirectoryEntry[];
+    filesystemId?: string;
+    path: string;
+    terminalId: string;
+};
+export type ProviderFileWriteOptions = {
+    data: Buffer;
+    filesystemId?: string;
+    mkdirs?: boolean;
+    mode?: string;
+    path: string;
+    terminalId: string;
+};
+export type ProviderFileWriteResult = {
+    bytes: number;
+    filesystemId?: string;
+    path: string;
+    terminalId: string;
+};
+export declare function parseFileMode(value: string | null | undefined): string | undefined;
+export declare function parseProviderFilePath(value: string | null | undefined): string;
+export declare function parseProviderFileTerminalId(value: string | null | undefined): string;

package/dist/contracts/files.js

@@ -0,0 +1,37 @@
+export function parseFileMode(value) {
+    if (value === null || value === undefined || value === "") {
+        return undefined;
+    }
+    if (!/^[0-7]{3,4}$/.test(value)) {
+        throw new Error("File mode must be an octal mode like 600 or 0644.");
+    }
+    return value;
+}
+export function parseProviderFilePath(value) {
+    if (!value) {
+        throw new Error("File path is required.");
+    }
+    if (value.includes("\0")) {
+        throw new Error("File path cannot contain null bytes.");
+    }
+    if (!value.startsWith("/")) {
+        throw new Error("File path must be absolute.");
+    }
+    // Reject "." / ".." segments so a path can never climb out of the directory it
+    // names. The file browser only ever builds canonical absolute paths from
+    // listDirectory results, so this never rejects legitimate use — it only blocks
+    // traversal tricks (e.g. /srv/data/../../etc/shadow).
+    if (value.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error("File path cannot contain '.' or '..' segments.");
+    }
+    return value;
+}
+export function parseProviderFileTerminalId(value) {
+    if (!value) {
+        throw new Error("File terminalId is required.");
+    }
+    if (value.includes("\0")) {
+        throw new Error("File terminalId cannot contain null bytes.");
+    }
+    return value;
+}

package/dist/contracts/provider-url.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeProviderOrigin(raw: string): string;
+export declare function isSsrfReservedProviderHost(raw: string): boolean;
+export declare function isLocalProviderUrl(raw: string): boolean;

package/dist/contracts/provider-url.js

@@ -0,0 +1,49 @@
+export function normalizeProviderOrigin(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        throw new Error(`Registry provided invalid provider URL: ${raw}`);
+    }
+}
+// Loopback only — used as a security boundary (CORS origin allow + the
+// "local provider" SSRF/registration allowlist), so it must classify the host
+// STRUCTURALLY, never by string prefix. "127.0.0.1.evil.com" and "127.evil.com"
+// begin with "127." but resolve to attacker-controlled IPs; they are not local.
+function isLoopbackIpv4(host) {
+    const octets = host.split(".");
+    if (octets.length !== 4)
+        return false;
+    if (!octets.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255))
+        return false;
+    return Number(octets[0]) === 127;
+}
+// Hosts that are never a legitimate provider and are the classic SSRF target:
+// link-local (169.254.0.0/16 — including the cloud-metadata endpoint
+// 169.254.169.254 — and IPv6 fe80::/10) plus the unspecified address. The
+// console probes/proxies registered provider URLs, so it must refuse to fetch
+// these. Loopback (console-managed providers) and LAN ranges (a supported remote
+// provider location) are intentionally NOT rejected here.
+export function isSsrfReservedProviderHost(raw) {
+    let host;
+    try {
+        host = new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    }
+    catch {
+        return false;
+    }
+    if (host === "0.0.0.0" || host === "::")
+        return true;
+    const octets = host.split(".");
+    if (octets.length === 4 && octets.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)) {
+        return Number(octets[0]) === 169 && Number(octets[1]) === 254;
+    }
+    // IPv6 link-local fe80::/10 spans fe80–febf.
+    return /^fe[89ab]/.test(host);
+}
+export function isLocalProviderUrl(raw) {
+    // URL.hostname keeps brackets for IPv6 (e.g. "[::1]"); strip them so the
+    // loopback literal compares cleanly.
+    const host = new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost" || host === "::1" || isLoopbackIpv4(host);
+}

package/dist/contracts/registry.d.ts

@@ -0,0 +1,58 @@
+export type RegistryProviderRecord = {
+    aliases?: string[];
+    baseUrl: string;
+    deploymentKind?: RegistryProviderDeploymentKind;
+    instanceId?: string;
+    label?: string;
+    lifecycle?: ManagedProviderSpec;
+    owner?: RegistryProviderOwner;
+    ownerOrganizationId?: string;
+    registrySource?: RegistryProviderSource;
+    requiresAuth?: boolean;
+    status?: RegistryProviderRuntimeStatus;
+    verifiedProvider?: RegistryVerifiedProvider;
+};
+export type RegistryProviderRuntimeStatus = {
+    lastProbedAt?: number;
+    message?: string;
+    phase: "down" | "failed" | "running" | "starting";
+    pid?: number;
+};
+export declare const managedProviderKinds: readonly ["docker-worker", "iterm", "virtual-tmux", "wezterm"];
+export type ManagedProviderKind = (typeof managedProviderKinds)[number];
+export type ManagedProviderSpec = {
+    kind: "iterm";
+    name: string;
+} | {
+    count: number;
+    kind: "virtual-tmux";
+    prefix: string;
+} | {
+    count: number;
+    kind: "wezterm";
+    prefix: string;
+} | {
+    kind: "docker-worker";
+    themeProfile?: string;
+};
+export type RegistryProviderOwner = {
+    fullName: string;
+    imageUrl?: string;
+    source: RegistryProviderOwnerSource;
+};
+export type RegistryProviderOwnerSource = "authenticated" | "self-declared";
+export type RegistryVerifiedProvider = {
+    buildSha?: string;
+    epoch?: string;
+    kind: string;
+    sourceBaseUrl?: string;
+    verifiedAt?: string;
+    version?: string;
+};
+export type RegistryProviderSource = "console-memory" | "local-registry" | "remote-registry";
+export type RegistryProviderDeploymentKind = "docker-worker" | "console-managed";
+export declare function normalizeRegistryPayload(payload: unknown): RegistryProviderRecord[];
+export declare function normalizeRegistryRegistrationResponse(payload: unknown, fallback: RegistryProviderRecord): RegistryProviderRecord;
+export declare function normalizeProviderAlias(value: string): string;
+export declare function mergeRegistryProviders(providers: RegistryProviderRecord[]): RegistryProviderRecord[];
+export declare function providerAliases(provider: RegistryProviderRecord): string[];

package/dist/contracts/registry.js

@@ -0,0 +1,285 @@
+import { normalizeProviderOrigin } from "./provider-url.js";
+// The kinds whose process lifecycle the console owns and can reconstruct. The
+// array is the source of truth (the type derives from it) so a runtime guard test
+// can assert every managed kind has a controller — catching a kind added here but
+// not given an ensure/probe/stop controller.
+export const managedProviderKinds = ["docker-worker", "iterm", "virtual-tmux", "wezterm"];
+export function normalizeRegistryPayload(payload) {
+    const providers = Array.isArray(payload)
+        ? payload
+        : (() => {
+            const candidate = payload;
+            if (!candidate || typeof candidate !== "object" || !Array.isArray(candidate.providers)) {
+                throw new Error("Registry response must be an array or an object with a providers array.");
+            }
+            return candidate.providers;
+        })();
+    return providers.map((entry, index) => {
+        const provider = normalizeRegistryEntry(entry, index);
+        return {
+            ...provider,
+            baseUrl: normalizeProviderOrigin(provider.baseUrl)
+        };
+    });
+}
+export function normalizeRegistryRegistrationResponse(payload, fallback) {
+    const candidates = extractRegistrationCandidates(payload);
+    const normalizedFallback = {
+        ...fallback,
+        baseUrl: normalizeProviderOrigin(fallback.baseUrl)
+    };
+    const match = candidates.find((candidate) => candidate.baseUrl === normalizedFallback.baseUrl);
+    if (match) {
+        return match;
+    }
+    const [single] = candidates;
+    if (candidates.length === 1 && single) {
+        return single;
+    }
+    return normalizedFallback;
+}
+function extractRegistrationCandidates(payload) {
+    if (!payload || typeof payload !== "object") {
+        return [];
+    }
+    const source = payload;
+    if (source.provider && typeof source.provider === "object") {
+        return tryNormalizeRegistryPayload([source.provider]);
+    }
+    if (Array.isArray(payload) || Array.isArray(source.providers)) {
+        return tryNormalizeRegistryPayload(payload);
+    }
+    return tryNormalizeRegistryPayload([payload]);
+}
+function tryNormalizeRegistryPayload(payload) {
+    try {
+        return normalizeRegistryPayload(payload);
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeRegistryEntry(entry, index) {
+    if (typeof entry === "string") {
+        return { baseUrl: entry, label: `Provider ${index + 1}` };
+    }
+    if (!entry || typeof entry !== "object") {
+        throw new Error(`Registry provider at index ${index} must be a string or object.`);
+    }
+    const source = entry;
+    const baseUrl = stringValue(source.baseUrl)
+        ?? stringValue(source.url)
+        ?? stringValue(source.endpoint)
+        ?? stringValue(source.tunnelUrl)
+        ?? stringValue(source.tunnel_url)
+        ?? stringValue(source.origin);
+    if (!baseUrl) {
+        throw new Error(`Registry provider at index ${index} is missing baseUrl.`);
+    }
+    return {
+        aliases: aliasesValue(source.aliases, source.alias),
+        baseUrl,
+        deploymentKind: deploymentKindValue(source.deploymentKind)
+            ?? deploymentKindValue(source.deployment_kind),
+        instanceId: stringValue(source.instanceId)
+            ?? stringValue(source.instance_id),
+        label: stringValue(source.label)
+            ?? stringValue(source.name)
+            ?? `Provider ${index + 1}`,
+        lifecycle: lifecycleValue(source.lifecycle),
+        owner: ownerValue(source.owner),
+        ownerOrganizationId: stringValue(source.ownerOrganizationId)
+            ?? stringValue(source.owner_organization_id)
+            ?? stringValue(source.organizationId)
+            ?? stringValue(source.organization_id),
+        registrySource: registrySourceValue(source.registrySource)
+            ?? registrySourceValue(source.registry_source),
+        requiresAuth: booleanValue(source.requiresAuth)
+            ?? booleanValue(source.requires_auth),
+        status: runtimeStatusValue(source.status),
+        verifiedProvider: verifiedProviderValue(source.verifiedProvider)
+            ?? verifiedProviderValue(source.verified_provider)
+    };
+}
+// The console's runtime liveness overlay, preserved through normalize so the UI
+// can read it. Conservative: an unrecognized phase degrades to undefined.
+function runtimeStatusValue(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const source = value;
+    if (source.phase !== "down" && source.phase !== "failed" && source.phase !== "running" && source.phase !== "starting") {
+        return undefined;
+    }
+    return {
+        ...(typeof source.lastProbedAt === "number" ? { lastProbedAt: source.lastProbedAt } : {}),
+        ...(typeof source.message === "string" ? { message: source.message } : {}),
+        phase: source.phase,
+        ...(typeof source.pid === "number" ? { pid: source.pid } : {})
+    };
+}
+export function normalizeProviderAlias(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) {
+        throw new Error(`Provider alias must use lowercase id-style characters: letters, numbers, dots, underscores, or hyphens. Got: ${JSON.stringify(value)}`);
+    }
+    return normalized;
+}
+function aliasesValue(aliases, alias) {
+    const values = [];
+    if (typeof alias === "string" && alias.trim()) {
+        values.push(alias);
+    }
+    if (typeof aliases === "string" && aliases.trim()) {
+        values.push(...aliases.split(","));
+    }
+    if (Array.isArray(aliases)) {
+        for (const entry of aliases) {
+            if (typeof entry === "string" && entry.trim()) {
+                values.push(entry);
+            }
+        }
+    }
+    const normalized = [...new Set(values.map(normalizeProviderAlias))];
+    return normalized.length > 0 ? normalized : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function registrySourceValue(value) {
+    if (value === "console-memory" || value === "local-registry" || value === "remote-registry") {
+        return value;
+    }
+    return undefined;
+}
+function deploymentKindValue(value) {
+    if (value === "docker-worker" || value === "console-managed") {
+        return value;
+    }
+    return undefined;
+}
+// Conservative: an unrecognized or malformed lifecycle spec parses to undefined
+// (the provider is treated as unmanaged) rather than throwing — a forward-compat
+// kind from a newer console must not break an older one reading the registry.
+function lifecycleValue(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const source = value;
+    if (source.kind === "iterm") {
+        const name = stringValue(source.name);
+        return name ? { kind: "iterm", name } : undefined;
+    }
+    if (source.kind === "virtual-tmux" || source.kind === "wezterm") {
+        const prefix = stringValue(source.prefix);
+        const count = countValue(source.count);
+        return prefix !== undefined && count !== undefined ? { count, kind: source.kind, prefix } : undefined;
+    }
+    if (source.kind === "docker-worker") {
+        const themeProfile = stringValue(source.themeProfile);
+        return { kind: "docker-worker", ...(themeProfile ? { themeProfile } : {}) };
+    }
+    return undefined;
+}
+function countValue(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function ownerValue(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const source = value;
+    const fullName = stringValue(source.fullName) ?? stringValue(source.full_name);
+    if (!fullName) {
+        return undefined;
+    }
+    const imageUrl = stringValue(source.imageUrl) ?? stringValue(source.image_url);
+    return {
+        fullName,
+        ...(imageUrl ? { imageUrl } : {}),
+        // An owner without recorded provenance counts as self-declared; only the
+        // registry server stamps "authenticated" from a signed-in session.
+        source: ownerSourceValue(source.source) ?? "self-declared"
+    };
+}
+function ownerSourceValue(value) {
+    if (value === "authenticated" || value === "self-declared") {
+        return value;
+    }
+    return undefined;
+}
+function verifiedProviderValue(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const source = value;
+    const kind = stringValue(source.kind)
+        ?? stringValue(source.provider)
+        ?? stringValue(source.providerKind)
+        ?? stringValue(source.provider_kind);
+    if (!kind) {
+        return undefined;
+    }
+    const version = stringValue(source.version);
+    const buildSha = stringValue(source.buildSha) ?? stringValue(source.build_sha);
+    const epoch = stringValue(source.epoch);
+    const sourceBaseUrl = stringValue(source.sourceBaseUrl) ?? stringValue(source.source_base_url);
+    const verifiedAt = stringValue(source.verifiedAt) ?? stringValue(source.verified_at);
+    return {
+        kind,
+        ...(version ? { version } : {}),
+        ...(buildSha ? { buildSha } : {}),
+        ...(epoch ? { epoch } : {}),
+        ...(sourceBaseUrl ? { sourceBaseUrl } : {}),
+        ...(verifiedAt ? { verifiedAt } : {})
+    };
+}
+// Merge registry records by baseUrl (last wins, but server-learned/stamped fields a
+// bare re-registration omits — instanceId/owner/lifecycle/etc. — fall back to the
+// existing value rather than being erased). The ONE merge: shared by the local
+// ProviderRegistry, the standalone serve-registry, and the Cloud Worker, so they
+// can't drift (the Worker's old private copy silently dropped aliases/lifecycle).
+export function mergeRegistryProviders(providers) {
+    const merged = new Map();
+    for (const provider of providers) {
+        const existing = merged.get(provider.baseUrl);
+        merged.set(provider.baseUrl, {
+            ...existing,
+            ...provider,
+            aliases: mergeProviderAliases(existing, provider),
+            deploymentKind: provider.deploymentKind ?? existing?.deploymentKind,
+            instanceId: provider.instanceId ?? existing?.instanceId,
+            lifecycle: provider.lifecycle ?? existing?.lifecycle,
+            owner: provider.owner ?? existing?.owner,
+            ownerOrganizationId: provider.ownerOrganizationId ?? existing?.ownerOrganizationId,
+            registrySource: preferredRegistrySource(existing?.registrySource, provider.registrySource),
+            requiresAuth: provider.requiresAuth ?? existing?.requiresAuth,
+            verifiedProvider: provider.verifiedProvider ?? existing?.verifiedProvider
+        });
+    }
+    return [...merged.values()];
+}
+export function providerAliases(provider) {
+    return (provider.aliases ?? []).map(normalizeProviderAlias);
+}
+function mergeProviderAliases(left, right) {
+    const aliases = [...new Set([...providerAliases(left ?? { baseUrl: right.baseUrl }), ...providerAliases(right)])];
+    return aliases.length > 0 ? aliases : undefined;
+}
+function preferredRegistrySource(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return registrySourceRank(right) > registrySourceRank(left) ? right : left;
+}
+function registrySourceRank(source) {
+    if (source === "local-registry")
+        return 3;
+    if (source === "console-memory")
+        return 2;
+    return 1;
+}

package/dist/launch-trace.d.ts

@@ -0,0 +1,6 @@
+export type LaunchTrace = {
+    readonly file: string;
+    event(type: string, data?: Record<string, unknown>): void;
+};
+export declare function launchTraceDir(): string;
+export declare function createLaunchTrace(label: string): LaunchTrace;

package/dist/launch-trace.js

@@ -0,0 +1,33 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function launchTraceDir() {
+    return process.env.TERMFLEET_LAUNCH_TRACE_DIR ?? join(homedir(), ".termfleet", "launch-traces");
+}
+let traceCounter = 0;
+export function createLaunchTrace(label) {
+    const directory = launchTraceDir();
+    traceCounter += 1;
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const slug = label.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "launch";
+    const file = join(directory, `${stamp}-${process.pid}-${traceCounter}-${slug}.jsonl`);
+    let disabled = false;
+    return {
+        event(type, data = {}) {
+            if (disabled) {
+                return;
+            }
+            try {
+                // 0700/0600: launch traces can capture terminal screen content on a
+                // failed launch — keep them owner-only on shared machines.
+                mkdirSync(directory, { mode: 0o700, recursive: true });
+                appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), type, ...data })}\n`, { mode: 0o600 });
+            }
+            catch (error) {
+                disabled = true;
+                console.error(`termfleet launch trace disabled, could not write ${file}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        file
+    };
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1 @@
+export declare function asError(value: unknown): Error;

package/dist/lib/errors.js

@@ -0,0 +1,5 @@
+// Coerce an unknown thrown value to an Error. Used everywhere a `catch (error)`
+// (typed `unknown`) needs `.message` — one definition instead of ~15 copies.
+export function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}

package/dist/lib/exec.d.ts

@@ -0,0 +1,13 @@
+export type RunOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+};
+export declare function commandExists(command: string): boolean;
+export declare function requireCommand(command: string, installHint?: string): void;
+export declare function run(command: string, args: string[], options?: RunOptions): string;
+export declare function runBuffer(command: string, args: string[], options?: RunOptions): Buffer;
+export declare function runWithInput(command: string, args: string[], input: Buffer, options?: RunOptions): Buffer;
+export declare function runAsync(command: string, args: string[], options?: RunOptions): Promise<string>;
+export declare function runWithInputAsync(command: string, args: string[], input: Buffer | string, options?: RunOptions): Promise<string>;
+export declare function spawnInherited(command: string, args: string[]): void;