@rallycry/conveyor-k3 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,777 @@
+import { PersonalClusterEnrollmentBundle, PersonalClusterEnrollmentCompletion, PersonalClusterDesiredState, PersonalClusterHeartbeat, PersonalClusterKubeletState } from '@project/shared';
+
+interface ClusterConnectionConfig {
+    apiUrl: string;
+    clusterToken: string;
+    /** Test-only override; production always reads the root-owned guest key. */
+    deviceKeyPath?: string;
+}
+declare class ClusterConnection {
+    private socket;
+    private readonly config;
+    /** Called when Conveyor says the desired state changed. */
+    onSyncRequested: (() => void) | null;
+    /** Called when Conveyor asks the machine to remove itself. */
+    onUninstall: (() => Promise<void>) | null;
+    constructor(config: ClusterConnectionConfig);
+    connect(): Promise<void>;
+    private require;
+    enroll(): Promise<PersonalClusterEnrollmentBundle>;
+    completeEnrollment(payload: PersonalClusterEnrollmentCompletion): Promise<void>;
+    requestDesiredState(): Promise<PersonalClusterDesiredState>;
+    /** Fire-and-forget: a lost heartbeat is covered by the next one. */
+    sendHeartbeat(payload: PersonalClusterHeartbeat): void;
+    /**
+     * Tell Conveyor this machine is stopping, so placement skips it at once
+     * instead of waiting out the stale window.
+     */
+    sayGoodbye(timeoutMs?: number): Promise<void>;
+    disconnect(): void;
+}
+
+interface RunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface RunOptions {
+    /** Hard cap on runtime. The process is SIGTERMed on timeout. */
+    timeoutMs?: number;
+    /** Bound output from untrusted guests before it can exhaust host memory. */
+    maxOutputBytes?: number;
+    /** Isolate and terminate the whole command tree for guest SSH commands. */
+    killProcessGroup?: boolean;
+    /** Piped to the child's stdin, for `--password-stdin` style input. */
+    stdin?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Runs a command and returns its result — including a NON-ZERO exit.
+ *
+ * Deliberately not throwing. Almost every caller here has a meaningful
+ * response to a failure (defer a restart, record a warning, try the next
+ * image) and exceptions would turn each of those into a try/catch. The two
+ * places that genuinely require success use {@link runOrThrow}.
+ */
+type Executor = (bin: string, args: readonly string[], options?: RunOptions) => Promise<RunResult>;
+declare const spawnExecutor: Executor;
+declare class CommandError extends Error {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(bin: string, result: RunResult);
+}
+/** Run a command and throw {@link CommandError} unless it exits 0. */
+declare function runOrThrow(exec: Executor, bin: string, args: readonly string[], options?: RunOptions): Promise<RunResult>;
+
+interface FileSystemPort$1 {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string, mode?: number): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    ensureDir(path: string): Promise<void>;
+}
+declare const nodeFileSystem: FileSystemPort$1;
+/** In-memory filesystem for tests. Exported so suites share one shape. */
+declare function createMemoryFileSystem(seed?: Record<string, string>): FileSystemPort$1 & {
+    files: Map<string, string>;
+    modes: Map<string, number>;
+    removed: string[];
+};
+
+interface DaemonPorts {
+    exec: Executor;
+    fs: FileSystemPort$1;
+    connection: ClusterConnection;
+    cliVersion: string;
+    log: (line: string) => void;
+}
+declare class ClusterDaemon {
+    private readonly ports;
+    private desired;
+    private state;
+    private warnings;
+    /**
+     * The image-GC high threshold the kubelet is really using — ours, or the
+     * owner's when their own config.yaml set it and the drop-in stood down.
+     * Null until the first reconcile has read both.
+     */
+    private effectiveImageGcHigh;
+    /**
+     * Warnings the last warm produced, as opposed to the last reconcile.
+     *
+     * Kept separate because the two clocks are separate: a warm runs hourly and
+     * a reconcile daily, and folding warm's findings into `warnings` would have
+     * the next reconcile silently clear them.
+     */
+    private warmWarnings;
+    private timers;
+    /** Serializes reconcile against itself — a sync nudge during a reconcile
+     *  must queue, not interleave two kubectl applies of the same manifests. */
+    private reconciling;
+    constructor(ports: DaemonPorts);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Fetch the desired state and converge to it. Queued, never concurrent. */
+    syncAndReconcile(): Promise<void>;
+    private runReconcile;
+    /**
+     * The hourly clock: warm, re-pin, and reclaim if the pile justifies it.
+     *
+     * The prune check rides the hourly warm rather than the daily reconcile
+     * because that is the cadence a bake-heavy day actually needs. With the
+     * kubelet back on its own thresholds, nothing else clears stranded
+     * generations in between.
+     */
+    private warmAndPruneIfDue;
+    /** Pre-pull the wanted refs. Silent on success; that is the normal case. */
+    warm(): Promise<void>;
+    /**
+     * Take the wanted refs out of the kubelet's reach, and release the ones that
+     * have left the wanted set.
+     *
+     * Runs on every warm, not once: importing an image under the same ref
+     * replaces the containerd record and drops the label with it, so a bake
+     * always leaves its `:current` unpinned until the next pass. It pins from
+     * the INVENTORY rather than from what warm pulled, because `warmImages`
+     * skips `localhost/` refs — which are the ones a local bake produces, and
+     * the ones that were actually being deleted.
+     */
+    private pinWanted;
+    /** Prune daily, or sooner when the disk is tight. */
+    private pruneIfDue;
+    /**
+     * Whether stranded generations alone justify a prune now.
+     *
+     * A bake-heavy day strands several gigabytes per bake, and with the kubelet
+     * back on its own thresholds nothing else clears them before the daily run.
+     * An unreadable inventory answers false: the prune itself would refuse the
+     * cycle anyway, and guessing "yes" would just run it to find that out.
+     */
+    private strandedBytesExceedLimit;
+    prune(): Promise<void>;
+    private buildHeartbeat;
+    beat(): Promise<void>;
+}
+
+/**
+ * Converge the machine onto Conveyor's desired state.
+ *
+ * This is what "manages itself" means in code. Conveyor publishes what the
+ * cluster SHOULD look like; this function makes it so, and it runs on connect,
+ * on request, and daily. Nothing here is a command from the server — a machine
+ * that was powered off for a week catches up on its next run, and a practice
+ * Conveyor changes reaches every enrolled box without anyone touching one.
+ *
+ * Three properties every step keeps:
+ *
+ * 1. **Idempotent.** Running twice changes nothing the first run already did.
+ * 2. **Independently fallible.** A step that fails records a warning and the
+ *    rest still run. A cluster with one bad namespace is not a reason to skip
+ *    image hygiene.
+ * 3. **Additive.** Nothing here deletes a namespace, a workload, or an image
+ *    that is in use. The machine belongs to its owner.
+ * 4. **Bounded.** The server does not get to say what runs here. The one field
+ *    it sends as raw YAML is checked against a local kind allowlist before it
+ *    reaches `kubectl` — see `../lib/manifest-guard.js`.
+ */
+
+/** The filesystem operations reconcile needs, injectable for tests. */
+interface FileSystemPort {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string, mode?: number): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    ensureDir(path: string): Promise<void>;
+}
+interface ReconcileContext {
+    exec: Executor;
+    fs: FileSystemPort;
+    /**
+     * Conveyor pods currently running here, or null when that could not be
+     * determined. A disruptive step is unsafe above zero AND unsafe on null —
+     * "I could not ask" is not "nothing is running".
+     */
+    runningConveyorPods: number | null;
+}
+interface ReconcileResult {
+    appliedVersion: number;
+    warnings: string[];
+    /** True when the kubelet drop-in changed and k3s was restarted. */
+    restartedK3s: boolean;
+    /** Kubelet flags left to the owner because their own config sets them. */
+    skippedKubeletFlags: string[];
+    /**
+     * The image-GC high threshold the kubelet is actually enforcing — ours, or
+     * the owner's when their own config.yaml set it and the drop-in stood down.
+     * Null when neither side named one. Reported so the heartbeat can warn about
+     * GC pressure against the number in force rather than the one we sent.
+     */
+    effectiveImageGcHighThreshold: number | null;
+    /** True when a wrong-valued PriorityClass was deleted AND put back. */
+    recreatedPriorityClass: boolean;
+}
+declare function reconcile(ctx: ReconcileContext, desired: PersonalClusterDesiredState): Promise<ReconcileResult>;
+
+/** One entry of `crictl images -o json`. */
+interface CrictlImage {
+    id: string;
+    repoTags?: string[];
+    repoDigests?: string[];
+    size?: string;
+    /** CRI reports this for a pinned image; absent on a runtime too old to say. */
+    pinned?: boolean;
+}
+interface ImageInventory {
+    images: CrictlImage[];
+    /** Image ids referenced by a container, running or not. */
+    referencedIds: Set<string>;
+}
+interface PruneCandidate {
+    id: string;
+    sizeBytes: number;
+}
+/**
+ * Which images may be removed.
+ *
+ * Pure, so the selection table is testable against a real `crictl images`
+ * fixture rather than inferred from what the daemon happened to delete.
+ */
+declare function selectStrandedImages(inventory: ImageInventory, wantedImages: string[]): PruneCandidate[];
+/** Read the machine's images and which of them containers are holding. */
+declare function readImageInventory(exec: Executor): Promise<ImageInventory>;
+interface PruneResult {
+    removed: number;
+    bytesReclaimed: number;
+    failures: string[];
+}
+/** Remove the stranded images. Individual failures are reported, not thrown. */
+declare function pruneStrandedImages(exec: Executor, inventory: ImageInventory, wantedImages: string[]): Promise<PruneResult>;
+interface WarmResult {
+    pulled: string[];
+    skipped: string[];
+    failures: string[];
+    /** How many refs were skipped for being on Artifact Registry. */
+    skippedArtifactRegistry: number;
+}
+/**
+ * Pre-pull the refs a build will ask for.
+ *
+ * A no-op download when the ref has not moved, and the difference between a
+ * card starting immediately and a card waiting on a multi-gigabyte cold pull
+ * right after a bake.
+ *
+ * Three kinds of ref are skipped rather than attempted:
+ * - `localhost/...`, which a local bake already imported into containerd and
+ *   which no registry can serve.
+ * - anything on a host we know has no credential, because that pull would
+ *   fail slowly and noisily every hour.
+ * - Artifact Registry, whatever the credential. A personal cluster sits
+ *   outside GCP, so that pull crosses the internet and is billed as AR egress
+ *   — and such a ref is never placed here, so it buys nothing. The server
+ *   already excludes these from `warmImages`, but a daemon can be running a
+ *   desired state older than that field, so the refusal lives here too.
+ */
+declare function warmImages(exec: Executor, wantedImages: string[], unauthenticatedHosts: string[]): Promise<WarmResult>;
+
+interface TelemetryState {
+    cliVersion: string;
+    appliedDesiredStateVersion: number;
+    wantedImages: string[];
+    authRequiredHosts: string[];
+    lastPruneAt: string | null;
+    lastWarmAt: string | null;
+    lastUpdateAt: string | null;
+    localWarnings: string[];
+    /**
+     * The image-GC high threshold the kubelet is really enforcing, or null when
+     * no reconcile has read one yet. Drives the GC-pressure warning below.
+     */
+    imageGcHighThreshold?: number | null;
+}
+interface TelemetryPorts {
+    exec: Executor;
+    readFile(path: string): Promise<string | null>;
+}
+/**
+ * Conveyor pods running here, across every namespace it manages — or null when
+ * that cannot be determined.
+ *
+ * Three destructive operations gate on this number: the k3s restart after a
+ * kubelet change, the k3s channel upgrade, and the PriorityClass recreate. So
+ * "I could not ask" must NOT collapse to "nothing is running" — that reads as
+ * an idle machine and takes a card down mid-build. It returns null instead, and
+ * every guard treats null as busy.
+ *
+ * The selector comes from `@project/shared` because the API stamps the same
+ * label on the pods it creates. A hand-written selector here silently matched
+ * nothing and disabled all three guards at once.
+ */
+declare function countRunningConveyorPods(exec: Executor): Promise<number | null>;
+declare function collectHeartbeat(ports: TelemetryPorts, state: TelemetryState, inventory: ImageInventory | null): Promise<PersonalClusterHeartbeat>;
+
+interface RegistryAuth {
+    username?: string;
+    password?: string;
+    auth?: string;
+    identitytoken?: string;
+}
+interface RegistryConfigEntry {
+    auth?: RegistryAuth;
+    tls?: Record<string, unknown>;
+}
+interface RegistriesFile {
+    mirrors?: Record<string, unknown>;
+    configs?: Record<string, RegistryConfigEntry>;
+    [key: string]: unknown;
+}
+/** Parse the file. An absent or empty file is an empty config, not an error. */
+declare function parseRegistries(raw: string | null): RegistriesFile;
+/** Hosts that already carry a credential. */
+declare function configuredAuthHosts(file: RegistriesFile): string[];
+/**
+ * Required hosts with no credential configured.
+ *
+ * This is what the daemon reports in its heartbeat and what the profile turns
+ * into a `conveyor-k3 registry add <host>` line. Without it, the first
+ * acceptance run stalls on an unauthenticated multi-gigabyte pull with nothing
+ * saying why.
+ */
+declare function missingAuthHosts(file: RegistriesFile, requiredHosts: string[]): string[];
+/**
+ * Insert or replace ONE host's auth entry, preserving everything else.
+ *
+ * Everything outside `configs.<host>.auth` is carried through untouched:
+ * other hosts, the `mirrors` block, and the target host's own `tls` settings.
+ */
+declare function upsertRegistryAuth(file: RegistriesFile, host: string, auth: RegistryAuth): RegistriesFile;
+/** Serialize back to YAML. */
+declare function serializeRegistries(file: RegistriesFile): string;
+
+/**
+ * The k3s configuration Conveyor sets, as a drop-in.
+ *
+ * k3s reads `/etc/rancher/k3s/config.yaml` and then every `*.yaml` under
+ * `config.yaml.d/`, merging them. Our settings go in the drop-in so the
+ * owner's `config.yaml` is never rewritten — this machine is theirs, and a
+ * managed cluster that silently replaced their config would be worse than no
+ * managed mode at all.
+ *
+ * Two details make the merge safe:
+ *
+ * - `kubelet-arg+:` APPENDS to any `kubelet-arg` list the owner already has,
+ *   where a bare `kubelet-arg:` would replace it.
+ * - A GC threshold the owner already sets in their own `config.yaml` is
+ *   SKIPPED, not overridden. They chose a number for a reason, and duplicate
+ *   kubelet flags are a startup failure, not a last-wins merge.
+ */
+
+/**
+ * Bundled components Conveyor turns off, and the kubeconfig mode it sets.
+ *
+ * These were passed to the k3s INSTALLER at setup, which is where they stopped
+ * surviving: the installer rebuilds the unit's `ExecStart` from its own
+ * arguments on every run, so an upgrade that does not repeat them rewrites the
+ * unit to a bare `k3s server` and traefik and servicelb come back — claiming
+ * host ports 80 and 443 on a machine its owner uses for other things.
+ *
+ * k3s merges the drop-in on every start regardless of how the unit was
+ * written, so carrying them here makes them survive an upgrade by construction
+ * rather than by remembering to pass them again. `update.ts` passes the same
+ * exec string as well, so the unit stays identical too — belt and braces.
+ */
+declare const K3S_DISABLED_COMPONENTS: readonly ["traefik", "servicelb"];
+/**
+ * What `setup` and `update` both pass as `INSTALL_K3S_EXEC`.
+ *
+ * One constant because the installer has no "keep what is there" mode: an
+ * unset value means a bare `k3s server`, so the two call sites drifting apart
+ * is exactly the bug this fixes.
+ */
+declare const K3S_INSTALL_EXEC: string;
+interface DropInRenderResult {
+    /** The file to write, or null when the owner already set everything. */
+    content: string | null;
+    /** Flags skipped because the owner's own config already sets them. */
+    skipped: string[];
+}
+/**
+ * Which kubelet flags the owner's `config.yaml` already sets.
+ *
+ * A deliberately textual scan rather than a YAML parse: we only need to know
+ * whether a flag NAME appears under a `kubelet-arg` key, and a config that
+ * fails to parse must not stop us reporting what we can see. Over-detecting
+ * costs a skipped flag and a note; under-detecting costs a kubelet that will
+ * not start.
+ */
+declare function ownerConfiguredKubeletFlags(ownerConfig: string | null): Set<string>;
+/**
+ * Whether the owner's `config.yaml` sets a top-level key of its own.
+ *
+ * Same textual-scan reasoning as the kubelet flags above: a top-level key is
+ * `key:` at column zero, and a config that fails to parse must not stop us
+ * reporting what we can see.
+ */
+declare function ownerConfiguredKeys(ownerConfig: string | null): Set<string>;
+/**
+ * Render the drop-in: the kubelet settings, plus the components Conveyor turns
+ * off and the kubeconfig mode it sets.
+ *
+ * Returns `content: null` when there is nothing left for us to set, so the
+ * caller can remove a stale drop-in rather than leaving an empty one behind.
+ *
+ * `disable+:` APPENDS, so an owner who disables something of their own keeps
+ * it and gains ours. That is why the disables are not skipped the way a
+ * kubelet flag is: duplicate kubelet flags are a startup failure, whereas
+ * `disable` is a set of component names where a repeat is harmless — and
+ * standing down would quietly re-enable servicelb for an owner who had only
+ * meant to disable traefik.
+ *
+ * `write-kubeconfig-mode` IS skipped when the owner sets it: it is a scalar
+ * they chose, and last-writer-wins on their own file is exactly what this
+ * module exists not to do.
+ */
+declare function renderK3sDropIn(kubelet: PersonalClusterKubeletState, ownerConfig: string | null): DropInRenderResult;
+/**
+ * @deprecated Use {@link renderK3sDropIn}. Kept as a named alias because the
+ * package exports it and a published CLI may still import it by this name.
+ */
+declare const renderKubeletDropIn: typeof renderK3sDropIn;
+
+interface UnitRenderOptions {
+    /** Absolute path to the installed `conveyor-k3` binary. */
+    cliBin: string;
+    /** Absolute path to `cloudflared`. */
+    cloudflaredBin: string;
+    /** Local hour (0-23) the update timer fires in. */
+    maintenanceHour: number;
+}
+/** Every unit file this CLI writes, keyed by unit name. */
+declare function renderAllUnits(options: UnitRenderOptions): Record<string, string>;
+
+/**
+ * The machine's own record of what it has done.
+ *
+ * Small on purpose: everything authoritative lives on Conveyor's side, and
+ * this file exists so a daemon restart does not re-warm every image or forget
+ * which settings version it applied. Losing it costs one extra reconcile.
+ */
+
+interface MachineState {
+    /** The desired-state version last successfully applied. */
+    appliedDesiredStateVersion: number;
+    /** Tunnel hostname Conveyor routed here, for `status` to print. */
+    hostname: string | null;
+    /** True once the ServiceAccount token has been handed to Conveyor. */
+    enrolled: boolean;
+    lastPruneAt: string | null;
+    lastWarmAt: string | null;
+    lastUpdateAt: string | null;
+    /**
+     * Absolute paths setup resolved for the binaries the updater invokes.
+     *
+     * Recorded because systemd's default unit PATH does not include
+     * `/root/.bun/bin`, so a bare name is ENOENT from the update timer. Optional:
+     * a state file written before this field existed falls back to `which`.
+     */
+    bins?: {
+        bun: string;
+        cli: string;
+        cloudflared: string;
+    };
+    /**
+     * Refs this daemon has labelled `io.cri-containerd.pinned`.
+     *
+     * Recorded so a ref that LEAVES the wanted set can be released again. The
+     * node's own pinned images — the pause sandbox, a co-tenant's — look
+     * identical to a demoted one from the inventory alone, so "pinned but not
+     * wanted" is not a safe rule to unpin on. Only what we pinned, we unpin.
+     */
+    pinnedImages?: string[];
+}
+declare function readState(fs: FileSystemPort$1): Promise<MachineState>;
+declare function writeState(fs: FileSystemPort$1, state: MachineState): Promise<void>;
+
+/**
+ * The verb table.
+ *
+ * One binary and one table, rather than the deployment runner's no-argv-at-all
+ * or conveyor-mcp's one-bin-per-verb. A machine's owner types these, so the
+ * help output below is part of the product: every verb states what it does to
+ * their machine, and `uninstall` states what it does not.
+ */
+declare const VERBS: readonly ["vm", "setup", "start", "stop", "status", "sync", "update", "registry", "runners", "uninstall", "daemon"];
+type Verb = (typeof VERBS)[number];
+declare function isVerb(value: string): value is Verb;
+interface ParsedArgs {
+    verb: Verb | null;
+    /** Positional arguments after the verb (e.g. the registry host). */
+    positional: string[];
+    flags: Record<string, string | true>;
+}
+/**
+ * Parse `conveyor-k3 <verb> [positional…] [--flag[=value]]`.
+ *
+ * Deliberately small. A dependency-free parser is auditable at a glance, and
+ * this surface is nine verbs and six flags, not a general CLI framework.
+ */
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare const HELP = "conveyor-k3 \u2014 managed personal compute for Conveyor\n\nUsage: conveyor-k3 <command> [options]\n\nCommands:\n  vm                    Manage isolated compute on macOS or Linux.\n                        Run conveyor-k3 vm for host lifecycle commands.\n  setup                 Install and enrol this machine. Safe to re-run.\n  start                 Start the tunnel and the daemon.\n  stop                  Stop both, and tell Conveyor at once so your next\n                        build goes straight to project compute.\n  status [--json]       What is running, what Conveyor knows, and what is\n                        missing.\n  sync                  Re-read your settings from Conveyor and apply them.\n  update                Update conveyor-k3, cloudflared, and (when you have\n                        allowed it and nothing is running) k3s.\n  registry list         Which registry credentials are configured, and which\n                        ones your projects still need.\n  registry add <host>   Add one registry credential.\n                          --username <user>\n                          --password-stdin      read the password from stdin\n                          --no-restart          skip the required k3s restart\n  runners list          Which GitHub Actions runners this machine hosts, and\n                        whether each may import a locally baked image.\n  runners grant <user>\u2026 Let those runner users import a locally baked image\n                        into this node and pin it. Writes one file under\n                        /etc/sudoers.d, checked with visudo first. Needed only\n                        when a project has Bake Locally turned on.\n  uninstall             Remove Conveyor's units, environment, and state. Your\n                        k3s config, registries.yaml, and workloads are left\n                        alone.\n                          --purge-k3s --yes     also remove k3s itself\n  daemon                Run in the foreground (what the systemd unit calls).\n\nOptions:\n  --version             Print the version.\n  --help                Print this message.\n\nDocs: https://conveyor.rallycryapp.com/docs/guides/managed-personal-compute\n";
+
+/**
+ * `conveyor-k3 registry add|list` — the one place this CLI writes
+ * `registries.yaml`.
+ *
+ * The reconcile loop never touches that file. Only an explicit command does,
+ * it takes a timestamped backup first, and it merges rather than templates —
+ * so a machine pulling through its own LAN mirror keeps that mirror, its TLS
+ * settings, and every other host it had configured.
+ *
+ * A restart is required and is not optional: k3s reads `registries.yaml` at
+ * startup only, so a credential added without one silently does nothing.
+ */
+
+interface RegistryPorts {
+    exec: Executor;
+    fs: FileSystemPort$1;
+    log: (line: string) => void;
+    /** Injected so the backup filename is deterministic in tests. */
+    now: () => Date;
+}
+interface RegistryAddOptions {
+    host: string;
+    username?: string;
+    password?: string;
+    /** Skip the k3s restart. The caller must then restart it themselves. */
+    noRestart?: boolean;
+}
+interface RegistryAddResult {
+    backupPath: string | null;
+    restarted: boolean;
+}
+declare function registryAdd(ports: RegistryPorts, options: RegistryAddOptions): Promise<RegistryAddResult>;
+interface RegistryCoverage {
+    configured: string[];
+    missing: string[];
+}
+/** What is configured against what Conveyor says this machine needs. */
+declare function registryList(ports: RegistryPorts, requiredHosts: string[]): Promise<RegistryCoverage>;
+/**
+ * The lines `setup` prints at the very end.
+ *
+ * Without this the acceptance flow stalls on an unauthenticated multi-gigabyte
+ * pull with nothing saying why, so it is part of setup's contract rather than
+ * a nicety.
+ */
+declare function renderRegistryAuthSummary(missing: string[]): string[];
+
+/**
+ * `conveyor-k3 uninstall` — remove exactly what Conveyor put on this machine.
+ *
+ * Everything this CLI created carries a `conveyor-k3` name and lives under
+ * `/etc/conveyor` or `/var/lib/conveyor-k3`, which is what makes a precise
+ * removal possible. Nothing else is touched: not the owner's `config.yaml`,
+ * not `registries.yaml`, not their workloads.
+ *
+ * k3s itself is NOT removed by default. On most machines it predates us, or
+ * the owner wants to keep it — so removing it is `--purge-k3s`, and even then
+ * only after an explicit confirmation.
+ */
+
+interface UninstallPorts {
+    exec: Executor;
+    fs: FileSystemPort$1;
+    log: (line: string) => void;
+}
+interface UninstallOptions {
+    /** Also run k3s-uninstall.sh. Requires `confirmed`. */
+    purgeK3s?: boolean;
+    /** The caller has an explicit yes from the person running this. */
+    confirmed?: boolean;
+    /** Conveyor asked for this, so the "click Disconnect" reminder is moot. */
+    serverInitiated?: boolean;
+}
+interface UninstallResult {
+    stoppedUnits: string[];
+    removedFiles: string[];
+    purgedK3s: boolean;
+}
+declare function uninstall(ports: UninstallPorts, options?: UninstallOptions): Promise<UninstallResult>;
+
+/**
+ * `conveyor-k3 update` — the maintenance-window updater.
+ *
+ * Updates ride a systemd timer and NEVER runtime self-replacement. The agent
+ * removed runtime self-update after the 2026-07-19 eviction outage; a daemon
+ * that swaps its own binary mid-run has exactly the same failure shape. Here
+ * the package is replaced by a separate oneshot unit, and the daemon is
+ * restarted afterwards by systemd.
+ *
+ * Three independent pieces, each with its own decision:
+ *
+ * - **The package.** Installed at the EXACT version Conveyor's desired state
+ *   names, never `@latest` — the npm dist-tag is a root-execution channel on
+ *   every enrolled machine, so a compromised publish would reach them all
+ *   within a day. The daemon restarts only if the version actually moved.
+ * - **cloudflared.** `cloudflared update` exits 11 to mean "updated"; that is
+ *   the only case that needs a tunnel restart.
+ * - **k3s.** Only when the owner allowed it AND nothing of Conveyor's is
+ *   running. A k3s upgrade at the wrong moment interrupts someone's build, and
+ *   no upgrade is worth that.
+ */
+
+interface UpdatePorts {
+    exec: Executor;
+    log: (line: string) => void;
+    /**
+     * Absolute paths to the binaries this updater invokes.
+     *
+     * Absolute, not bare names, because this runs from a systemd oneshot whose
+     * default PATH is `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`
+     * — which does not include `/root/.bun/bin`, where the installer puts both
+     * Bun and this CLI. Bare names made every timed update exit 1 on ENOENT
+     * before it did anything, silently, forever.
+     */
+    bins: UpdateBinaries;
+}
+interface UpdateBinaries {
+    bun: string;
+    cli: string;
+    cloudflared: string;
+}
+interface UpdateDecisionInput {
+    autoUpgradeK3s: boolean;
+    /** Null when the count could not be read — treated exactly like "busy". */
+    runningConveyorPods: number | null;
+    installedK3s: [number, number] | null;
+    channelLatestK3s: [number, number] | null;
+}
+type K3sUpgradeDecision = {
+    upgrade: true;
+} | {
+    upgrade: false;
+    reason: string;
+};
+/**
+ * Whether to take a k3s upgrade right now.
+ *
+ * Pure so the table is testable: the interesting cases are "owner said no",
+ * "machine is busy", and "already current", and each must produce a distinct
+ * reason the owner can read in their health panel.
+ */
+declare function decideK3sUpgrade(input: UpdateDecisionInput): K3sUpgradeDecision;
+interface UpdateResult {
+    packageUpdated: boolean;
+    cloudflaredUpdated: boolean;
+    k3sUpgraded: boolean;
+    notes: string[];
+}
+/**
+ * @param targetVersion The `cli.latestVersion` from desired state. Null or
+ * empty skips the package update instead of falling back to a dist-tag.
+ */
+declare function runUpdate(ports: UpdatePorts, decision: K3sUpgradeDecision, channel: string, targetVersion: string | null): Promise<UpdateResult>;
+
+/**
+ * `conveyor-k3 setup` — bring a machine from "nothing" to "running builds".
+ *
+ * Idempotent from end to end. Running it twice is the normal way to repair a
+ * half-finished install, so every step checks before it acts: k3s is installed
+ * only when absent, cloudflared only when absent, and the units are rewritten
+ * only when their content changed.
+ *
+ * The step order matters in one place. The ServiceAccount token is minted and
+ * handed to Conveyor LAST, because that write is what flips the cluster to
+ * enabled — so it must not happen until the tunnel, the RBAC, and the units
+ * are all actually in place. A cluster marked usable before it is usable sends
+ * the owner's next card to a machine that cannot run it.
+ */
+
+/** Parse `k3s version v1.31.0+k3s1` into [major, minor]. */
+declare function parseK3sVersion(output: string): [number, number] | null;
+declare function meetsK3sMinimum(version: [number, number] | null): boolean;
+
+interface NetworkEndpoint {
+    host: string;
+    ports: number[];
+}
+interface ResolvedNetworkHost {
+    /** Canonical hostname written into the guest's static DNS data. */
+    name: string;
+    /** An address on WORKER_SUBNET; it is never a real remote address. */
+    guestIp: string;
+    /** Host-resolved, pinned, globally-routable IPv4 address. */
+    address: string;
+    ports: number[];
+}
+interface GuestSrvRecord {
+    name: string;
+    target: string;
+    port: number;
+    priority: number;
+    weight: number;
+}
+interface ResolvedNetwork {
+    hosts: ResolvedNetworkHost[];
+    /** Static SRV answers needed by cloudflared's documented edge discovery. */
+    srv: GuestSrvRecord[];
+}
+/** Alias used by the VM host manager. */
+type NetworkPolicy = ResolvedNetwork;
+type IPv4Lookup = (host: string) => Promise<string[]>;
+type SRVLookup = (name: string) => Promise<Array<{
+    name: string;
+    port: number;
+    priority: number;
+    weight: number;
+}>>;
+/** Reject addresses which cannot be a public Internet destination. */
+declare function isGloballyRoutableIPv4(address: string): boolean;
+/**
+ * Resolve approved egress destinations on the host before VM creation.
+ *
+ * The guest receives only synthetic addresses. Its root user may change its
+ * resolver or hosts file, but it cannot add a QEMU guestfwd rule, so this does
+ * not turn into arbitrary egress. Every answer is checked, rather than picking
+ * a public answer from a mixed public/private DNS response.
+ */
+declare function resolveNetwork(endpoints: NetworkEndpoint[], lookup?: IPv4Lookup): Promise<ResolvedNetwork>;
+/**
+ * Build static SRV results only when their region targets were explicitly
+ * approved. Callers opt into us-region targets by including them in endpoints.
+ */
+declare function cloudflaredSrvRecords(hosts: ResolvedNetworkHost[]): GuestSrvRecord[];
+/**
+ * Resolve Cloudflare's current SRV discovery records on the host and retain
+ * only targets explicitly present in the fixed endpoint allowlist. This is an
+ * opt-in refresh helper: callers must recreate the worker when an answer
+ * changes, and a guest never performs this lookup itself.
+ */
+declare function resolveCloudflaredSrvRecords(hosts: ResolvedNetworkHost[], lookup?: SRVLookup): Promise<GuestSrvRecord[]>;
+
+interface GuestDnsProvision {
+    /** Write verbatim to /etc/conveyor-vm/dns.json (mode 0600). */
+    data: string;
+    /** Write verbatim to /usr/local/lib/conveyor-vm-static-dns.py (mode 0755). */
+    daemon: string;
+    /** Write verbatim to /etc/systemd/system/conveyor-vm-static-dns.service. */
+    unit: string;
+    /** Write verbatim to /etc/resolv.conf after disabling any local stub resolver. */
+    resolvConf: string;
+}
+/**
+ * The daemon is deliberately a small authoritative server, not a forwarding
+ * resolver. It answers only the creation-time allowlist and returns NXDOMAIN
+ * for everything else. The network data is JSON, never interpolated as Python.
+ */
+declare function renderGuestDnsProvision(network: ResolvedNetwork): GuestDnsProvision;
+
+interface QemuNetworkPolicy extends ResolvedNetwork {
+    sshPort: number;
+}
+/** Host-only information used to tie QEMU file endpoints to one Lima instance. */
+interface QemuPolicyContext {
+    instanceDir?: string;
+}
+/** Rewrites only a complete, known Lima QEMU profile; every unknown input fails closed. */
+declare function rewriteQemuArgs(args: string[], network: QemuNetworkPolicy, ncPath?: string, context?: QemuPolicyContext): string[];
+
+export { ClusterConnection, type ClusterConnectionConfig, ClusterDaemon, CommandError, type CrictlImage, type DaemonPorts, type Executor, type FileSystemPort$1 as FileSystemPort, type GuestDnsProvision, type GuestSrvRecord, HELP, type ImageInventory, K3S_DISABLED_COMPONENTS, K3S_INSTALL_EXEC, type K3sUpgradeDecision, type MachineState, type NetworkEndpoint, type NetworkPolicy, type QemuNetworkPolicy, type ReconcileContext, type ReconcileResult, type RegistriesFile, type ResolvedNetwork, type ResolvedNetworkHost, type SRVLookup, type UninstallResult, type UnitRenderOptions, VERBS, type Verb, cloudflaredSrvRecords, collectHeartbeat, configuredAuthHosts, countRunningConveyorPods, createMemoryFileSystem, decideK3sUpgrade, isGloballyRoutableIPv4, isVerb, meetsK3sMinimum, missingAuthHosts, nodeFileSystem, ownerConfiguredKeys, ownerConfiguredKubeletFlags, parseArgs, parseK3sVersion, parseRegistries, pruneStrandedImages, readImageInventory, readState, reconcile, registryAdd, registryList, renderAllUnits, renderGuestDnsProvision, renderK3sDropIn, renderKubeletDropIn, renderRegistryAuthSummary, resolveCloudflaredSrvRecords, resolveNetwork, rewriteQemuArgs, runOrThrow, runUpdate, selectStrandedImages, serializeRegistries, spawnExecutor, uninstall, upsertRegistryAuth, warmImages, writeState };