@tikoci/centrs 0.1.3 → 0.1.6

package/src/resolver/selection.ts

@@ -54,7 +54,7 @@ export interface SelectionWhereClause {
 	value: string;
 }
 
-/** The parsed target selection a command hands to {@link expandCdbSelection}. */
+/** The parsed target selection a command hands to {@link expandSelection}. */
 export interface TargetSelection {
 	/** Literal/lookup positionals (NOT operation args — the caller splits those). */
 	positionals: readonly string[];
@@ -70,23 +70,41 @@ export interface TargetSelection {
 	near?: NearPredicate;
 	/** `--bbox <south>,<west>,<north>,<east>`: a geo union predicate (device GPS in box). */
 	bbox?: BboxPredicate;
+	/**
+	 * Repeatable `--quickchr <name>`: quickchr machine names (the named-live-
+	 * provider, #134). Exclusive in v1 — a selection targets quickchr machines OR
+	 * CDB/literals, never both; the CLI enforces the usage error before expansion
+	 * and {@link expandSelection} re-asserts it.
+	 */
+	quickchr?: readonly string[];
 }
 
-export interface CdbSelectionResolveInput {
+export interface SelectionResolveInput {
 	cdbFile?: string;
 	cdbPassword?: string;
 	/** CLI: true (literal positionals allowed). MCP: false (CDB is the allowlist). */
 	allowAdhoc: boolean;
 }
 
-/** One resolved selection member: a CDB record or an ad-hoc literal target. */
-export type CdbSelectionMember =
+/**
+ * One resolved selection member: a CDB record or an ad-hoc literal target.
+ *
+ * This is the connection-fact origin ("Axis B") the fan-out callers consume. The
+ * selector-source (CDB) and literal arms carry a single endpoint materialized
+ * later by `./target.ts`. The `quickchr` arm is the named-live-provider (#134):
+ * it carries only the machine NAME here — the live descriptor is resolved in the
+ * per-member fan-out `resolve()` path (via `resolveQuickchrTarget`), so a
+ * stopped/unknown machine is an inner per-target failure, not an expansion
+ * error — see `docs/CONSTITUTION.md` → Resolution providers.
+ */
+export type SelectionMember =
 	| { kind: "cdb"; resolution: CdbResolution; recordIndex: number }
-	| { kind: "literal"; input: string };
+	| { kind: "literal"; input: string }
+	| { kind: "quickchr"; name: string };
 
-export interface CdbSelectionExpansion {
+export interface SelectionExpansion {
 	/** Members ordered by record index; literals appended in positional order. */
-	targets: readonly CdbSelectionMember[];
+	targets: readonly SelectionMember[];
 	warnings: readonly ResolverWarning[];
 	/** True when nothing matched (an empty/unknown selection is not an error). */
 	empty: boolean;
@@ -113,12 +131,16 @@ const ENV_CDB_PASSWORD = "CENTRS_CDB_PASSWORD";
  * literal host when no CDB is present). An explicit `--cdb-file` that is missing
  * still throws.
  */
-export async function expandCdbSelection(
+export async function expandSelection(
 	selection: TargetSelection,
-	input: CdbSelectionResolveInput,
+	input: SelectionResolveInput,
 	env: Record<string, string | undefined>,
 	config: Record<string, string | undefined> = {},
-): Promise<CdbSelectionExpansion> {
+): Promise<SelectionExpansion> {
+	const quickchrNames = selection.quickchr ?? [];
+	if (quickchrNames.length > 0) {
+		return expandQuickchrSelection(selection, input, quickchrNames);
+	}
 	const settings = resolveDevicesSettings({
 		cdbFile: input.cdbFile,
 		cdbPassword: input.cdbPassword,
@@ -224,7 +246,7 @@ export async function expandCdbSelection(
 		}
 	}
 
-	const literals: CdbSelectionMember[] = [];
+	const literals: SelectionMember[] = [];
 	const seenLiteral = new Set<string>();
 	for (const positional of selection.positionals) {
 		try {
@@ -255,7 +277,7 @@ export async function expandCdbSelection(
 		}
 	}
 
-	const cdbMembers: CdbSelectionMember[] = [...indices]
+	const cdbMembers: SelectionMember[] = [...indices]
 		.sort((a, b) => a - b)
 		.map((index) => ({
 			kind: "cdb",
@@ -302,3 +324,68 @@ export async function expandCdbSelection(
 
 	return { targets, warnings, empty: false };
 }
+
+/**
+ * Expand a quickchr-only selection. No CDB is loaded — a named-live-provider
+ * member never touches the registry, the `__default__` ladder, or the selector
+ * grammar. Members carry only the machine name (de-duped by exact name, flag
+ * order preserved); the live descriptor resolves per member inside the fan-out.
+ *
+ * Two guards are load-bearing:
+ *   - Exclusivity (v1): mixing `--quickchr` with selectors/positionals is a
+ *     usage error. The CLI throws first with flag-level wording; this re-assert
+ *     protects library/MCP callers that build a {@link TargetSelection} directly.
+ *   - `allowAdhoc: false` (the MCP surface) rejects quickchr members entirely:
+ *     the CDB is the MCP allowlist, and a live provider must not widen it (#134
+ *     non-goal).
+ */
+function expandQuickchrSelection(
+	selection: TargetSelection,
+	input: SelectionResolveInput,
+	names: readonly string[],
+): SelectionExpansion {
+	if (!input.allowAdhoc) {
+		throw new CentrsError({
+			code: "cdb/target-not-registered",
+			summary:
+				"quickchr targets are not available on this surface; the CDB is the allowlist.",
+			remediation:
+				"Register the device with `centrs devices add` and select it by identity, or use the CLI for `--quickchr` targets.",
+			context: { quickchr: [...names] },
+		});
+	}
+	if (
+		selection.positionals.length > 0 ||
+		selection.groups.length > 0 ||
+		selection.all ||
+		selection.default ||
+		selection.where.length > 0 ||
+		selection.near !== undefined ||
+		selection.bbox !== undefined
+	) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"`--quickchr` is exclusive: a command targets quickchr machines or CDB/literal targets, not both.",
+			remediation:
+				"Drop the positional/selector (or the `--quickchr` flag) so the selection has one target source.",
+			context: {
+				quickchr: [...names],
+				positionals: selection.positionals.length,
+				groups: selection.groups.length,
+				all: selection.all,
+				default: selection.default,
+				where: selection.where.length,
+			},
+		});
+	}
+	const seen = new Set<string>();
+	const targets: SelectionMember[] = [];
+	for (const name of names) {
+		if (!seen.has(name)) {
+			seen.add(name);
+			targets.push({ kind: "quickchr", name });
+		}
+	}
+	return { targets, warnings: [], empty: false };
+}

package/src/resolver/service-endpoint.ts

@@ -0,0 +1,155 @@
+/**
+ * The neutral per-service endpoint shape — the connection-fact origin ("Axis B")
+ * for a resolved target, decoupled from *how* the member was selected ("Axis A").
+ *
+ * This is the load-bearing scaffold for the resolution-provider refactor
+ * (`docs/CONSTITUTION.md` → Resolution providers; centrs #174). Two provider
+ * kinds feed it:
+ *
+ *   - **Selector-source** — participates in the `--group`/`--where`/`--all`/
+ *     `--near`/`--bbox` selector grammar. **CDB** today; **TikTOML** next (#137).
+ *     CDB is the *degenerate single-endpoint* case: one record yields one
+ *     host/port/auth, materialized lazily by `./target.ts` once `--via` is known,
+ *     so a CDB member never needs a populated {@link ServiceEndpointMap}.
+ *   - **Named-live-provider** — addressed only by an explicit named flag, never
+ *     matched by selectors, fanned out by repeating the flag; owns an ephemeral
+ *     endpoint so it also bypasses the settings/`__default__` ladder and conflicts
+ *     with `--host`/`--port`/`--username`/`--password`/`--ssh-key`. **quickchr**
+ *     (`--quickchr <name>`, #134). A live provider resolves a member into a
+ *     *populated* per-service map, because it genuinely exposes different
+ *     host/port/auth per transport (e.g. a SLiRP-forwarded loopback port per
+ *     service). Flattening that to a single host/port is the exact refactor #174
+ *     exists to prevent — TikTOML's `services` block is per-service too.
+ *
+ * The shape here deliberately mirrors quickchr's published descriptor contract
+ * (`tikoci/quickchr` `docs/centrs-interface.md`, `ServiceEndpoint`/
+ * `SshServiceEndpoint`), which states that centrs reuses *this same internal
+ * type* for TikTOML resolution. It is provider-neutral: `source.provider` is a
+ * free string, not a quickchr literal. Mapping a resolved endpoint's auth onto
+ * centrs' {@link ../resolver/target.ts | ResolvedAuth} (notably
+ * `privateKeyPath` → `sshKey`) is the provider adapter's job, not this type's.
+ *
+ * Phase 1 (this file) defines the contract only; the quickchr provider adapter
+ * that *produces* a map, and the `--via` consumer that *reads* `map[via]`, land
+ * with the `--quickchr` plumbing (#134 Phase 2+).
+ */
+
+import type { RouterOsProtocol } from "../protocols/index.ts";
+
+/** Provenance for a resolved endpoint — which provider vouched for it. */
+export interface ServiceEndpointSource {
+	/** Provider identity, e.g. `"quickchr"` or `"tiktoml"`. Neutral by design. */
+	provider: string;
+	/** Provider-internal forward name backing the service (e.g. `"api-ssl"`), for provenance. */
+	portMappingName?: string;
+}
+
+/** REST/native-api auth. RouterOS shares one credential across REST and native. */
+export interface ServiceEndpointAuth {
+	username: string;
+	password?: string;
+	/** Pre-encoded HTTP Basic value, when the provider supplies one directly. */
+	basic?: string;
+	/** Pre-formed auth header value, when the provider supplies one directly. */
+	header?: string;
+}
+
+/** SSH auth. Same credential vocabulary `+ key path`, plus batch-mode capability. */
+export interface SshEndpointAuth {
+	username: string;
+	/**
+	 * Path to a usable private key. Populated only when the provider has actually
+	 * verified a batch (non-interactive) login with it — maps to
+	 * {@link ../resolver/target.ts | ResolvedAuth.sshKey} in the provider adapter.
+	 */
+	privateKeyPath?: string;
+	/** Every auth mode the endpoint accepts. */
+	modes: Array<"private-key" | "agent-or-config" | "password">;
+	/**
+	 * The batch-capable subset. This is the gate centrs enforces for `--via ssh`
+	 * and `transfer --via sftp`: an empty list means no non-interactive handoff is
+	 * possible, so centrs must emit a typed unsupported-capability error rather
+	 * than prompt for a password or silently fall back (#134 Phase 4).
+	 */
+	batchModes: Array<"private-key" | "agent-or-config">;
+	passwordAvailable?: boolean;
+}
+
+/** Fields shared by every available endpoint regardless of auth flavor. */
+interface AvailableEndpointBase {
+	available: true;
+	/** Hostname/IP to dial — NOT a port. `"127.0.0.1"` for a SLiRP-forwarded service. */
+	host: string;
+	port: number;
+	guestPort?: number;
+	transport: "tcp" | "udp";
+	/** True for TLS-backed endpoints (https / api-ssl); SSH is always `false` (own transport security). */
+	tls: boolean;
+	url?: string;
+	source?: ServiceEndpointSource;
+}
+
+/** An endpoint the provider could not vouch for; a consumer MUST gate on `available` before dialing. */
+export interface UnavailableEndpoint {
+	available: false;
+	unavailableReason: string;
+	/** Best-effort echoes only — never dial these without a re-resolve. */
+	host?: string;
+	port?: number;
+	guestPort?: number;
+	transport?: "tcp" | "udp";
+	tls?: boolean;
+	url?: string;
+	source?: ServiceEndpointSource;
+}
+
+/** One per-service endpoint (rest-api / native-api). */
+export type ServiceEndpoint =
+	| (AvailableEndpointBase & { auth?: ServiceEndpointAuth })
+	| UnavailableEndpoint;
+
+/** The SSH endpoint — same union, with SSH-specific auth substituted. */
+export type SshServiceEndpoint =
+	| (AvailableEndpointBase & { auth: SshEndpointAuth })
+	| UnavailableEndpoint;
+
+/** Any resolved endpoint, whatever the service. */
+export type AnyServiceEndpoint = ServiceEndpoint | SshServiceEndpoint;
+
+/**
+ * The endpoint type for a given `--via` id. `ssh` carries the SSH-specific
+ * {@link SshServiceEndpoint} (its available form guarantees `auth: SshEndpointAuth`
+ * with `batchModes`, the gate Phase 4 enforces for `--via ssh`/`transfer --via
+ * sftp`); every other transport uses the shared credential {@link ServiceEndpoint}.
+ */
+export type ServiceEndpointFor<K extends RouterOsProtocol> = K extends "ssh"
+	? SshServiceEndpoint
+	: ServiceEndpoint;
+
+/**
+ * A member's per-service connection facts, keyed by centrs `--via` id.
+ *
+ * Partial by design: a provider may cover only a subset of the eight protocols
+ * (quickchr v1 covers `rest-api`/`native-api`/`ssh`). A `--via` whose key is
+ * absent is a typed unsupported-provider error at consume time, not a silent
+ * fallback. CDB never populates this map (its single endpoint is materialized by
+ * `./target.ts`); only named-live-providers do.
+ *
+ * Keyed by service so per-`--via` precision survives: `map.ssh` is a
+ * {@link SshServiceEndpoint}, not a widened `AnyServiceEndpoint`, so a consumer
+ * reading `map.ssh` keeps the SSH `auth`/`batchModes` guarantee without a cast.
+ */
+export type ServiceEndpointMap = {
+	[K in RouterOsProtocol]?: ServiceEndpointFor<K>;
+};
+
+/**
+ * Narrow an endpoint to its available form (the only form safe to dial). Generic
+ * so the caller's precise union is preserved: an {@link SshServiceEndpoint} narrows
+ * to its available arm (`auth: SshEndpointAuth` required), not the widened base.
+ */
+export function isEndpointAvailable<T extends AnyServiceEndpoint>(
+	endpoint: T,
+): endpoint is Extract<T, { available: true }> {
+	return endpoint.available;
+}

package/src/resolver/target.ts

@@ -455,6 +455,6 @@ export function defaultPortForScheme(scheme: "http" | "https"): number {
 	return scheme === "https" ? 443 : 80;
 }
 
-function formatHostForUrl(host: string): string {
+export function formatHostForUrl(host: string): string {
 	return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }

package/src/retrieve-fanout.ts

@@ -12,7 +12,7 @@
  *
  * Boundaries (see `commands/retrieve/README.md`, `docs/CONSTITUTION.md`), shared
  * with `api-fanout.ts`:
- *   - The CDB is loaded + decrypted ONCE (`expandCdbSelection`); a cdb member is
+ *   - The CDB is loaded + decrypted 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 is guarded from being dialed as the
@@ -46,15 +46,16 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.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 {
@@ -71,7 +72,6 @@ import {
 	resolveRetrieveGlobalContext,
 	resolveRetrieveRequest,
 	runResolvedRetrieve,
-	toYaml,
 	validateRetrieveRequestShape,
 } from "./retrieve.ts";
 
@@ -82,6 +82,8 @@ export interface RetrieveSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface RetrieveFanoutOperationMeta {
@@ -109,10 +111,10 @@ export interface RetrieveFanoutInternals {
 	/** Selection expansion. Defaults to the real CDB-backed expansion. */
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	/** Backoff sleeper. Defaults to a real timer; tests pass a no-op. */
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -132,10 +134,11 @@ function summarizeSelection(
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -147,6 +150,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -159,7 +165,7 @@ function memberTargetMeta(member: CdbSelectionMember): {
  */
 function relabelAdhocMember(
 	envelope: RetrieveEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): RetrieveEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -194,7 +200,7 @@ export async function retrieveFanout(
 	);
 	const selectionSummary = summarizeSelection(selection);
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -234,7 +240,7 @@ export async function retrieveFanout(
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
-		CdbSelectionMember,
+		SelectionMember,
 		ResolvedRetrieveRequest,
 		RetrieveEnvelope
 	>({
@@ -267,6 +273,14 @@ export async function retrieveFanout(
 					config,
 				);
 			}
+			if (member.kind === "quickchr") {
+				// The live descriptor resolves here, per member — a stopped/unknown
+				// machine is an inner per-target failure, not an expansion error.
+				return resolveRetrieveRequest(
+					{ ...request, targetInput: undefined, quickchr: member.name },
+					env,
+				);
+			}
 			// Ad-hoc literal: full single-target resolution (CDB load → `__default__`
 			// fallback creds), mirroring single-target `retrieve`.
 			return resolveRetrieveRequest(
@@ -373,7 +387,7 @@ function resolveFanoutConcurrencyProtocol(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
 	globalVia: RouterOsProtocol,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): RouterOsProtocol {
 	// Deliberately CLI/env only, not `config` — a `centrs.env` default is the
 	// weakest precedence tier and must not be treated as a hard pin the way an