@tikoci/quickchr 0.2.0 → 0.3.0

package/src/lib/socket-registry.ts

@@ -14,7 +14,10 @@ export interface SocketEntry {
 	mcastGroup?: string;
 	port: number;
 	createdAt: string;
+	/** Machines that currently reference this socket. */
 	members: string[];
+	/** Auto-created by `start()` (true) vs explicit user/CLI creation (false). */
+	autoCreated: boolean;
 }
 
 const DEFAULT_START_PORT = 4000;
@@ -41,6 +44,19 @@ function socketPath(name: string): string {
 	return join(getSocketRegistryDir(), `${name}.json`);
 }
 
+/** Normalize an entry loaded from disk: defaults missing fields for backward compat. */
+function normalizeEntry(raw: Partial<SocketEntry> & { name: string; mode: SocketEntry["mode"]; port: number; createdAt: string }): SocketEntry {
+	return {
+		name: raw.name,
+		mode: raw.mode,
+		mcastGroup: raw.mcastGroup,
+		port: raw.port,
+		createdAt: raw.createdAt,
+		members: Array.isArray(raw.members) ? [...raw.members] : [],
+		autoCreated: typeof raw.autoCreated === "boolean" ? raw.autoCreated : false,
+	};
+}
+
 function saveEntry(entry: SocketEntry): void {
 	writeFileSync(socketPath(entry.name), JSON.stringify(entry, null, "\t") + "\n");
 	_cache.set(entry.name, entry);
@@ -54,7 +70,7 @@ function allocatePort(existing: SocketEntry[]): number {
 
 export function createNamedSocket(
 	name: string,
-	opts?: { mode?: "mcast" | "listen-connect"; port?: number; mcastGroup?: string },
+	opts?: { mode?: "mcast" | "listen-connect"; port?: number; mcastGroup?: string; autoCreated?: boolean },
 ): SocketEntry {
 	if (_cache.has(name) || existsSync(socketPath(name))) {
 		throw new QuickCHRError("STATE_ERROR", `Named socket "${name}" already exists`);
@@ -71,6 +87,7 @@ export function createNamedSocket(
 		mcastGroup,
 		createdAt: new Date().toISOString(),
 		members: [],
+		autoCreated: opts?.autoCreated ?? false,
 	};
 
 	saveEntry(entry);
@@ -81,7 +98,8 @@ export function getNamedSocket(name: string): SocketEntry | undefined {
 	const cached = _cache.get(name);
 	if (cached) return cached;
 	try {
-		const entry = JSON.parse(readFileSync(socketPath(name), "utf-8")) as SocketEntry;
+		const raw = JSON.parse(readFileSync(socketPath(name), "utf-8"));
+		const entry = normalizeEntry(raw);
 		_cache.set(name, entry);
 		return entry;
 	} catch {
@@ -98,7 +116,8 @@ export function listNamedSockets(): SocketEntry[] {
 			const name = file.replace(/\.json$/, "");
 			if (!merged.has(name)) {
 				try {
-					const entry = JSON.parse(readFileSync(join(dir, file), "utf-8")) as SocketEntry;
+					const raw = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+					const entry = normalizeEntry(raw);
 					merged.set(name, entry);
 					_cache.set(name, entry);
 				} catch {}
@@ -132,7 +151,7 @@ export function removeSocketMember(name: string, machineName: string): void {
 	const entry = getNamedSocket(name);
 	if (!entry) return;
 	entry.members = entry.members.filter((m) => m !== machineName);
-	if (entry.members.length === 0) {
+	if (entry.members.length === 0 && entry.autoCreated) {
 		removeNamedSocket(name);
 	} else {
 		saveEntry(entry);

package/src/lib/types.ts

@@ -195,12 +195,17 @@ export interface MachineState extends MachineConfig {
  * requires SCP upload + reboot cycle, typically 60–120s extra on native acceleration).
  */
 export interface StartOptions {
-	/** RouterOS version to use (e.g. "7.22.1"). Mutually exclusive with `channel`. */
+	/** RouterOS version to use (e.g. "7.22.1"). Mutually exclusive with `channel`.
+	 *  As a convenience, a channel name (e.g. "long-term") is also accepted here and
+	 *  resolves the same as `channel: "long-term"` — but this emits a warning, since
+	 *  `channel` is the self-documenting field for that case. */
 	version?: string;
 	/** Release channel to resolve latest version from. Default: "stable". */
 	channel?: Channel;
-	/** Guest architecture. Default: matches host (arm64 on Apple Silicon, x86 on Intel/AMD). */
-	arch?: Arch;
+	/** Guest architecture. Default: matches host (arm64 on Apple Silicon, x86 on Intel/AMD).
+	 *  Pass `"auto"` as an explicit synonym for the default — useful when an agent or
+	 *  caller wants to state the intent rather than omit the field. */
+	arch?: Arch | "auto";
 	/** Instance name. Auto-generated from version+arch if omitted. Must not start with "-". */
 	name?: string;
 	/** Number of virtual CPUs. Default: 1. */
@@ -226,6 +231,11 @@ export interface StartOptions {
 	 *  Enabling the managed login path is quickchr provisioning, so it is validated/tested
 	 *  on RouterOS 7.20.8+ only. */
 	secureLogin?: boolean;
+	/** Convenience alias: `noAuth: true` is equivalent to `secureLogin: false` —
+	 *  skip the managed `quickchr` user provisioning, leave admin password-less.
+	 *  Self-documenting alternative for callers who find `secureLogin: false` cryptic.
+	 *  When both are set, an explicit `secureLogin` value wins. */
+	noAuth?: boolean;
 	/** Starting port number for this instance's port block. Auto-allocated if omitted. */
 	portBase?: number;
 	/** Services to exclude from port mappings (e.g. ["winbox", "api-ssl"]). */
@@ -304,12 +314,51 @@ export interface ChrInstance {
 	ports: ChrPorts;
 	restUrl: string;
 	sshPort: number;
+	/** Port block base for this instance. Useful for picking L2 socket ports
+	 *  that won't collide with this instance's management ports.
+	 *  Each block occupies `PORTS_PER_BLOCK` (10) consecutive ports starting here.
+	 *  @example
+	 *  // Pick a socket port outside any running instance's block:
+	 *  const socketPort = Math.max(...instances.map(i => i.portBase)) + PORTS_PER_BLOCK;
+	 */
+	portBase: number;
+	/** Platform-appropriate network interface for capturing TZSP traffic from this instance.
+	 *  `"lo0"` on macOS — QEMU user-mode (slirp) routes guest UDP through the host loopback.
+	 *  `"any"` on Linux — TZSP arrives on whichever interface the host routes it to.
+	 *  Pass directly to tshark: `tshark -i ${instance.captureInterface} -f "udp port 37008"`
+	 *  Only meaningful when the instance has a user-mode (`"user"`) network interface. */
+	captureInterface: string;
+	/** QEMU user-mode networking gateway IP — the host's address as seen from inside the VM.
+	 *  Use this as the RouterOS `/tool/sniffer` streaming-server target so TZSP traffic
+	 *  reaches the host. Always `"10.0.2.2"` for QEMU slirp user-mode networking.
+	 *  @example
+	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.tzspGatewayIp}:37008`);
+	 */
+	tzspGatewayIp: string;
 
 	/** Check or wait for REST API readiness.
 	 *  After `QuickCHR.start()` with provisioning options (installAllPackages, license, etc.),
 	 *  the returned instance is already REST-reachable — this returns immediately.
 	 *  Call this only when starting without provisioning, or as a safety check after a manual stop/restart. */
 	waitForBoot(timeoutMs?: number): Promise<boolean>;
+	/** Poll a condition until it returns true or the timeout elapses.
+	 *  Retries every 2 s, swallowing errors from the condition function.
+	 *  Returns `true` when the condition passes, `false` on timeout.
+	 *
+	 *  Useful for waiting on RouterOS state that isn't reflected in the boot readiness
+	 *  check — e.g. waiting for a package to become active, a daemon to enable, or a
+	 *  background script to complete.
+	 *
+	 *  @param condition  Async predicate: return `true` when the desired state is reached.
+	 *  @param timeoutMs  Maximum wait in milliseconds (default: 30 000).
+	 *  @example
+	 *  // Wait for the Dude daemon to report enabled=yes
+	 *  const ready = await instance.waitFor(async () => {
+	 *    const r = await instance.exec("/dude/print");
+	 *    return r.output.includes("enabled: yes");
+	 *  }, 30_000);
+	 */
+	waitFor(condition: () => Promise<boolean>, timeoutMs?: number): Promise<boolean>;
 	stop(): Promise<void>;
 	remove(): Promise<void>;
 	clean(): Promise<void>;
@@ -329,7 +378,19 @@ export interface ChrInstance {
 	qga(command: QgaCommand, args?: object): Promise<unknown>;
 
 	rest(path: string, opts?: RequestInit): Promise<unknown>;
-	/** Run a RouterOS CLI command against the instance. */
+	/** Run a RouterOS CLI command against the instance.
+	 *
+	 *  **Single command per call.** RouterOS `/rest/execute` runs the input as one
+	 *  script statement; a multi-line `command` string with `\n`-separated commands
+	 *  may execute only the first line and silently ignore the rest depending on
+	 *  RouterOS version. To run several commands, call `exec()` multiple times, or
+	 *  wrap them in an explicit RouterOS script: `:do { /cmd1; /cmd2 }`.
+	 *
+	 *  **Soft errors.** Some RouterOS commands return HTTP 200 with an error
+	 *  string in `output` (e.g. `/dude/agent/add` may resolve OK with
+	 *  `"doAdd Agent not implemented"`). `exec()` does not parse output for these
+	 *  patterns — inspect `result.output` if you need to assert success.
+	 */
 	exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
 	/** Apply or renew a CHR trial license.
 	 *  quickchr validates this provisioning flow on RouterOS 7.20.8+ only. */
@@ -343,6 +404,22 @@ export interface ChrInstance {
 	 *  @param logger   Optional progress logger for status/debug output. */
 	setDeviceMode(options: DeviceModeOptions, logger?: ProgressLogger): Promise<void>;
 
+	/** Copy a local file to the CHR via SCP.
+	 *  Machine must be running. `remotePath` defaults to `/<basename>` (RouterOS flash root).
+	 *  Uses the resolved instance credentials.
+	 *  @example
+	 *  await instance.upload("./dude.db", "/dude/dude.db");
+	 *  await instance.upload("./config.rsc"); // → /config.rsc
+	 */
+	upload(localPath: string, remotePath?: string): Promise<void>;
+
+	/** Copy a file from the CHR to the local filesystem via SCP.
+	 *  Machine must be running. Uses the resolved instance credentials.
+	 *  @example
+	 *  await instance.download("/dude/dude.db", "./dude-snapshot.db");
+	 */
+	download(remotePath: string, localPath: string): Promise<void>;
+
 	/** List extra packages available for this instance's version and arch.
 	 *  Downloads and caches the all_packages ZIP on the first call. */
 	availablePackages(): Promise<string[]>;
@@ -460,6 +537,7 @@ export type ErrorCode =
 	| "SPAWN_FAILED"
 	| "NETWORK_UNAVAILABLE"
 	| "INVALID_NETWORK"
+	| "INVALID_FORWARD_SPEC"
 	| "PROVISIONING_VERSION_UNSUPPORTED"
 	| "INSUFFICIENT_DISK_SPACE"
 	| "STATE_ERROR";