@tikoci/centrs 0.1.3 → 0.1.6

package/src/retrieve.ts

@@ -15,6 +15,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -26,11 +27,14 @@ import {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	isIpTransport,
 	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	type QuickchrResolution,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -39,6 +43,7 @@ import {
 	resolveCdb,
 	resolveMacTarget,
 	resolveOptionalIntegerSetting,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -49,6 +54,12 @@ export type RetrieveOutputFormat = (typeof retrieveOutputFormats)[number];
 
 export interface RetrieveRequest {
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password.
+	 */
+	quickchr?: string;
 	path: string;
 	via?: string;
 	host?: string;
@@ -123,6 +134,14 @@ export interface ResolvedRetrieveRequest {
 	timeoutMs: ResolvedSetting<number>;
 	format: ResolvedSetting<RetrieveOutputFormat>;
 	validate: ResolvedSetting<boolean>;
+	/**
+	 * Relax TLS peer verification. retrieve has no `--insecure` flag; this is set
+	 * only by the quickchr provider (trust-by-provenance for the VM's self-signed
+	 * TLS forward — see `src/resolver/quickchr-provider.ts`), so when present its
+	 * source is always `provider` and it is surfaced as `meta.settings.insecure`
+	 * for auditability.
+	 */
+	insecure?: ResolvedSetting<boolean>;
 	maxResultsBytes?: ResolvedSetting<number>;
 	attributes: readonly string[];
 	allAttributes: boolean;
@@ -161,6 +180,7 @@ export async function runResolvedRetrieve(
 		username: resolved.auth.username,
 		password: resolved.auth.password,
 		timeoutMs: resolved.timeoutMs.value,
+		insecure: resolved.insecure?.value,
 	});
 
 	try {
@@ -212,7 +232,8 @@ export async function runResolvedRetrieve(
 						"Check the attribute name, or use `--list-attributes` to inspect the available properties first.",
 					context: {
 						path: resolved.path,
-						requested: resolved.attributes,
+						parameter: missing[0],
+						requestedAttributes: resolved.attributes,
 						availableAttributes,
 					},
 				});
@@ -462,6 +483,9 @@ function metaFromResolved(
 			timeoutMs: toCoreSource(resolved.timeoutMs.source),
 			format: toCoreSource(resolved.format.source),
 			validate: toCoreSource(resolved.validate.source),
+			insecure: resolved.insecure
+				? toCoreSource(resolved.insecure.source)
+				: undefined,
 			maxResultsBytes: resolved.maxResultsBytes
 				? toCoreSource(resolved.maxResultsBytes.source)
 				: undefined,
@@ -620,6 +644,7 @@ export function buildResolvedRetrieve(
 	attributeSelections: readonly string[],
 	macResolution?: { mac: string; ip: string },
 	config: Record<string, string | undefined> = {},
+	quickchrResolution?: QuickchrResolution,
 ): ResolvedRetrieveRequest {
 	const via = resolveProtocol(request, env, cdbResolution, config);
 	const format = resolveFormat(request, env, config);
@@ -647,22 +672,33 @@ export function buildResolvedRetrieve(
 		undefined,
 		config,
 	);
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-	);
-	const auth = resolveAuth(
-		{ username: request.username, password: request.password },
-		env,
-		cdbResolution,
-	);
+	// A quickchr member substitutes the live descriptor's per-`--via` endpoint
+	// for the CDB/env target+auth path (`docs/CONSTITUTION.md` → Resolution
+	// providers); everything else (via/format/validate/timeout) resolved above
+	// stays on the normal ladder.
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, via.value)
+		: null;
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+					macResolution,
+				},
+				env,
+				via.value,
+				cdbResolution,
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{ username: request.username, password: request.password },
+				env,
+				cdbResolution,
+			);
 
 	return {
 		path: request.path,
@@ -672,12 +708,24 @@ export function buildResolvedRetrieve(
 		timeoutMs,
 		format,
 		validate,
+		insecure:
+			connection?.insecure === true && quickchrResolution
+				? {
+						value: true,
+						source: {
+							kind: "provider" as const,
+							key: `quickchr:${quickchrResolution.name}`,
+						},
+					}
+				: undefined,
 		maxResultsBytes,
 		attributes: attributeSelections,
 		allAttributes: request.allAttributes ?? false,
 		listAttributes: request.listAttributes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
 	};
 }
 
@@ -758,6 +806,22 @@ export async function resolveRetrieveRequest(
 	const attributeSelections = validateRetrieveRequestShape(request);
 	const config = await loadEnvFileDefaults(env);
 
+	// A quickchr target bypasses CDB and MAC resolution entirely — the live
+	// descriptor is the only connection-fact source for those fields.
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		const quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+		return buildResolvedRetrieve(
+			request,
+			env,
+			undefined,
+			attributeSelections,
+			undefined,
+			config,
+			quickchrResolution,
+		);
+	}
+
 	const cdbResolution = await resolveCdb(
 		{
 			targetInput: request.targetInput,
@@ -1129,62 +1193,3 @@ function exhaustiveOutputFormat(value: never): never {
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-
-export function toYaml(value: unknown, indent = 0): string {
-	const prefix = " ".repeat(indent);
-	if (value === null || value === undefined) {
-		return "null";
-	}
-	if (typeof value === "string") {
-		return yamlScalar(value);
-	}
-	if (typeof value === "number" || typeof value === "boolean") {
-		return String(value);
-	}
-	if (Array.isArray(value)) {
-		if (value.length === 0) {
-			return `${prefix}[]`;
-		}
-		return value
-			.map((item) => {
-				if (isScalar(item)) {
-					return `${prefix}- ${toYaml(item, indent + 2)}`;
-				}
-				return `${prefix}-\n${toYaml(item, indent + 2)}`;
-			})
-			.join("\n");
-	}
-	if (isPlainObject(value)) {
-		const entries = Object.entries(value).filter(
-			([, entryValue]) => entryValue !== undefined,
-		);
-		if (entries.length === 0) {
-			return `${prefix}{}`;
-		}
-		return entries
-			.map(([key, entryValue]) => {
-				if (isScalar(entryValue)) {
-					return `${prefix}${key}: ${toYaml(entryValue, indent + 2)}`;
-				}
-				return `${prefix}${key}:\n${toYaml(entryValue, indent + 2)}`;
-			})
-			.join("\n");
-	}
-	return yamlScalar(JSON.stringify(value));
-}
-
-function isScalar(value: unknown): value is boolean | number | string | null {
-	return (
-		value === null ||
-		typeof value === "string" ||
-		typeof value === "number" ||
-		typeof value === "boolean"
-	);
-}
-
-function yamlScalar(value: string): string {
-	if (value.length === 0) {
-		return '""';
-	}
-	return JSON.stringify(value);
-}

package/src/settings.ts

@@ -24,6 +24,7 @@ import type {
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
+import { toYaml } from "./core/yaml.ts";
 import { loadCdb, resolveDevicesSettings } from "./devices.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
@@ -37,7 +38,7 @@ import {
 	readSettingsFileRaw,
 	resolveOptionalIntegerSetting,
 } from "./resolver/index.ts";
-import { retrieveOutputFormats, toYaml } from "./retrieve.ts";
+import { retrieveOutputFormats } from "./retrieve.ts";
 
 // ── Envelope shape ───────────────────────────────────────────────────────────
 

package/src/transfer-fanout.ts

@@ -8,7 +8,7 @@
  *
  * Boundaries (see `commands/transfer/README.md`, `docs/CONSTITUTION.md`), shared
  * with `api`/`retrieve`/`execute` fan-out:
- *   - The CDB is loaded ONCE (`expandCdbSelection`); a cdb member is resolved with
+ *   - The CDB is loaded ONCE (`expandSelection`); a cdb member is resolved with
  *     its pre-resolved record, so `resolveCdb`'s `__default__` synthetic fallback
  *     never collides ad-hoc literals.
  *   - A `--default` / `__default__` member fails that one target deterministically
@@ -38,19 +38,19 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 import {
 	buildTransferErrorEnvelope,
 	isTransferWriteVerb,
@@ -71,6 +71,8 @@ export interface TransferSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface TransferFanoutRequestSummary {
@@ -101,13 +103,13 @@ export type TransferFanoutErrorEnvelope =
 export interface TransferFanoutInternals {
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	execute?: (
 		request: TransferRequest,
-		member: CdbSelectionMember,
+		member: SelectionMember,
 	) => Promise<TransferSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -127,14 +129,18 @@ function summarizeSelection(
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
-function memberLabel(member: CdbSelectionMember): string {
-	return member.kind === "cdb" ? member.resolution.identity : member.input;
+function memberLabel(member: SelectionMember): string {
+	if (member.kind === "cdb") {
+		return member.resolution.identity;
+	}
+	return member.kind === "quickchr" ? member.name : member.input;
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -146,6 +152,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -165,11 +174,11 @@ function sanitizeFilename(label: string): string {
 function planDownloadPaths(
 	outDir: string,
 	remote: string,
-	members: readonly CdbSelectionMember[],
-): Map<CdbSelectionMember, string> {
+	members: readonly SelectionMember[],
+): Map<SelectionMember, string> {
 	const ext = extname(basename(remote));
 	const used = new Set<string>();
-	const paths = new Map<CdbSelectionMember, string>();
+	const paths = new Map<SelectionMember, string>();
 	members.forEach((member, index) => {
 		const label = sanitizeFilename(memberLabel(member));
 		let name = `${label}${ext}`;
@@ -197,7 +206,7 @@ function planDownloadPaths(
  */
 function relabelAdhocMember(
 	envelope: TransferEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): TransferEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -217,7 +226,7 @@ function relabelAdhocMember(
  */
 function applyMemberMeta(
 	envelope: TransferEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): TransferEnvelope {
 	if (member.kind === "literal") {
 		return relabelAdhocMember(envelope, member);
@@ -268,7 +277,7 @@ export async function transferFanout(
 		});
 	}
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -310,7 +319,7 @@ export async function transferFanout(
 
 	const execute =
 		internals.execute ??
-		((req: TransferRequest, member: CdbSelectionMember) =>
+		((req: TransferRequest, member: SelectionMember) =>
 			transfer(req, env, {
 				// cdb members carry their pre-resolved record (CDB loaded once);
 				// literals fall through to single-target resolution.
@@ -319,8 +328,8 @@ export async function transferFanout(
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
-		CdbSelectionMember,
-		{ request: TransferRequest; member: CdbSelectionMember },
+		SelectionMember,
+		{ request: TransferRequest; member: SelectionMember },
 		TransferEnvelope
 	>({
 		members: expansion.targets,
@@ -339,9 +348,17 @@ export async function transferFanout(
 					context: { target: member.resolution.target },
 				});
 			}
-			const targetInput =
-				member.kind === "cdb" ? member.resolution.target : member.input;
-			const perRequest: TransferRequest = { ...request, targetInput };
+			// A quickchr member carries the machine name in `quickchr` (resolved live
+			// inside `resolveTransferRequest`, so a stopped machine is an inner
+			// per-target failure), never as a `targetInput`.
+			const perRequest: TransferRequest =
+				member.kind === "quickchr"
+					? { ...request, targetInput: undefined, quickchr: member.name }
+					: {
+							...request,
+							targetInput:
+								member.kind === "cdb" ? member.resolution.target : member.input,
+						};
 			if (downloadPaths !== undefined) {
 				perRequest.local = downloadPaths.get(member);
 			}
@@ -377,7 +394,7 @@ export async function transferFanout(
 
 async function assertFanoutWriteConfirmed(
 	request: TransferRequest,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): Promise<void> {
 	if (request.yes) {
 		return;
@@ -407,7 +424,7 @@ interface TransferFanoutEnvelopeInput {
 	summary: FanoutSummary;
 	requestSummary: TransferFanoutRequestSummary;
 	via: RouterOsProtocol | string | null;
-	warnings: CdbSelectionExpansion["warnings"];
+	warnings: SelectionExpansion["warnings"];
 	targets: readonly TransferEnvelope[];
 }
 

package/src/transfer.ts

@@ -29,6 +29,7 @@ import type {
 	EnvelopeValidationMeta,
 	Warning,
 } from "./core/envelope.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -38,20 +39,22 @@ import {
 import type { RouterOsProtocol } from "./protocols/index.ts";
 import { SftpClient } from "./protocols/sftp.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	loadEnvFileDefaults,
 	parseDuration,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 export const transferOutputFormats = ["text", "json", "yaml"] as const;
 export type TransferOutputFormat = (typeof transferOutputFormats)[number];
@@ -104,6 +107,12 @@ export const FILE_READ_CHUNK_BYTES = 32_768;
 export interface TransferRequest {
 	verb: TransferVerb;
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password/sshKey.
+	 */
+	quickchr?: string;
 	/** Local path (or `-` for stdin/stdout). Present for upload/download. */
 	local?: string;
 	/** RouterOS file path. Present for upload/download/remove/mkdir and copy source. */
@@ -818,19 +827,31 @@ export async function resolveTransferRequest(
 		config,
 	);
 
+	// A quickchr target is a named-live-provider: host/port/auth come from the
+	// live descriptor, bypassing CDB and the `__default__` ladder. For
+	// `--via sftp`/`scp`, `quickchrConnection` additionally gates on the SSH
+	// endpoint's batch-capable auth modes (typed error, never a password prompt).
+	let quickchrResolution: Awaited<
+		ReturnType<typeof resolveQuickchrTarget>
+	> | null = null;
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+	}
 	// Fan-out passes the pre-resolved CDB record for a member (the CDB is loaded
-	// once in `expandCdbSelection`); single-target resolves it here.
-	const cdbResolution =
-		options.cdbResolution ??
-		(await resolveCdb(
-			{
-				targetInput: request.targetInput,
-				cdbFile: request.cdbFile,
-				cdbPassword: request.cdbPassword,
-			},
-			env,
-			config,
-		));
+	// once in `expandSelection`); single-target resolves it here.
+	const cdbResolution = quickchrResolution
+		? undefined
+		: (options.cdbResolution ??
+			(await resolveCdb(
+				{
+					targetInput: request.targetInput,
+					cdbFile: request.cdbFile,
+					cdbPassword: request.cdbPassword,
+				},
+				env,
+				config,
+			)));
 
 	const format = resolveTransferFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -842,15 +863,6 @@ export async function resolveTransferRequest(
 		cdbResolution?.overrides.validate,
 		config,
 	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-		config,
-	);
 	const timeoutMs = resolveTransferTimeout(
 		request.timeout,
 		env,
@@ -858,30 +870,59 @@ export async function resolveTransferRequest(
 		cdbResolution,
 		config,
 	);
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-		},
-		env,
-		protocol,
-		cdbResolution,
-		config,
-	);
-	const auth = resolveAuth(
-		{
-			username: request.username,
-			password: request.password,
-			sshKey: request.sshKey,
-		},
-		env,
-		cdbResolution,
-		config,
-	);
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, protocol)
+		: null;
+	// A quickchr TLS/SSH endpoint is trusted by provenance (self-signed VM cert /
+	// ephemeral host key) — `insecure` is forced with provider provenance and the
+	// provider-trust warning replaces the generic `--insecure` anomaly warning.
+	const insecure =
+		connection?.insecure === true
+			? {
+					value: true,
+					source: {
+						kind: "provider" as const,
+						key: `quickchr:${request.quickchr}`,
+					},
+				}
+			: resolveBooleanSetting(
+					request.insecure,
+					env,
+					"CENTRS_INSECURE",
+					false,
+					"insecure",
+					cdbResolution?.overrides.insecure,
+					config,
+				);
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+				},
+				env,
+				protocol,
+				cdbResolution,
+				config,
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{
+					username: request.username,
+					password: request.password,
+					sshKey: request.sshKey,
+				},
+				env,
+				cdbResolution,
+				config,
+			);
 
 	const warnings: Warning[] = [
 		...((cdbResolution?.warnings ?? []) as readonly Warning[]),
+		...(connection?.warnings ?? []),
 	];
 	// Report the auto hop: a large upload cannot ride the REST family's 60 KB
 	// `/file/set` cap, so auto-selection moved it to sftp.
@@ -892,8 +933,10 @@ export async function resolveTransferRequest(
 				"Large upload (>60 KB) auto-selected sftp; the REST family cannot write past the 60 KB `/file/set` cap.",
 		});
 	}
-	// A self-signed-accepting run is an anomaly worth surfacing on every transport.
-	if (insecure.value) {
+	// A self-signed-accepting run is an anomaly worth surfacing on every
+	// transport — unless the trust came from the provider, whose own
+	// provider-trust warning already rides above.
+	if (insecure.value && connection?.insecure !== true) {
 		warnings.push({
 			code: "transport/insecure-trust",
 			message: