@tikoci/quickchr 0.4.7 → 0.4.8

package/src/lib/cache-api.ts

@@ -0,0 +1,146 @@
+/** Public cache operations for CI consumers and the quickchr CLI. */
+
+import { join } from "node:path";
+import { ensureCachedImage, isUsableCachedImage } from "./images.ts";
+import type { ProgressLogger } from "./log.ts";
+import { getCacheDir } from "./state.ts";
+import { ARCHES, CHANNELS, QuickCHRError, type Arch, type Channel } from "./types.ts";
+import { chrImageBasename, isValidVersion, resolveVersion } from "./versions.ts";
+
+export const CACHE_VERSION_UNRESOLVED = "unresolved";
+const CACHE_VERSION_MAX_LENGTH = 32;
+
+export interface CacheTargetOptions {
+	/** Resolve this RouterOS channel. Mutually exclusive with `version`. */
+	channel?: Channel;
+	/** Use this concrete RouterOS version without a network resolution request. */
+	version?: string;
+	/** Override the cache directory. Defaults to quickchr's platform-correct cache. */
+	cacheDir?: string;
+	/** CHR architecture. `auto` and omission select the Bun process architecture. */
+	arch?: Arch | "auto";
+}
+
+export interface CacheKeyResult {
+	dir: string;
+	/** Concrete RouterOS version, or `unresolved` when channel resolution is offline. */
+	version: string;
+	arch: Arch;
+}
+
+export interface CacheAddOptions extends CacheTargetOptions {
+	logger?: ProgressLogger;
+}
+
+export interface CacheAddResult extends CacheKeyResult {
+	path: string;
+	cacheHit: boolean;
+}
+
+export type CacheVersionResolver = (channel: Channel) => Promise<string>;
+
+function validateTarget(options: CacheTargetOptions): { channel?: Channel; version?: string } {
+	if (options.channel !== undefined && options.version !== undefined) {
+		throw new QuickCHRError("INVALID_VERSION", "Choose either a RouterOS channel or a concrete version, not both");
+	}
+	if (options.channel !== undefined && !(CHANNELS as readonly string[]).includes(options.channel)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Invalid RouterOS channel "${options.channel}" — expected one of ${CHANNELS.join(", ")}`,
+		);
+	}
+	if (options.version !== undefined && !isValidVersion(options.version)) {
+		throw new QuickCHRError("INVALID_VERSION", `Invalid RouterOS version: ${options.version}`);
+	}
+	return { channel: options.channel, version: options.version };
+}
+
+async function concreteVersion(
+	options: CacheTargetOptions,
+	resolver: CacheVersionResolver,
+): Promise<{ channel?: Channel; version: string }> {
+	const target = validateTarget(options);
+	if (target.version !== undefined) return { version: target.version };
+	const channel = target.channel ?? "stable";
+	const version = await resolver(channel);
+	if (!isValidVersion(version)) {
+		throw new QuickCHRError(
+			"INVALID_VERSION",
+			`Unexpected version "${version}" resolved for channel "${channel}"`,
+		);
+	}
+	return { channel, version };
+}
+
+function concreteArch(arch: Arch | "auto" | undefined): Arch {
+	if (arch === undefined || arch === "auto") return process.arch === "arm64" ? "arm64" : "x86";
+	if (!(ARCHES as readonly string[]).includes(arch)) {
+		throw new QuickCHRError("INVALID_ARCH", `Invalid architecture "${arch}" — expected one of ${ARCHES.join(", ")}, auto`);
+	}
+	return arch;
+}
+
+/**
+ * Return quickchr's cache directory and the concrete version for a CI key.
+ *
+ * An explicit version is validated and returned without a network call. A
+ * channel resolution failure degrades to the stable `unresolved` sentinel so
+ * cache lookup cannot make an otherwise useful offline job fail.
+ */
+export async function cacheKey(
+	options: CacheTargetOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheKeyResult> {
+	const target = validateTarget(options);
+	const dir = options.cacheDir ?? getCacheDir();
+	const arch = concreteArch(options.arch);
+	if (target.version !== undefined) {
+		return {
+			dir,
+			version: target.version.length <= CACHE_VERSION_MAX_LENGTH ? target.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	}
+	try {
+		const resolved = await concreteVersion(options, resolver);
+		return {
+			dir,
+			version: resolved.version.length <= CACHE_VERSION_MAX_LENGTH ? resolved.version : CACHE_VERSION_UNRESOLVED,
+			arch,
+		};
+	} catch (error) {
+		if (error instanceof QuickCHRError && error.code === "DOWNLOAD_FAILED") {
+			return { dir, version: CACHE_VERSION_UNRESOLVED, arch };
+		}
+		throw error;
+	}
+}
+
+/** Resolve and cache one CHR image without creating or booting a machine. */
+export async function cacheAdd(
+	options: CacheAddOptions = {},
+	resolver: CacheVersionResolver = resolveVersion,
+): Promise<CacheAddResult> {
+	const resolved = await concreteVersion(options, resolver);
+	if (resolved.version.length > CACHE_VERSION_MAX_LENGTH) {
+		throw new QuickCHRError("INVALID_VERSION", `RouterOS version is too long: ${resolved.version}`);
+	}
+	const arch = concreteArch(options.arch);
+	const dir = options.cacheDir ?? getCacheDir();
+	const expectedPath = join(dir, `${chrImageBasename(resolved.version, arch)}.img`);
+	const cacheHit = await isUsableCachedImage(expectedPath);
+
+	try {
+		const path = await ensureCachedImage(resolved.version, arch, dir, options.logger);
+		return { dir, version: resolved.version, arch, path, cacheHit };
+	} catch (error) {
+		if (resolved.channel && error instanceof QuickCHRError) {
+			throw new QuickCHRError(
+				error.code,
+				`Failed to cache channel "${resolved.channel}" -> ${resolved.version} (${arch}): ${error.message}`,
+				error.installHint,
+			);
+		}
+		throw error;
+	}
+}

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help"
+    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -352,6 +352,10 @@ _quickchr() {
             local opts="--install --uninstall --status --dry-run --shell"
             COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
             ;;
+        cache)
+            local opts="add key list prune clear"
+            COMPREPLY=( $(compgen -W "${D}opts" -- "${D}cur") )
+            ;;
         help)
             COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
             ;;
@@ -401,6 +405,7 @@ _quickchr() {
                 'snap:Manage snapshots (alias)'
                 'networks:Network discovery and socket management'
                 'net:Network discovery (alias)'
+                'cache:Prefetch and manage downloaded CHR images'
                 'doctor:Check prerequisites'
                 'settings:Manage global quickchr settings'
                 'setup:Interactive setup wizard'
@@ -434,8 +439,12 @@ _quickchr() {
                     )
                     _describe 'option' opts
                     ;;
+                cache)
+                    local subcommands=(add key list prune clear)
+                    _describe 'cache subcommand' subcommands
+                    ;;
                 help)
-                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor settings setup completions version)
+                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks cache doctor settings setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -451,7 +460,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor settings setup completions version help
+set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net cache doctor settings setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -489,6 +498,8 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "snapshot snap" -d "Manage snapshots"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "networks net" -d "Network discovery and socket management"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "cache"       -d "Prefetch and manage downloaded CHR images"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "doctor"      -d "Check prerequisites"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -518,5 +529,8 @@ complete -c quickchr -n "__fish_seen_subcommand_from completions" -l uninstall -
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l status    -d "Show install status"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l dry-run   -d "Show what would happen"
 complete -c quickchr -n "__fish_seen_subcommand_from completions" -l shell     -d "Specify shell" -a "bash zsh fish"
+
+# cache subcommands
+complete -c quickchr -n "__fish_seen_subcommand_from cache" -a "add key list prune clear" -d "cache subcommand"
 `;
 }

package/src/lib/images.ts

@@ -2,7 +2,7 @@
  * Image download, ZIP extraction, and cache management.
  */
 
-import { existsSync, copyFileSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { existsSync, copyFileSync, mkdtempSync, readdirSync, renameSync, rmSync, unlinkSync } from "node:fs";
 import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -20,6 +20,37 @@ function finalizeExtractedImage(zipPath: string, imgPath: string): string {
 	return imgPath;
 }
 
+/**
+ * Check that a cached raw image has a complete DOS partition table.
+ *
+ * RouterOS CHR images for both supported architectures use a DOS partition
+ * table. Checking its signature and partition extents catches empty and
+ * truncated files while avoiding a version-specific image-size assumption.
+ */
+export async function isUsableCachedImage(imgPath: string): Promise<boolean> {
+	const file = Bun.file(imgPath);
+	if (!(await file.exists()) || file.size < 512) return false;
+
+	try {
+		const sector = new Uint8Array(await file.slice(0, 512).arrayBuffer());
+		if (sector[510] !== 0x55 || sector[511] !== 0xaa) return false;
+
+		let hasPartition = false;
+		for (let offset = 446; offset < 510; offset += 16) {
+			const start = new DataView(sector.buffer, sector.byteOffset + offset + 8, 8);
+			const firstSector = start.getUint32(0, true);
+			const sectorCount = start.getUint32(4, true);
+			if (sectorCount === 0) continue;
+			hasPartition = true;
+			const end = (firstSector + sectorCount) * 512;
+			if (!Number.isSafeInteger(end) || end > file.size) return false;
+		}
+		return hasPartition;
+	} catch {
+		return false;
+	}
+}
+
 /** Download a CHR image ZIP if not already cached. Returns path to the ZIP. */
 export async function downloadImage(
 	version: string,
@@ -58,39 +89,38 @@ export async function extractImage(
 	const imgName = basename(zipPath, ".zip");
 	const imgPath = join(cache, imgName);
 
-	if (existsSync(imgPath)) {
+	if (await isUsableCachedImage(imgPath)) {
 		return finalizeExtractedImage(zipPath, imgPath);
 	}
+	if (existsSync(imgPath)) unlinkSync(imgPath);
 
 	const log = logger ?? createLogger();
 	log.status(`Extracting: ${basename(zipPath)}`);
 
-	extractZip(zipPath, cache);
+	const tempDir = mkdtempSync(join(cache, ".quickchr-image-"));
+	try {
+		extractZip(zipPath, tempDir);
 
-	// MikroTik x86 ZIPs contain chr-X.Y.Z.img (no arch suffix).
-	// Our ZIP is named chr-X.Y.Z.img.zip (without -x86 for x86). Check if we need to
-	// find the extracted file.
-	if (!existsSync(imgPath)) {
-		const files = readdirSync(cache).filter(
-			(f) => f.endsWith(".img") && f.startsWith("chr-"),
+		// MikroTik arm64 ZIPs may contain chr-X.Y.Z.img without the arch suffix.
+		const files = readdirSync(tempDir).filter((file) => file.endsWith(".img") && file.startsWith("chr-"));
+		const base = basename(zipPath, ".img.zip");
+		const expected = files.find(
+			(file) => file === `${base}.img` || file.replace("-arm64", "") === `${base.replace("-arm64", "")}.img`,
 		);
-		// Find the one that was just extracted (matching version)
-		const expected = files.find((f) => {
-			const base = basename(zipPath, ".img.zip");
-			// chr-7.22.1.img matches chr-7.22.1.img.zip
-			return f === base + ".img" || f.replace("-arm64", "") === base.replace("-arm64", "") + ".img";
-		});
-		if (expected) {
-			const extractedPath = join(cache, expected);
-			if (extractedPath !== imgPath) {
-				renameSync(extractedPath, imgPath);
-			}
-		} else {
+		if (!expected) {
 			throw new QuickCHRError(
 				"PROCESS_FAILED",
 				`Expected ${imgPath} after unzip, but not found. Files: ${files.join(", ")}`,
 			);
 		}
+
+		const extractedPath = join(tempDir, expected);
+		if (!(await isUsableCachedImage(extractedPath))) {
+			throw new QuickCHRError("PROCESS_FAILED", `Extracted CHR image is incomplete or invalid: ${expected}`);
+		}
+		renameSync(extractedPath, imgPath);
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
 	}
 
 	return finalizeExtractedImage(zipPath, imgPath);
@@ -105,11 +135,12 @@ export async function ensureCachedImage(
 ): Promise<string> {
 	const cache = cacheDir ?? getCacheDir();
 	const imgPath = join(cache, `${chrImageBasename(version, arch)}.img`);
-	if (existsSync(imgPath)) {
+	if (await isUsableCachedImage(imgPath)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached image: ${chrImageBasename(version, arch)}`);
 		return imgPath;
 	}
+	if (existsSync(imgPath)) unlinkSync(imgPath);
 	assertSufficientQuickchrStorage(`cache CHR ${version} (${arch})`);
 	const zipPath = await downloadImage(version, arch, cacheDir, logger);
 	const extractedImgPath = await extractImage(zipPath, cacheDir, logger);

package/src/lib/names.ts

@@ -0,0 +1,72 @@
+/**
+ * Resource-name validation — machine names and named-socket names.
+ *
+ * Both become a path segment under the data dir (`machines/<name>/`,
+ * `networks/<name>.json`), so a name is not free text: it has to be safe to join
+ * onto a path and safe to type back into a command. A name starting with `-`
+ * also reads as a flag everywhere it is echoed (`quickchr remove --help`), which
+ * is how `networks sockets create --help` persisted a socket called `--help` (#156).
+ */
+
+import { QuickCHRError } from "./types.ts";
+
+/** Letters, digits, dot, underscore, hyphen — the charset already produced by
+ *  `generateMachineName()` (e.g. `7.24.4-x86-1`), minus anything a shell or a
+ *  path would reinterpret. */
+const VALID_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const MAX_NAME_LENGTH = 64;
+
+/** Throw `INVALID_NAME` unless `name` is safe as both a path segment and a CLI argument.
+ *  `kind` names the resource in the message ("machine", "named socket"). */
+export function assertValidResourceName(name: string, kind: string): void {
+	const reject = (why: string) => {
+		throw new QuickCHRError("INVALID_NAME", `Invalid ${kind} name "${name}" — ${why}`);
+	};
+
+	if (name.length === 0) reject("names cannot be empty");
+	if (name.startsWith("-")) reject(`names cannot start with "-" (it would be read as a flag)`);
+	if (name.length > MAX_NAME_LENGTH) reject(`names are limited to ${MAX_NAME_LENGTH} characters`);
+	if (!VALID_NAME.test(name)) {
+		reject("names may contain only letters, digits, dot, underscore and hyphen, and must start with a letter or digit");
+	}
+}
+
+/** The weaker rule that applies to a name being *used*, not created.
+ *
+ *  `assertValidResourceName()` cannot guard a lookup or a delete: machines created
+ *  under the older, looser rules have to stay addressable. But a name still becomes a
+ *  path segment, and `join(machinesDir, name)` happily normalizes `..` into the data
+ *  directory itself — so `removeOrphan("..")` would `rmSync` every machine, the cache
+ *  and the socket registry. This is the minimum that stops that while passing every
+ *  name a real machine can have. */
+export function isPathSafeName(name: string): boolean {
+	if (name.length === 0) return false;
+	if (name === "." || name === "..") return false;
+	if (name.includes("/") || name.includes("\0")) return false;
+	// `\` is a path separator on Windows and an ordinary filename character on POSIX.
+	// Rejecting it everywhere would strand a machine named `lab\old` under the older,
+	// looser creation rules: `list` still shows it, so `remove` has to still clear it.
+	if (process.platform === "win32" && name.includes("\\")) return false;
+	return true;
+}
+
+/** Throwing form of {@link isPathSafeName}, for the paths that delete. */
+export function assertPathSafeName(name: string, kind: string): void {
+	if (!isPathSafeName(name)) {
+		throw new QuickCHRError(
+			"INVALID_NAME",
+			`Invalid ${kind} name ${JSON.stringify(name)} — a name cannot be empty, "." or "..", or contain a path separator`,
+		);
+	}
+}
+
+/** Non-throwing form, for callers that want to branch rather than fail. */
+export function isValidResourceName(name: string): boolean {
+	try {
+		assertValidResourceName(name, "resource");
+		return true;
+	} catch {
+		return false;
+	}
+}