@tikoci/quickchr 0.2.0 → 0.3.0

package/src/lib/forward-spec.ts

@@ -0,0 +1,92 @@
+/**
+ * Parse a CLI `--forward` spec into a `PortMapping`.
+ *
+ * Grammar: `name[:host[:guest]][/proto]`
+ *
+ * - `name` — required. If it matches a key/alias in `WELL_KNOWN_GUEST_PORTS`,
+ *   missing `guest` and `proto` are filled from the registry. The original
+ *   spelling (alias or canonical) is preserved as `name` so users see the
+ *   label they typed in `quickchr list` / state.
+ * - `host` — optional. When omitted (or 0), `buildPortMappings` auto-allocates
+ *   a host port from the machine's port block.
+ * - `guest` — optional only when `name` resolves in the registry; otherwise
+ *   required.
+ * - `proto` — optional. Defaults from registry, else `tcp`. Must be `tcp` or
+ *   `udp`.
+ *
+ * Throws `QuickCHRError("INVALID_FORWARD_SPEC", ...)` with the original spec
+ * embedded in the message on any parse error.
+ */
+
+import { lookupGuestPort } from "./guest-ports.ts";
+import { type PortMapping, QuickCHRError } from "./types.ts";
+
+function fail(spec: string, reason: string): never {
+	throw new QuickCHRError(
+		"INVALID_FORWARD_SPEC",
+		`Invalid --forward spec "${spec}": ${reason}`,
+	);
+}
+
+function parsePort(spec: string, raw: string, label: string, allowZero: boolean): number {
+	if (!/^\d+$/.test(raw)) {
+		fail(spec, `${label} port "${raw}" is not a number`);
+	}
+	const n = Number(raw);
+	const min = allowZero ? 0 : 1;
+	if (n < min || n > 65535) {
+		fail(spec, `${label} port ${n} out of range (${min}-65535)`);
+	}
+	return n;
+}
+
+export function parseForwardSpec(spec: string): PortMapping {
+	if (!spec?.trim()) {
+		throw new QuickCHRError(
+			"INVALID_FORWARD_SPEC",
+			"Empty --forward spec",
+		);
+	}
+	const trimmed = spec.trim();
+
+	// Split off /proto suffix
+	let body = trimmed;
+	let protoStr: string | undefined;
+	const slash = trimmed.lastIndexOf("/");
+	if (slash !== -1) {
+		body = trimmed.slice(0, slash);
+		protoStr = trimmed.slice(slash + 1).toLowerCase();
+		if (protoStr !== "tcp" && protoStr !== "udp") {
+			fail(spec, `protocol must be "tcp" or "udp", got "${protoStr}"`);
+		}
+	}
+
+	const parts = body.split(":");
+	if (parts.length > 3) {
+		fail(spec, `too many ":" segments (expected name[:host[:guest]])`);
+	}
+	const name = parts[0]?.trim() ?? "";
+	if (!name) {
+		fail(spec, "name is required");
+	}
+
+	const known = lookupGuestPort(name);
+
+	let host = 0;
+	if (parts.length >= 2 && parts[1] !== "" && parts[1] !== undefined) {
+		host = parsePort(spec, parts[1], "host", true);
+	}
+
+	let guest: number;
+	if (parts.length >= 3 && parts[2] !== "" && parts[2] !== undefined) {
+		guest = parsePort(spec, parts[2], "guest", false);
+	} else if (known) {
+		guest = known.guest;
+	} else {
+		fail(spec, `guest port required for unknown service "${name}"`);
+	}
+
+	const proto: "tcp" | "udp" = (protoStr as "tcp" | "udp" | undefined) ?? known?.proto ?? "tcp";
+
+	return { name, host, guest, proto };
+}

package/src/lib/guest-ports.ts

@@ -0,0 +1,67 @@
+/**
+ * Well-known guest port registry.
+ *
+ * Maps a canonical service name (e.g. "smb", "winbox") to its guest-side port
+ * and protocol. Used to power short-form `--forward <name>` CLI flags so users
+ * don't have to remember exact port numbers.
+ *
+ * Pure data + lookup. No side effects, no imports from the rest of the codebase.
+ */
+
+export interface GuestPortDef {
+	/** Canonical lowercase name, e.g. "smb". */
+	name: string;
+	/** Guest-side port number (1..65535). */
+	guest: number;
+	/** Transport protocol. */
+	proto: "tcp" | "udp";
+	/** Optional alternate names that resolve to this entry, e.g. ["cifs"] for "smb". */
+	aliases?: string[];
+	/** Brief, factual notes. May reference RouterOS package or subsystem. */
+	notes?: string;
+}
+
+export const WELL_KNOWN_GUEST_PORTS: readonly GuestPortDef[] = [
+	// --- RouterOS services (defaults from /ip/service) ---
+	{ name: "ftp", guest: 21, proto: "tcp", notes: "RouterOS /ip/service ftp" },
+	{ name: "ssh", guest: 22, proto: "tcp", notes: "RouterOS /ip/service ssh" },
+	{ name: "telnet", guest: 23, proto: "tcp", notes: "RouterOS /ip/service telnet" },
+	{ name: "http", guest: 80, proto: "tcp", aliases: ["www", "webfig"], notes: "RouterOS /ip/service www (WebFig + REST)" },
+	{ name: "https", guest: 443, proto: "tcp", aliases: ["www-ssl", "webfig-ssl"], notes: "RouterOS /ip/service www-ssl (WebFig + REST over TLS)" },
+	{ name: "snmp", guest: 161, proto: "udp", notes: "RouterOS /snmp" },
+	{ name: "bandwidth-test", guest: 2000, proto: "tcp", aliases: ["btest"], notes: "RouterOS /tool/bandwidth-server" },
+	{ name: "dude", guest: 2210, proto: "tcp", notes: "RouterOS dude package server (legacy)" },
+	{ name: "dude-secure", guest: 2211, proto: "tcp", notes: "RouterOS dude package server (TLS)" },
+	{ name: "upnp", guest: 2828, proto: "tcp", notes: "RouterOS /ip/upnp" },
+	{ name: "winbox", guest: 8291, proto: "tcp", notes: "RouterOS /ip/service winbox (also used by Dude client and MikroTik mobile app)" },
+	{ name: "api", guest: 8728, proto: "tcp", notes: "RouterOS /ip/service api (native API)" },
+	{ name: "api-ssl", guest: 8729, proto: "tcp", notes: "RouterOS /ip/service api-ssl" },
+	{ name: "socks", guest: 1080, proto: "tcp", notes: "RouterOS /ip/socks" },
+
+	// --- Common services often forwarded for container / userspace use ---
+	{ name: "dns", guest: 53, proto: "udp", notes: "DNS resolver (UDP)" },
+	{ name: "dns-tcp", guest: 53, proto: "tcp", notes: "DNS resolver (TCP, used for large responses and zone transfers)" },
+	{ name: "ntp", guest: 123, proto: "udp", notes: "Network Time Protocol" },
+	{ name: "smb", guest: 445, proto: "tcp", aliases: ["cifs"], notes: "SMB/CIFS file sharing" },
+	{ name: "syslog", guest: 514, proto: "udp", notes: "Syslog (UDP)" },
+	{ name: "mqtt", guest: 1883, proto: "tcp", notes: "MQTT broker (plaintext)" },
+	{ name: "winrm", guest: 5985, proto: "tcp", notes: "Windows Remote Management (HTTP)" },
+	{ name: "winrm-https", guest: 5986, proto: "tcp", notes: "Windows Remote Management (HTTPS)" },
+	{ name: "http-alt", guest: 8080, proto: "tcp", notes: "Alternate HTTP, common for containerized web apps" },
+	{ name: "https-alt", guest: 8443, proto: "tcp", notes: "Alternate HTTPS, common for containerized web apps" },
+	{ name: "mqtts", guest: 8883, proto: "tcp", notes: "MQTT broker (TLS)" },
+];
+
+/**
+ * Look up a guest port definition by canonical name or alias.
+ * Case-insensitive. Returns `undefined` if not found.
+ */
+export function lookupGuestPort(nameOrAlias: string): GuestPortDef | undefined {
+	if (!nameOrAlias) return undefined;
+	const key = nameOrAlias.toLowerCase();
+	for (const entry of WELL_KNOWN_GUEST_PORTS) {
+		if (entry.name === key) return entry;
+		if (entry.aliases?.some((a) => a.toLowerCase() === key)) return entry;
+	}
+	return undefined;
+}

package/src/lib/network.ts

@@ -8,6 +8,7 @@ import {
 	DEFAULT_PORT_BASE,
 	PORTS_PER_BLOCK,
 	type ChrPorts,
+	type MachineState,
 	type NetworkConfig,
 	type NetworkMode,
 	type NetworkSpecifier,
@@ -77,6 +78,78 @@ export function buildPortMappings(
 	return mappings;
 }
 
+/** Validate user-supplied `extraPorts` with explicit `host` values for collisions.
+ *
+ *  Rejects three classes of conflict:
+ *   1. Explicit host equals one of this machine's auto-allocated SERVICE_PORTS
+ *      slots (`portBase + offset`) for a non-excluded service.
+ *   2. Two explicit entries in the same `extraPorts` set request the same host.
+ *   3. Explicit host is already in use by another existing machine's port mapping.
+ *
+ *  Auto-allocated extras (host falsy/0) are not validated here — the live
+ *  `findAvailablePortBlock` probe handles those.
+ *
+ *  Pass `ownMachineName` to skip an existing machine's mappings (e.g. when
+ *  re-validating during a restart).
+ */
+export function validateExplicitExtraPorts(
+	extraPorts: PortMapping[] | undefined,
+	portBase: number,
+	excludePorts: ServiceName[] = [],
+	existingMachines: MachineState[] = [],
+	ownMachineName?: string,
+): void {
+	if (!extraPorts || extraPorts.length === 0) return;
+
+	const serviceHosts = new Map<number, string>();
+	for (const [name, spec] of Object.entries(SERVICE_PORTS)) {
+		if (excludePorts.includes(name as ServiceName)) continue;
+		serviceHosts.set(portBase + spec.offset, name);
+	}
+
+	const otherHosts = new Map<number, { machine: string; service: string }>();
+	for (const m of existingMachines) {
+		if (ownMachineName && m.name === ownMachineName) continue;
+		for (const mapping of Object.values(m.ports ?? {})) {
+			otherHosts.set(mapping.host, { machine: m.name, service: mapping.name });
+		}
+	}
+
+	const seenInExtras = new Map<number, string>();
+
+	for (let i = 0; i < extraPorts.length; i++) {
+			const extra = extraPorts[i];
+			if (!extra?.host) continue;
+
+		const label = extra.name || `custom-${i}`;
+
+		const svc = serviceHosts.get(extra.host);
+		if (svc) {
+			throw new QuickCHRError(
+				"PORT_CONFLICT",
+				`Explicit extra port "${label}" host=${extra.host} collides with built-in service "${svc}" (portBase=${portBase}). Pick a different host port or exclude the service.`,
+			);
+		}
+
+		const dup = seenInExtras.get(extra.host);
+		if (dup) {
+			throw new QuickCHRError(
+				"PORT_CONFLICT",
+				`Explicit extra ports "${dup}" and "${label}" both request host=${extra.host}.`,
+			);
+		}
+		seenInExtras.set(extra.host, label);
+
+		const other = otherHosts.get(extra.host);
+		if (other) {
+			throw new QuickCHRError(
+				"PORT_CONFLICT",
+				`Explicit extra port "${label}" host=${extra.host} is already allocated to machine "${other.machine}" (service "${other.service}").`,
+			);
+		}
+	}
+}
+
 /** Build QEMU hostfwd string from port mappings. */
 export function buildHostfwdString(ports: Record<string, PortMapping>): string {
 	return Object.values(ports)

package/src/lib/packages.ts

@@ -2,15 +2,15 @@
  * Extra package download and installation for CHR instances.
  */
 
-import { existsSync, readdirSync, unlinkSync, chmodSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join, basename } from "node:path";
-import { tmpdir } from "node:os";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { restPost } from "./rest.ts";
+import { scpPush } from "./scp.ts";
 import { extractZip } from "./zip.ts";
 
 /** Download and extract the all-packages ZIP for a version/arch. Returns the extract dir. */
@@ -74,7 +74,7 @@ export function findPackageFile(
 	return match ? join(extractDir, match) : undefined;
 }
 
-/** Upload packages to a running CHR via SCP. */
+/** Upload packages to a running CHR via SCP. Uploads each file to flash root (`/<basename>`). */
 export async function uploadPackages(
 	packagePaths: string[],
 	sshPort: number,
@@ -82,58 +82,11 @@ export async function uploadPackages(
 	password: string = "",
 	logger?: ProgressLogger,
 ): Promise<void> {
-	// Use SSH_ASKPASS to supply the password without requiring sshpass.
-	// SSH_ASKPASS_REQUIRE=prefer (OpenSSH 8.4+) works even without a display.
-	// SSH_ASKPASS: a small helper program that prints the password when invoked.
-	// On Windows: .cmd script (OpenSSH Windows calls it as a process, not a shell).
-	// On Unix: .sh script with execute bit set via chmodSync.
-	const isWindows = process.platform === "win32";
-	const ext = isWindows ? ".cmd" : ".sh";
-	const askpassPath = join(tmpdir(), `quickchr-askpass-${process.pid}${ext}`);
-	if (isWindows) {
-		// Windows .cmd: OpenSSH reads stdout from the helper
-		await Bun.write(askpassPath, `@echo off\r\necho ${password.replace(/[&|<>^%]/g, "^$&")}\r\n`);
-	} else {
-		await Bun.write(askpassPath, `#!/bin/sh\nprintf '%s' '${password.replace(/'/g, "'\\''")}'`);
-		chmodSync(askpassPath, 0o755);
-	}
-
-	const scpEnv: Record<string, string> = {
-		...(process.env as Record<string, string>),
-		DISPLAY: "",
-		SSH_ASKPASS: askpassPath,
-		SSH_ASKPASS_REQUIRE: "prefer",
-	};
-
-	try {
-		const log = logger ?? createLogger();
-		for (const pkgPath of packagePaths) {
-			const filename = basename(pkgPath);
-			log.status(`Uploading: ${filename}`);
-
-			const scpArgs = [
-				"scp", "-P", String(sshPort),
-				"-o", "StrictHostKeyChecking=accept-new",
-				"-o", "UserKnownHostsFile=/dev/null",
-				pkgPath, `${user}@127.0.0.1:/`,
-			];
-
-			const result = Bun.spawnSync(scpArgs, {
-				stdout: "pipe",
-				stderr: "pipe",
-				env: scpEnv,
-			});
-
-			if (result.exitCode !== 0) {
-				const stderr = new TextDecoder().decode(result.stderr);
-				throw new QuickCHRError(
-					"PROCESS_FAILED",
-					`SCP upload failed for ${filename}: ${stderr}`,
-				);
-			}
-		}
-	} finally {
-		try { unlinkSync(askpassPath); } catch { /* ignore */ }
+	const log = logger ?? createLogger();
+	for (const pkgPath of packagePaths) {
+		const filename = basename(pkgPath);
+		log.status(`Uploading: ${filename}`);
+		await scpPush(pkgPath, undefined, { sshPort, user, password });
 	}
 }
 

package/src/lib/quickchr.ts

@@ -27,11 +27,12 @@ import {
 	assertProvisioningSupportedVersion,
 	PROVISIONING_FEATURE_LABEL,
 } from "./versions.ts";
-import { buildPortMappings, findAvailablePortBlock, resolveStartNetworks, resolveAllNetworks, buildHostfwdString, hasUserModeNetwork } from "./network.ts";
+import { buildPortMappings, findAvailablePortBlock, resolveStartNetworks, resolveAllNetworks, buildHostfwdString, hasUserModeNetwork, validateExplicitExtraPorts } from "./network.ts";
 import {
 	getUsedPortBases,
 	saveMachine,
 	loadMachine,
+	loadAllMachines,
 	removeMachine as removeState,
 	getMachineDir,
 	getMachinesDir,
@@ -43,13 +44,15 @@ import {
 	getDataDir,
 } from "./state.ts";
 import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
+import { autoPruneIfOverCap } from "./cache.ts";
 import { buildQemuArgs, spawnQemu, stopQemu, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
 import { monitorCommand, serialStreams, qgaCommand, channelEndpoint } from "./channels.ts";
 import { installPackages, installAllPackages, downloadAndListPackages, downloadPackages, findPackageFile, uploadPackages } from "./packages.ts";
 import { provision } from "./provision.ts";
 import { renewLicense, getLicenseInfo } from "./license.ts";
-import { resolveAuth } from "./auth.ts";
+import { resolveAuth, resolveCreds } from "./auth.ts";
+import { scpPush, scpPull } from "./scp.ts";
 import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials } from "./credentials.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
@@ -109,6 +112,16 @@ function hasProvisioningMutations(opts: {
 	);
 }
 
+/** Normalize convenience aliases on StartOptions:
+ *  - `noAuth: true` → `secureLogin: false` (only when secureLogin is not explicitly set).
+ *  Returns a shallow copy so the caller's input object is not mutated. */
+function normalizeStartOptions(opts: StartOptions): StartOptions {
+	if (opts.noAuth === true && opts.secureLogin === undefined) {
+		return { ...opts, secureLogin: false };
+	}
+	return opts;
+}
+
 function listProvisioningMutations(opts: {
 	installAllPackages?: boolean;
 	packages?: string[];
@@ -166,7 +179,7 @@ function registerSocketMembers(state: MachineState): void {
 	for (const name of getSocketNamedNetworks(state)) {
 		try {
 			if (!getNamedSocket(name)) {
-				createNamedSocket(name);
+				createNamedSocket(name, { autoCreated: true });
 			}
 			addSocketMember(name, state.name);
 		} catch (e) {
@@ -218,6 +231,9 @@ function createInstance(state: MachineState): ChrInstance {
 		ports,
 		restUrl,
 		sshPort: ports.ssh,
+		portBase: state.portBase,
+		captureInterface: process.platform === "darwin" ? "lo0" : "any",
+		tzspGatewayIp: "10.0.2.2",
 
 		async waitForBoot(timeoutMs?: number): Promise<boolean> {
 			// Use resolved credentials so waitForBoot can validate the response body
@@ -226,6 +242,19 @@ function createInstance(state: MachineState): ChrInstance {
 			return waitForBoot(ports.http, timeoutMs, auth.header);
 		},
 
+		async waitFor(condition: () => Promise<boolean>, timeoutMs = 30_000): Promise<boolean> {
+			const deadline = Date.now() + timeoutMs;
+			while (Date.now() < deadline) {
+				try {
+					if (await condition()) return true;
+				} catch { /* swallow — condition may throw before the state is ready */ }
+				const remaining = deadline - Date.now();
+				if (remaining <= 0) break;
+				await Bun.sleep(Math.min(2000, remaining));
+			}
+			return false;
+		},
+
 		async stop(): Promise<void> {
 			if (state.pid) {
 				await stopQemu(state.pid);
@@ -514,6 +543,28 @@ function createInstance(state: MachineState): ChrInstance {
 			return installed;
 		},
 
+		async upload(localPath: string, remotePath?: string): Promise<void> {
+			if (!isMachineRunning(state)) {
+				throw new QuickCHRError(
+					"MACHINE_STOPPED",
+					`Machine "${state.name}" must be running to upload files.`,
+				);
+			}
+			const creds = resolveCreds(state);
+			await scpPush(localPath, remotePath, { sshPort: ports.ssh, ...creds });
+		},
+
+		async download(remotePath: string, localPath: string): Promise<void> {
+			if (!isMachineRunning(state)) {
+				throw new QuickCHRError(
+					"MACHINE_STOPPED",
+					`Machine "${state.name}" must be running to download files.`,
+				);
+			}
+			const creds = resolveCreds(state);
+			await scpPull(remotePath, localPath, { sshPort: ports.ssh, ...creds });
+		},
+
 		async destroy(): Promise<void> {
 			await this.stop();
 			await this.remove();
@@ -690,6 +741,12 @@ function hostArchToChr(): Arch {
 	return "x86";
 }
 
+/** Resolve user-supplied arch (including the "auto" synonym) to a concrete Arch. */
+function resolveArch(input: Arch | "auto" | undefined): Arch {
+	if (input === undefined || input === "auto") return hostArchToChr();
+	return input;
+}
+
 async function waitForPidExit(pid: number, timeoutMs: number): Promise<boolean> {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
@@ -937,6 +994,7 @@ export class QuickCHR {
 	 *  and applied automatically on the first subsequent start(). Disk options (`bootSize`,
 	 *  `extraDisks`) are materialized immediately and require `qemu-img` on the host. */
 	static async add(opts: StartOptions = {}): Promise<MachineState> {
+		opts = normalizeStartOptions(opts);
 		if (opts.name?.startsWith("-")) {
 			throw new QuickCHRError("INVALID_NAME", `Invalid machine name "${opts.name}" — names cannot start with "-"`);
 		}
@@ -952,7 +1010,7 @@ export class QuickCHR {
 			version = await resolveVersion(channel);
 		}
 
-		const arch: Arch = opts.arch ?? hostArchToChr();
+		const arch: Arch = resolveArch(opts.arch);
 		requireQemu(arch);
 		if (arch === "arm64") requireFirmware();
 		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
@@ -987,6 +1045,7 @@ export class QuickCHR {
 
 		const usedBases = getUsedPortBases();
 		const portBase = opts.portBase ?? await findAvailablePortBlock(usedBases, opts.excludePorts, opts.extraPorts);
+		validateExplicitExtraPorts(opts.extraPorts, portBase, opts.excludePorts, loadAllMachines(), name);
 		const ports = buildPortMappings(portBase, opts.excludePorts, opts.extraPorts);
 
 		const machineDir = getMachineDir(name);
@@ -1017,6 +1076,7 @@ export class QuickCHR {
 				deviceMode: opts.deviceMode,
 				user: opts.user,
 				disableAdmin: opts.disableAdmin,
+				secureLogin: opts.secureLogin,
 				portBase,
 				excludePorts: opts.excludePorts ?? [],
 				extraPorts: opts.extraPorts ?? [],
@@ -1044,6 +1104,7 @@ export class QuickCHR {
 	 * apply when creating a new machine and require `qemu-img` on the host.
 	 */
 	static async start(opts: StartOptions = {}): Promise<ChrInstance> {
+		opts = normalizeStartOptions(opts);
 		// Validate name early (before any I/O) so callers get a fast, clear error
 		if (opts.name?.startsWith("-")) {
 			throw new QuickCHRError("INVALID_NAME", `Invalid machine name "${opts.name}" — names cannot start with "-"`);
@@ -1062,6 +1123,9 @@ export class QuickCHR {
 		let version: string;
 		if (opts.version) {
 			if ((CHANNELS as 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.`,
+				);
 				version = await resolveVersion(opts.version as Channel);
 			} else if (!isValidVersion(opts.version)) {
 				throw new QuickCHRError("INVALID_VERSION", `Invalid version: ${opts.version}`);
@@ -1094,7 +1158,7 @@ export class QuickCHR {
 		}
 
 		// Resolve architecture
-		const arch: Arch = opts.arch ?? hostArchToChr();
+		const arch: Arch = resolveArch(opts.arch);
 		const diskOpts = normalizeDiskOptions(opts.bootSize, opts.extraDisks, opts.bootDiskFormat);
 
 		// Check prerequisites (skip for dry-run — no QEMU needed)
@@ -1152,6 +1216,14 @@ export class QuickCHR {
 				opts.extraPorts,
 			);
 
+		validateExplicitExtraPorts(
+			opts.extraPorts,
+			portBase,
+			opts.excludePorts,
+			loadAllMachines(),
+			name,
+		);
+
 		const ports = buildPortMappings(
 			portBase,
 			opts.excludePorts,
@@ -1173,6 +1245,7 @@ export class QuickCHR {
 				deviceMode: requestedDeviceMode,
 				user: opts.user,
 				disableAdmin: opts.disableAdmin,
+				secureLogin: opts.secureLogin,
 				portBase,
 				excludePorts: opts.excludePorts ?? [],
 				extraPorts: opts.extraPorts ?? [],
@@ -1247,6 +1320,7 @@ export class QuickCHR {
 			deviceMode: requestedDeviceMode,
 			user: opts.user,
 			disableAdmin: opts.disableAdmin,
+			secureLogin: opts.secureLogin,
 			portBase,
 			excludePorts: opts.excludePorts ?? [],
 			extraPorts: opts.extraPorts ?? [],
@@ -1584,6 +1658,10 @@ export class QuickCHR {
 			await QuickCHR._provisionInstance(instance, state, provisioningOpts, launchConfig, logger);
 		}
 
+		try {
+			autoPruneIfOverCap({ logger: logger ? (msg) => logger.status(msg) : undefined, protectVersions: [state.version] });
+		} catch { /* never propagate */ }
+
 		return instance;
 		} finally {
 			try { unlinkSync(lockPath); } catch { /* ignore */ }

package/src/lib/scp.ts

@@ -0,0 +1,97 @@
+/**
+ * SCP file transfer to/from a running CHR.
+ *
+ * Uses the same SSH_ASKPASS trick as {@link ./packages.ts uploadPackages} so
+ * no `sshpass` dependency is required. Both directions share the askpass
+ * lifecycle (written to tmpdir, cleaned up on exit).
+ */
+
+import { chmodSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+import { QuickCHRError } from "./types.ts";
+
+export interface ScpOptions {
+	sshPort: number;
+	user: string;
+	password: string;
+}
+
+/** Copy a local file to the CHR. `remotePath` defaults to `/<basename>` (RouterOS flash root). */
+export async function scpPush(
+	localPath: string,
+	remotePath: string | undefined,
+	opts: ScpOptions,
+): Promise<void> {
+	const remote = remotePath ?? `/${basename(localPath)}`;
+	await runScp([localPath, `${opts.user}@127.0.0.1:${remote}`], opts, `upload ${basename(localPath)}`);
+}
+
+/** Copy a file from the CHR to the local filesystem. */
+export async function scpPull(
+	remotePath: string,
+	localPath: string,
+	opts: ScpOptions,
+): Promise<void> {
+	await runScp([`${opts.user}@127.0.0.1:${remotePath}`, localPath], opts, `download ${remotePath}`);
+}
+
+/** Shared plumbing: write askpass, invoke `scp`, clean up, translate exit code to QuickCHRError. */
+async function runScp(
+	scpArgs: string[],
+	opts: ScpOptions,
+	label: string,
+): Promise<void> {
+	const { askpassPath, env } = await writeAskpass(opts.password);
+	try {
+		const args = [
+			"scp",
+			"-P", String(opts.sshPort),
+			"-o", "StrictHostKeyChecking=accept-new",
+			"-o", "UserKnownHostsFile=/dev/null",
+			...scpArgs,
+		];
+		const result = Bun.spawnSync(args, {
+			stdout: "pipe",
+			stderr: "pipe",
+			env,
+		});
+		if (result.exitCode !== 0) {
+			const stderr = new TextDecoder().decode(result.stderr);
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`SCP ${label} failed: ${stderr.trim() || `exit ${result.exitCode}`}`,
+			);
+		}
+	} finally {
+		try { unlinkSync(askpassPath); } catch { /* ignore */ }
+	}
+}
+
+/**
+ * Write an SSH_ASKPASS helper for the given password.
+ *
+ * SSH_ASKPASS: a small program OpenSSH invokes to fetch a password when no
+ * TTY is available. `SSH_ASKPASS_REQUIRE=prefer` (OpenSSH 8.4+) makes it
+ * work without a display. On Windows we emit a `.cmd`; on Unix a `.sh`
+ * with the execute bit set.
+ */
+async function writeAskpass(password: string): Promise<{ askpassPath: string; env: Record<string, string> }> {
+	const isWindows = process.platform === "win32";
+	const ext = isWindows ? ".cmd" : ".sh";
+	const askpassPath = join(tmpdir(), `quickchr-askpass-${process.pid}-${Date.now()}${ext}`);
+	if (isWindows) {
+		await Bun.write(askpassPath, `@echo off\r\necho ${password.replace(/[&|<>^%]/g, "^$&")}\r\n`);
+	} else {
+		await Bun.write(askpassPath, `#!/bin/sh\nprintf '%s' '${password.replace(/'/g, "'\\''")}'`);
+		chmodSync(askpassPath, 0o755);
+	}
+	const env: Record<string, string> = {
+		...(process.env as Record<string, string>),
+		DISPLAY: "",
+		SSH_ASKPASS: askpassPath,
+		SSH_ASKPASS_REQUIRE: "prefer",
+	};
+	return { askpassPath, env };
+}