@tikoci/quickchr 0.4.1 → 0.4.2

package/DESIGN.md

@@ -46,13 +46,13 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
    How to tell it's firing: grep CI `qemu.log`/run logs for `respawning QEMU once`. A frequent occurrence, or a `BOOT_TIMEOUT` that *survives* the respawn (or appears on the `_launchExisting` path), is the signal to stop treating it as a flake and find the real cause. Tracked in `BACKLOG.md` (boot-respawn watch-item).
 
-9. **Resilient downloads via public DNS** — All fetches to MikroTik's `upgrade`/`download` hosts go through `fetchResilient()` (`src/lib/net.ts`), never bare `fetch()`. The real failure mode, confirmed by an on-runner probe (2026-06-16), is that **GitHub-hosted runners' system resolver returns `ESERVFAIL` for `*.mikrotik.com`** — slowly (2–26 s) — via *both* `getaddrinfo` and c-ares-over-`resolv.conf`. So a plain `fetch` either times out resolving or (when the stub hands back only the unreachable AAAA) fails with Bun's `errno: 0` `ConnectionRefused` / `FailedToOpenSocket`. A **direct query to a public resolver (1.1.1.1 / 8.8.8.8) answers in ~10 ms**, and the hosts have a reachable IPv4. The earlier "IPv6 happy-eyeballs" theory was a red herring — the primary fault is DNS resolution at the runner's stub, not IPv6 egress.
+9. **Resilient downloads: normal `fetch` first, public-DNS IPv4 as a failback** — All fetches to MikroTik's `upgrade`/`download` hosts go through `fetchResilient()` (`src/lib/net.ts`), never bare `fetch()`. The intent is narrow: a **plain `fetch` is the path** — dual-stack (happy eyeballs), on par with curl/most tools, and honoring local DNS (`/etc/hosts` pins, VPN/split-horizon, mirror redirects, IPv6-only egress) — and we layer one **failback** beneath it to ride out *DNS misconfiguration somewhere in the environment*, wherever it comes from. We deliberately do **not** invert this (public-DNS+IPv4 first) — that would override local DNS on every machine and could introduce its own failures (e.g. an IPv4-only connect on an IPv6-only network). Normal first keeps us on par with most tools; the failback only adds smarts when the normal path actually breaks.
 
-   Measured on the CI runner: `lookup({family:4})` → `ESERVFAIL` ~9 s; `lookup({all})` → `ESERVFAIL`/`ETIMEOUT` 22–26 s; `resolve4` (resolv.conf) → `ESERVFAIL` 2–22 s; `Resolver([1.1.1.1,8.8.8.8]).resolve4` → **OK ~10 ms**.
+   The trigger is precise: only when the normal `fetch` throws a **connection-class error** (`isConnectionFailure()` — the `ConnectionRefused`/`FailedToOpenSocket`/`ECONNREFUSED`-family codes, or a `TypeError` carrying Bun's `errno: 0` connect-failure marker; *not* aborts or any HTTP response) does `fetchResilient` retry. It resolves the A record by querying public DNS **directly** (a `dns.Resolver` with `setServers([1.1.1.1, 8.8.8.8, 1.0.0.1])`, bounded by a 3 s timeout so a blocked resolver doesn't stall), then connects to the IPv4 literal preserving the `Host` header and TLS SNI so certificate validation still passes. If public DNS also has no answer it surfaces the original failure. HTTP responses (incl. 5xx) and aborts (`AbortError`, e.g. from `AbortSignal.timeout`) pass through unchanged, never retried; a `TypeError` retries only with Bun's `errno: 0` connect-failure marker, so an unrelated `TypeError` (a real bug) surfaces immediately.
 
-   `fetchResilient` resolves the A record by querying public DNS **directly** (a `dns.Resolver` with `setServers([1.1.1.1, 8.8.8.8, 1.0.0.1])`, bounded by a 3 s timeout so a blocked resolver doesn't stall), then connects to the IPv4 literal preserving the `Host` header and TLS SNI so certificate validation still passes. It falls back to a normal `fetch` (system resolver, dual-stack) only when public DNS is unavailable — e.g. a network that blocks public resolvers — so it stays correct off CI. HTTP responses and aborts/timeouts pass through unchanged, never retried. `dns.resolve4`/`getaddrinfo` are deliberately **not** used for the primary path because they inherit the runner's broken stub.
+   *Motivating incident (don't over-fit to it):* the failback was prompted by GitHub-hosted runners whose system resolver returned `ESERVFAIL` for `*.mikrotik.com` — slowly (2–26 s) — via *both* `getaddrinfo` and c-ares-over-`resolv.conf`, so a plain `fetch` either timed out resolving or (when the stub handed back only the unreachable AAAA) failed with Bun's `errno: 0` `ConnectionRefused` / `FailedToOpenSocket`; a direct public-resolver query answered in ~10 ms. That was one observed symptom of a broken resolver, and its deeper root cause is still unknown — so the design is framed as *generic resilience to a misconfigured/transient resolver*, not a CI-specific patch. The earlier "IPv6 happy-eyeballs" theory was a red herring (the symptom was DNS, not IPv6 egress). On-runner probe (2026-06-16): `lookup({family:4})` → `ESERVFAIL` ~9 s; `lookup({all})` → `ESERVFAIL`/`ETIMEOUT` 22–26 s; `resolve4` (resolv.conf) → `ESERVFAIL` 2–22 s; `Resolver([1.1.1.1,8.8.8.8]).resolve4` → OK ~10 ms.
 
-   ⚠️ **Sister-project routing.** A download/version-resolve failure that only appears on CI (slow `ESERVFAIL`, or `errno: 0` from `resolveVersion`) is a **quickchr** concern, not the consuming project's — do not paper over it downstream with `/etc/hosts` pins or IPv6 toggles in the sister repo's workflow. The historical `getent ahostsv4` `/etc/hosts` workaround was both in the wrong layer and non-functional (it hit the same broken stub resolver, returning empty). Covered by `test/unit/net.test.ts`.
+   **Sister-project routing.** Because `fetchResilient` already absorbs a flaky resolver, a download/version-resolve failure should not be papered over downstream with `/etc/hosts` pins or IPv6 toggles in a consuming repo's workflow — fix it (or extend the failback) here in quickchr. The historical `getent ahostsv4` `/etc/hosts` workaround was both in the wrong layer and non-functional (it hit the same broken stub resolver, returning empty). The failback is best-effort, not a guarantee: it recovers connection-class DNS failures, not arbitrary network breakage. Covered by `test/unit/net.test.ts`.
 
 ## Port Layout
 

package/README.md

@@ -331,6 +331,25 @@ console.log(chr.state.bootDiskFormat); // "qcow2"
 console.log(chr.state.extraDisks);     // ["512M", "2G"]
 ```
 
+### Version & channel API
+
+Pick which CHRs are worth booting (handy for CI matrices) without scraping CLI text:
+
+```typescript
+import { resolveActiveChannels, resolveAllVersions } from "@tikoci/quickchr";
+
+await resolveAllVersions();
+// { stable: "7.23.1", "long-term": "7.21.4", testing: "7.23rc4", development: "7.24beta2" }
+
+await resolveActiveChannels();
+// ["stable", "long-term", "development"]
+//   released channels always, plus any pre-release at/ahead of stable
+```
+
+`compareRouterOsVersion` orders pre-release suffixes (`7.24beta2` < `7.24rc1` <
+`7.24` < `7.24.1`). The same map is available from the CLI via
+`quickchr version --json`. See [MANUAL.md](./MANUAL.md) → *Version & channel helpers*.
+
 ### Use in Tests
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/index.ts

@@ -179,7 +179,7 @@ async function main() {
 				await cmdCompletions(args.slice(1));
 				break;
 			case "doctor":
-				await cmdDoctor();
+				await cmdDoctor(args.slice(1));
 				break;
 			case "logs":
 				await cmdLogs(args.slice(1));
@@ -194,7 +194,7 @@ async function main() {
 			case "version":
 			case "--version":
 			case "-v":
-				await cmdVersion();
+				await cmdVersion(args.slice(1));
 				break;
 			case "help":
 			case "--help":
@@ -2429,38 +2429,37 @@ async function cmdCache(argv: string[]) {
 	}
 }
 
-async function cmdDoctor() {
+async function cmdDoctor(argv: string[] = []) {
+	const { flags } = parseFlags(argv);
+	const asJson = flagBool(flags, "json");
 	const { QuickCHR } = await import("../lib/quickchr.ts");
-	const { statusIcon, bold } = await import("./format.ts");
 
 	const result = await QuickCHR.doctor();
 
+	if (asJson) {
+		// Best-effort: cache entries older than current long-term (offline → empty).
+		const staleImages = await findStaleCacheImages();
+		console.log(JSON.stringify({ ok: result.ok, checks: result.checks, staleImages }, null, 2));
+		if (!result.ok) process.exit(1);
+		return;
+	}
+
+	const { statusIcon, bold } = await import("./format.ts");
 	console.log(bold("quickchr doctor\n"));
 	for (const check of result.checks) {
 		console.log(`${statusIcon(check.status)} ${check.label}: ${check.detail}`);
 	}
-
 	console.log();
 
-	// Best-effort: warn about cache entries older than current long-term.
-	try {
-		const { listCacheEntries } = await import("../lib/cache.ts");
-		const { resolveVersion, compareRouterOsVersion } = await import("../lib/versions.ts");
-		const entries = listCacheEntries();
-		if (entries.length > 0) {
-			const longTerm = await resolveVersion("long-term");
-			const stale = entries.filter((e) => {
-				if (e.version === "unknown" || e.inUse) return false;
-				try { return compareRouterOsVersion(e.version, longTerm) < 0; } catch { return false; }
-			});
-			if (stale.length > 0) {
-				console.log(`Note: ${stale.length} cached image(s) older than current long-term (${longTerm}):`);
-				for (const e of stale) console.log(`  - ${e.basename} (${e.version})`);
-				console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
-				console.log();
-			}
-		}
-	} catch { /* offline or no cache — silent */ }
+	// Best-effort, after the checks print so the network lookup never delays them.
+	const staleImages = await findStaleCacheImages();
+	if (staleImages.length > 0) {
+		const longTerm = staleImages[0]?.olderThan;
+		console.log(`Note: ${staleImages.length} cached image(s) older than current long-term (${longTerm}):`);
+		for (const e of staleImages) console.log(`  - ${e.basename} (${e.version})`);
+		console.log("  Hint: 'quickchr cache prune --older-than " + longTerm + "' to evict them.");
+		console.log();
+	}
 
 	if (result.ok) {
 		console.log("All checks passed.");
@@ -2470,12 +2469,50 @@ async function cmdDoctor() {
 	}
 }
 
-async function cmdVersion() {
+interface StaleCacheImage {
+	basename: string;
+	version: string;
+	/** The current long-term version this image is older than. */
+	olderThan: string;
+}
+
+/** Cached images older than the current long-term release. Empty when offline or no cache. */
+async function findStaleCacheImages(): Promise<StaleCacheImage[]> {
+	try {
+		const { listCacheEntries } = await import("../lib/cache.ts");
+		const { resolveVersion, compareRouterOsVersion } = await import("../lib/versions.ts");
+		const entries = listCacheEntries();
+		if (entries.length === 0) return [];
+		const longTerm = await resolveVersion("long-term");
+		return entries
+			.filter((e) => {
+				if (e.version === "unknown" || e.inUse) return false;
+				try { return compareRouterOsVersion(e.version, longTerm) < 0; } catch { return false; }
+			})
+			.map((e) => ({ basename: e.basename, version: e.version, olderThan: longTerm }));
+	} catch {
+		return []; // offline or no cache
+	}
+}
+
+async function cmdVersion(argv: string[] = []) {
+	const { flags } = parseFlags(argv);
+	const asJson = flagBool(flags, "json");
+	const { resolveAllVersions } = await import("../lib/versions.ts");
+
+	if (asJson) {
+		// Stable machine-readable contract: { channel: version }. Offline → {}.
+		let versions: Record<string, string> = {};
+		try {
+			versions = await resolveAllVersions();
+		} catch { /* offline — emit empty object */ }
+		console.log(JSON.stringify(versions));
+		return;
+	}
+
 	const pkg = await import("../../package.json");
 	console.log(`quickchr ${pkg.version}`);
-
 	try {
-		const { resolveAllVersions } = await import("../lib/versions.ts");
 		const versions = await resolveAllVersions();
 		console.log("\nLatest RouterOS versions:");
 		for (const [channel, version] of Object.entries(versions)) {
@@ -2522,8 +2559,8 @@ Commands:
   cache [list|prune|clear] Manage cached CHR images
   completions             Manage shell completions (Tab completion)
   logs <name>             Tail the QEMU log for an instance
-  doctor                  Check prerequisites
-  version                 Show version info
+  doctor [--json]         Check prerequisites
+  version [--json]        Show version info
   help [command]          Show help
 
 Environment:
@@ -2707,11 +2744,14 @@ Print environment variables for subprocesses that connect to a running CHR.
   --json      Output the env map as JSON instead of KEY=value lines.`);
 			break;
 		case "doctor":
-			console.log(`quickchr doctor
+			console.log(`quickchr doctor [--json]
 
 Check system prerequisites: QEMU binaries, firmware, acceleration,
 sshpass (for package upload), qemu-img (for disk operations), data directories,
-and cached images. Also reports the current shell and completion install status.`);
+and cached images. Also reports the current shell and completion install status.
+
+Options:
+  --json      Emit { ok, checks, staleImages } as JSON. Exit code still reflects ok.`);
 			break;
 		case "logs":
 			console.log(`quickchr logs <name> [options]
@@ -2842,6 +2882,16 @@ Credential resolution order (highest priority first):
               Omit to see a list of instances.
   --all       Remove all instances.`);
 			break;
+		case "version":
+			console.log(`quickchr version [--json]
+
+Show the quickchr version and the latest RouterOS version per channel.
+
+Options:
+  --json      Emit the latest RouterOS versions as a { channel: version } object
+              (stable, long-term, testing, development). Offline emits {}.
+              Omits the quickchr version line — query package.json for that.`);
+			break;
 		case "networks":
 		case "net":
 			showNetworksHelp();

package/src/index.ts

@@ -130,3 +130,20 @@ export { parseForwardSpec } from "./lib/forward-spec.ts";
 // Logging
 export { createLogger } from "./lib/log.ts";
 export type { ProgressLogger } from "./lib/log.ts";
+
+// Version & channel utilities
+export { CHANNELS } from "./lib/types.ts";
+export {
+	resolveVersion,
+	resolveAllVersions,
+	isValidVersion,
+	parseVersionParts,
+	compareRouterOsVersion,
+	isProvisioningSupportedVersion,
+	channelMaturity,
+	classifyChannels,
+	selectActiveChannels,
+	resolveChannelStatuses,
+	resolveActiveChannels,
+} from "./lib/versions.ts";
+export type { ChannelMaturity, ChannelStatus } from "./lib/versions.ts";

package/src/lib/net.ts

@@ -1,22 +1,30 @@
 /**
  * Resilient HTTP fetch for MikroTik's download hosts.
  *
- * On GitHub-hosted CI runners the system DNS resolver returns `ESERVFAIL`
- * (slowly — 2 to 26 s) for `upgrade.mikrotik.com` / `download.mikrotik.com` via
- * both `getaddrinfo` and c-ares-over-resolv.conf, so a plain `fetch` either
- * times out or (when the stub hands back only the unreachable AAAA) fails with
- * Bun's `errno: 0` ConnectionRefused / FailedToOpenSocket. A direct query to a
- * public resolver answers in ~10 ms, and the hosts are dual-stack with a
- * reachable IPv4. quickchr is expected to run unattended in CI, so it resolves
- * these hosts itself rather than trusting the runner's broken resolver.
+ * Primary path: a plain `fetch` on the system resolver. This is tried first,
+ * accepting the latency cost when it fails — usually small, but up to the
+ * resolver's own failure time (the broken CI stub below took 2–26 s). It is
+ * dual-stack (happy eyeballs) and on par with curl/most tools, and it honors
+ * local DNS configuration —
+ * `/etc/hosts` pins, VPN/split-horizon DNS, mirror redirects, IPv6-only egress —
+ * which a forced public-DNS+IPv4 path would silently override and could itself
+ * turn into a fresh failure mode. So we stay "normal" unless the normal path
+ * actually breaks.
  *
- * Strategy: resolve the A record by querying a public DNS server directly
- * (bypassing the host's resolv.conf), then connect to the IPv4 literal,
- * preserving the `Host` header and TLS SNI so certificate validation still
- * passes. Fall back to a normal `fetch` (system resolver, dual-stack) when the
- * public-DNS path is unavailable — e.g. a network that blocks public resolvers
- * — so this stays correct off CI. HTTP responses and aborts/timeouts pass
- * through unchanged; they are never retried.
+ * Fallback: some environments (notably GitHub-hosted CI runners, observed
+ * 2026-06) have a broken/slow stub resolver that returns `ESERVFAIL` — slowly,
+ * 2 to 26 s — for `upgrade.mikrotik.com` / `download.mikrotik.com`, or hands back
+ * only an unreachable AAAA, surfacing as Bun's `errno: 0` ConnectionRefused /
+ * FailedToOpenSocket. When the normal fetch fails *that* way (a connection-class
+ * error), we retry by resolving the A record against a public DNS server
+ * directly (~10 ms), bypassing the host's resolv.conf, and connecting to the
+ * IPv4 literal with the `Host` header and TLS SNI preserved so certificate
+ * validation still passes.
+ *
+ * Only connection-class failures trigger the fallback; HTTP responses (incl.
+ * 5xx) and aborts (`AbortError`, e.g. from `AbortSignal.timeout`) pass through
+ * unchanged and are never retried. (A low-level connect `ETIMEDOUT` is a
+ * connection-class failure and *is* retried — see `isConnectionFailure`.)
  */
 
 import { promises as dns } from "node:dns";
@@ -28,13 +36,14 @@ const DNS_TIMEOUT_MS = 3000;
  * True for the connection-class failures raised when a socket cannot be opened
  * (e.g. IPv4 blocked on an IPv6-only network, or Bun's `errno: 0`
  * ConnectionRefused / FailedToOpenSocket against an unreachable address), plus
- * the standard connect errors. Excludes aborts/timeouts and HTTP-level outcomes
- * (those carry a Response and never throw here). Used to decide whether to fall
- * back from the IPv4 attempt to a normal dual-stack fetch.
+ * the standard connect errors. Excludes `AbortError` (aborts/`AbortSignal`
+ * timeouts) and HTTP-level outcomes (those carry a Response and never throw
+ * here). Used to decide whether to fall back from the normal fetch to the
+ * public-DNS IPv4 attempt.
  */
 export function isConnectionFailure(err: unknown): boolean {
 	if (!err || typeof err !== "object") return false;
-	const e = err as { name?: string; code?: string; cause?: { code?: string } };
+	const e = err as { name?: string; code?: string; errno?: number; cause?: { code?: string } };
 	if (e.name === "AbortError") return false;
 	const code = e.code ?? e.cause?.code;
 	if (
@@ -49,10 +58,12 @@ export function isConnectionFailure(err: unknown): boolean {
 	) {
 		return true;
 	}
-	// Bun wraps low-level connect failures as a bare TypeError ("Unable to
-	// connect…"). Treat those as retriable too; a wrong guess only costs one
-	// normal fetch, which then surfaces the real error if it also fails.
-	return e.name === "TypeError";
+	// Bun has also surfaced low-level connect failures as a `TypeError` carrying
+	// `errno: 0` (its connect-failure marker; the typed `code`s above catch the
+	// current form — Bun 1.3 throws an `Error` with `code: "ConnectionRefused"`,
+	// confirmed by probe). Gate on that marker so an unrelated `TypeError` (a real
+	// bug) surfaces immediately instead of triggering a pointless DNS retry.
+	return e.name === "TypeError" && e.errno === 0;
 }
 
 /** Rewrite a URL to target an explicit IPv4 literal, preserving port/path/query. */
@@ -64,10 +75,11 @@ export function toIpv4Url(url: string, address: string): string {
 
 /**
  * Resolve a host's A record via public DNS servers directly, bypassing the
- * host's resolv.conf (which is broken for these names on CI runners). Returns
- * undefined — never throws — when public DNS is unreachable or has no answer,
- * so the caller can fall back to a normal fetch. Bounded by DNS_TIMEOUT_MS so a
- * blocked resolver does not stall the request.
+ * host's resolv.conf. Used only as the fallback path, after a normal fetch has
+ * already failed with a connection-class error (e.g. a broken stub resolver on
+ * CI runners). Returns undefined — never throws — when public DNS is unreachable
+ * or has no answer, so the caller can surface the original failure. Bounded by
+ * DNS_TIMEOUT_MS so a blocked resolver does not stall the request.
  */
 async function resolveIpv4(host: string): Promise<string | undefined> {
 	const resolver = new dns.Resolver();
@@ -88,6 +100,12 @@ async function resolveIpv4(host: string): Promise<string | undefined> {
 	}
 }
 
+/**
+ * Fetch `url` but connect to an explicit IPv4 `address`, keeping HTTP and TLS
+ * pointed at the original host: the `Host` header and TLS SNI (`serverName`) are
+ * set to the URL's hostname so virtual-hosting routing and certificate
+ * validation still pass against the IP literal. The failback transport.
+ */
 async function fetchOverIpv4(
 	url: string,
 	address: string,
@@ -99,25 +117,31 @@ async function fetchOverIpv4(
 	return fetch(toIpv4Url(url, address), {
 		...init,
 		headers,
-		tls: { serverName: host, ...init?.tls },
+		// serverName last: it must pin to the real host for cert validation against
+		// the IP literal — a caller-provided init.tls.serverName must not override it.
+		tls: { ...init?.tls, serverName: host },
 	});
 }
 
 /**
- * `fetch()` that resolves dual-stack hosts via public DNS and connects over
- * IPv4, so it survives a broken/slow system resolver (e.g. GitHub-hosted CI
- * runners). Falls back to a normal `fetch` when public DNS is unavailable.
- * Behaves like `fetch` for HTTP responses and aborts.
+ * `fetch()` that tries the system resolver first (a normal dual-stack fetch)
+ * and, only when that fails with a connection-class error, falls back to
+ * resolving via public DNS and connecting over the IPv4 literal — so it survives
+ * a broken/slow system resolver (e.g. GitHub-hosted CI runners) without
+ * overriding local DNS in the common case. Behaves like `fetch` for HTTP
+ * responses and aborts.
  */
 export async function fetchResilient(url: string, init?: BunFetchRequestInit): Promise<Response> {
-	const address = await resolveIpv4(new URL(url).hostname);
-	if (address) {
-		try {
-			return await fetchOverIpv4(url, address, init);
-		} catch (err) {
-			if (!isConnectionFailure(err)) throw err;
-			// IPv4 unreachable (e.g. IPv6-only egress) — fall through to a normal fetch.
-		}
+	try {
+		return await fetch(url, init);
+	} catch (err) {
+		// Only a connection-class failure (e.g. a broken/slow stub resolver, or an
+		// unreachable AAAA) is worth the public-DNS workaround. Aborts (AbortError)
+		// and everything else propagate unchanged.
+		if (!isConnectionFailure(err)) throw err;
+		const address = await resolveIpv4(new URL(url).hostname);
+		// Public DNS can't help (unreachable / no answer) — surface the original failure.
+		if (address === undefined) throw err;
+		return fetchOverIpv4(url, address, init);
 	}
-	return fetch(url, init);
 }

package/src/lib/quickchr.ts

@@ -1169,7 +1169,7 @@ export class QuickCHR {
 		// Resolve version
 		let version: string;
 		if (opts.version) {
-			if ((CHANNELS as string[]).includes(opts.version)) {
+			if ((CHANNELS as readonly string[]).includes(opts.version)) {
 				logger.warn(
 					`'${opts.version}' is a channel name, not a version — passed as 'version' but resolved as a channel. Use 'channel: "${opts.version}"' instead to make this explicit.`,
 				);

package/src/lib/types.ts

@@ -7,7 +7,8 @@ import type { ProgressLogger } from "./log.ts";
 // --- Version & Architecture ---
 
 export type Channel = "stable" | "long-term" | "testing" | "development";
-export const CHANNELS: Channel[] = ["stable", "long-term", "testing", "development"];
+/** Canonical channel order. Frozen so neither library code nor consumers can mutate it. */
+export const CHANNELS: readonly Channel[] = Object.freeze(["stable", "long-term", "testing", "development"] as Channel[]);
 
 export type Arch = "arm64" | "x86";
 export const ARCHES: Arch[] = ["arm64", "x86"];

package/src/lib/versions.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Arch, Channel } from "./types.ts";
-import { QuickCHRError } from "./types.ts";
+import { CHANNELS, QuickCHRError } from "./types.ts";
 import { fetchResilient } from "./net.ts";
 
 const UPGRADE_BASE = "https://upgrade.mikrotik.com/routeros/NEWESTa7";
@@ -92,9 +92,8 @@ export async function resolveVersion(channel: Channel): Promise<string> {
 
 /** Fetch latest versions for all channels in parallel. */
 export async function resolveAllVersions(): Promise<Record<Channel, string>> {
-	const channels: Channel[] = ["stable", "long-term", "testing", "development"];
 	const results = await Promise.all(
-		channels.map(async (ch) => [ch, await resolveVersion(ch)] as const),
+		CHANNELS.map(async (ch) => [ch, await resolveVersion(ch)] as const),
 	);
 	return Object.fromEntries(results) as Record<Channel, string>;
 }
@@ -104,27 +103,58 @@ export function isValidVersion(version: string): boolean {
 	return /^\d+\.\d+(\.\d+)?(beta\d+|rc\d+)?$/.test(version);
 }
 
-/** Parse a RouterOS version into numeric parts. beta/rc suffixes are ignored for ordering. */
-export function parseVersionParts(version: string): [number, number, number] {
-	const match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?(?:beta\d+|rc\d+)?$/);
+/**
+ * RouterOS pre-release ordering rank. For a given X.Y, a beta is older than an rc,
+ * which is older than the final release: beta < rc < release.
+ */
+const STAGE_RANK = { beta: 0, rc: 1, release: 2 } as const;
+
+interface ParsedVersion {
+	major: number;
+	minor: number;
+	patch: number;
+	/** Maturity rank within X.Y: beta=0 < rc=1 < release=2. */
+	stage: (typeof STAGE_RANK)[keyof typeof STAGE_RANK];
+	/** The N in betaN/rcN (0 for release builds). */
+	stageNum: number;
+}
+
+/** Parse a RouterOS version into numeric parts plus pre-release stage. */
+function parseVersion(version: string): ParsedVersion {
+	const match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?(?:(beta|rc)(\d+))?$/);
 	if (!match) {
 		throw new QuickCHRError("INVALID_VERSION", `Invalid version: ${version}`);
 	}
 
-	const major = Number.parseInt(match[1] ?? "0", 10);
-	const minor = Number.parseInt(match[2] ?? "0", 10);
-	const patch = Number.parseInt(match[3] ?? "0", 10);
+	const stageName = match[4] as "beta" | "rc" | undefined;
+	return {
+		major: Number.parseInt(match[1] ?? "0", 10),
+		minor: Number.parseInt(match[2] ?? "0", 10),
+		patch: Number.parseInt(match[3] ?? "0", 10),
+		stage: stageName ? STAGE_RANK[stageName] : STAGE_RANK.release,
+		stageNum: match[5] ? Number.parseInt(match[5], 10) : 0,
+	};
+}
+
+/** Parse a RouterOS version into numeric parts. beta/rc suffixes are ignored. */
+export function parseVersionParts(version: string): [number, number, number] {
+	const { major, minor, patch } = parseVersion(version);
 	return [major, minor, patch];
 }
 
-/** Compare two RouterOS versions semantically. */
+/**
+ * Compare two RouterOS versions semantically, including pre-release suffixes:
+ * `7.24beta2` < `7.24rc1` < `7.24` < `7.24.1`. Returns <0, 0, or >0.
+ */
 export function compareRouterOsVersion(left: string, right: string): number {
-	const [leftMajor, leftMinor, leftPatch] = parseVersionParts(left);
-	const [rightMajor, rightMinor, rightPatch] = parseVersionParts(right);
+	const a = parseVersion(left);
+	const b = parseVersion(right);
 
-	if (leftMajor !== rightMajor) return leftMajor - rightMajor;
-	if (leftMinor !== rightMinor) return leftMinor - rightMinor;
-	return leftPatch - rightPatch;
+	if (a.major !== b.major) return a.major - b.major;
+	if (a.minor !== b.minor) return a.minor - b.minor;
+	if (a.patch !== b.patch) return a.patch - b.patch;
+	if (a.stage !== b.stage) return a.stage - b.stage;
+	return a.stageNum - b.stageNum;
 }
 
 /** True if RouterOS version is supported for quickchr provisioning mutations. */
@@ -180,3 +210,65 @@ export function generateMachineName(
 	}
 	return `${base}-${n}`;
 }
+
+// --- Channel recency ---
+
+/** Channels that ship as finished releases vs. moving pre-release builds. */
+const RELEASED_CHANNELS: readonly Channel[] = ["stable", "long-term"];
+
+export type ChannelMaturity = "released" | "prerelease";
+
+/** Classify a channel as a finished release line or a pre-release line. */
+export function channelMaturity(channel: Channel): ChannelMaturity {
+	return RELEASED_CHANNELS.includes(channel) ? "released" : "prerelease";
+}
+
+export interface ChannelStatus {
+	channel: Channel;
+	/** Resolved version for the channel, e.g. "7.24beta2". */
+	version: string;
+	maturity: ChannelMaturity;
+	/** True if this channel's version is at or ahead of the current stable release. */
+	aheadOfStable: boolean;
+}
+
+/**
+ * Classify each channel by current recency (pure — no network).
+ * `aheadOfStable` is always measured against the `stable` version in `versions`.
+ */
+export function classifyChannels(versions: Record<Channel, string>): ChannelStatus[] {
+	const stableVersion = versions.stable;
+	return CHANNELS.map((channel) => ({
+		channel,
+		version: versions[channel],
+		maturity: channelMaturity(channel),
+		aheadOfStable: compareRouterOsVersion(versions[channel], stableVersion) >= 0,
+	}));
+}
+
+/**
+ * Select the channels currently worth booting (pure — no network): every released
+ * channel unconditionally, plus any pre-release channel at or ahead of the reference
+ * channel's version (default reference: `stable`). This answers "what's worth booting,"
+ * never "what must pass" — gate policy stays with the consumer.
+ */
+export function selectActiveChannels(
+	versions: Record<Channel, string>,
+	opts: { aheadOf?: Channel } = {},
+): Channel[] {
+	const referenceVersion = versions[opts.aheadOf ?? "stable"];
+	return CHANNELS.filter((channel) => {
+		if (channelMaturity(channel) === "released") return true;
+		return compareRouterOsVersion(versions[channel], referenceVersion) >= 0;
+	});
+}
+
+/** Fetch all channel versions and classify each by current recency. */
+export async function resolveChannelStatuses(): Promise<ChannelStatus[]> {
+	return classifyChannels(await resolveAllVersions());
+}
+
+/** Fetch all channel versions and return the channels currently worth booting. */
+export async function resolveActiveChannels(opts: { aheadOf?: Channel } = {}): Promise<Channel[]> {
+	return selectActiveChannels(await resolveAllVersions(), opts);
+}