@tikoci/centrs 0.1.1 → 0.1.3

package/src/transfer.ts

@@ -39,6 +39,7 @@ import type { RouterOsProtocol } from "./protocols/index.ts";
 import { SftpClient } from "./protocols/sftp.ts";
 import {
 	type CdbResolution,
+	loadEnvFileDefaults,
 	parseDuration,
 	type ResolvedAuth,
 	type ResolvedSetting,
@@ -66,6 +67,20 @@ export const transferVerbs = [
 ] as const;
 export type TransferVerb = (typeof transferVerbs)[number];
 
+/**
+ * Verbs that mutate the device (write path) — gated by `--yes` once up front in a
+ * fan-out. `download`/`list` only read the device (a download writes the *local*
+ * filesystem, not the router).
+ */
+export function isTransferWriteVerb(verb: TransferVerb): boolean {
+	return (
+		verb === "upload" ||
+		verb === "remove" ||
+		verb === "mkdir" ||
+		verb === "copy"
+	);
+}
+
 /**
  * `--via` method names. These are transfer *methods*, finer than the grid
  * transport: `rest`/`native` ride rest-api/native-api; `sftp`/`scp` ride ssh;
@@ -120,6 +135,14 @@ export interface TransferRequest {
 	name?: string;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/** `download` fan-out: directory to write one file per target into. */
+	outDir?: string;
+	/** Fan-out write gate: confirm a mutating fan-out (upload/remove/mkdir/copy). */
+	yes?: boolean;
+	/** Fan-out TTY detection seam (defaults to `process.stdin.isTTY`). */
+	stdinIsTty?: boolean;
+	/** Fan-out confirmation prompt seam (defaults to the shared TTY prompt). */
+	confirm?: (prompt: string) => Promise<boolean>;
 }
 
 export type TransferOp = TransferVerb;
@@ -190,8 +213,9 @@ interface ResolvedTransferRequest {
 export async function transfer(
 	request: TransferRequest,
 	env: Record<string, string | undefined> = Bun.env,
+	options: { cdbResolution?: CdbResolution } = {},
 ): Promise<TransferSuccessEnvelope> {
-	const resolved = await resolveTransferRequest(request, env);
+	const resolved = await resolveTransferRequest(request, env, options);
 	const backend = createFileBackend(resolved);
 	try {
 		return await runResolvedTransfer(resolved, backend);
@@ -778,8 +802,10 @@ function verifyReadSize(
 export async function resolveTransferRequest(
 	request: TransferRequest,
 	env: Record<string, string | undefined>,
+	options: { cdbResolution?: CdbResolution } = {},
 ): Promise<ResolvedTransferRequest> {
 	validateTransferRequestShape(request);
+	const config = await loadEnvFileDefaults(env);
 
 	const direction: TransferDirection =
 		request.verb === "upload" ? "upload" : "download";
@@ -789,18 +815,24 @@ export async function resolveTransferRequest(
 		direction,
 		sizeHint,
 		env,
+		config,
 	);
 
-	const cdbResolution = await resolveCdb(
-		{
-			targetInput: request.targetInput,
-			cdbFile: request.cdbFile,
-			cdbPassword: request.cdbPassword,
-		},
-		env,
-	);
+	// 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,
+		));
 
-	const format = resolveTransferFormat(request, env);
+	const format = resolveTransferFormat(request, env, config);
 	const validate = resolveBooleanSetting(
 		request.validate,
 		env,
@@ -808,6 +840,7 @@ export async function resolveTransferRequest(
 		true,
 		"validate",
 		cdbResolution?.overrides.validate,
+		config,
 	);
 	const insecure = resolveBooleanSetting(
 		request.insecure,
@@ -816,12 +849,14 @@ export async function resolveTransferRequest(
 		false,
 		"insecure",
 		cdbResolution?.overrides.insecure,
+		config,
 	);
 	const timeoutMs = resolveTransferTimeout(
 		request.timeout,
 		env,
 		protocol,
 		cdbResolution,
+		config,
 	);
 	const target = resolveTarget(
 		{
@@ -832,6 +867,7 @@ export async function resolveTransferRequest(
 		env,
 		protocol,
 		cdbResolution,
+		config,
 	);
 	const auth = resolveAuth(
 		{
@@ -841,6 +877,7 @@ export async function resolveTransferRequest(
 		},
 		env,
 		cdbResolution,
+		config,
 	);
 
 	const warnings: Warning[] = [
@@ -900,6 +937,7 @@ export function selectTransferMethod(
 	direction: TransferDirection,
 	uploadBytes: number | undefined,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): {
 	method: TransferMethod;
 	protocol: RouterOsProtocol;
@@ -911,6 +949,9 @@ export function selectTransferMethod(
 		"CENTRS_TRANSFER_VIA",
 		"auto",
 		"via",
+		undefined,
+		undefined,
+		config,
 	) as ResolvedSetting<string>;
 	const requested = via.value;
 
@@ -1062,6 +1103,7 @@ function parseVerifyMode(
 function resolveTransferFormat(
 	request: TransferRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<TransferOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -1079,6 +1121,8 @@ function resolveTransferFormat(
 				remediation: `Choose one of ${transferOutputFormats.join(", ")}.`,
 			});
 		},
+		undefined,
+		config,
 	) as ResolvedSetting<TransferOutputFormat>;
 }
 
@@ -1087,6 +1131,7 @@ function resolveTransferTimeout(
 	env: Record<string, string | undefined>,
 	protocol: RouterOsProtocol,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -1106,6 +1151,7 @@ function resolveTransferTimeout(
 			return parsed;
 		},
 		cdb?.overrides.timeoutMs,
+		config,
 	) as ResolvedSetting<number>;
 
 	if (protocol === "rest-api" && resolved.value > 60_000) {
@@ -1156,7 +1202,11 @@ function writeLocalSink(
 		process.stdout.write(bytes);
 		return;
 	}
-	writeFileSync(local, bytes);
+	// Downloaded RouterOS artifacts (backups/exports) can carry credentials,
+	// so a newly created destination file gets owner-only permissions
+	// instead of the process umask default. Mode only applies on creation —
+	// an existing destination keeps its current permissions.
+	writeFileSync(local, bytes, { mode: 0o600 });
 }
 
 function localLabel(resolved: ResolvedTransferRequest): string {

package/commands/stream/README.md

@@ -1,70 +0,0 @@
-# stream
-
-Follow live RouterOS output — `print follow`, `monitor`-style commands, and
-sniffer feeds — as a stream of envelopes.
-
-Status: `designed`. This file describes intent and flags; no implementation yet.
-See `docs/MATRIX.md` for the cell states. `stream` lands with a transport that
-can hold an open read (native-api first, then ssh); it is **not** a REST cell.
-
-## Why a separate verb
-
-`stream` exists because open-ended follow is a different I/O contract than a
-one-shot read, and conflating it into `retrieve` would force every retrieve
-consumer to handle "maybe this is a stream." A caller that picks `stream` knows
-it is getting a sequence of frames, not a single envelope. Bounded, finite
-captures stay on `retrieve` (`--once`); interactive PTY stays on `terminal`
-(constitution: protocol selection).
-
-## Intent
-
-- **Read-only**, validated like `retrieve` (path-shaped commands gate through
-  `/console/inspect`). `stream` never writes.
-- Wraps RouterOS follow semantics: `once`, `follow`, `duration=`,
-  `freeze-frame-interval=`. Targets are the `monitor`/`print follow`/sniffer
-  family of menus.
-- **Transport:** true follow cannot ride REST (RouterOS REST has a 60s hard
-  cap), so `stream` is **native-api / ssh-first**. `--via rest-api` is
-  bounded-or-rejected, never a silent open-ended poll.
-- Not a fan-out surface in single-session mode: a single `stream` rejects N>1
-  targets with `usage/fanout-not-supported` (constitution: target selection).
-
-## Output contract (NDJSON stream of envelopes)
-
-- Each frame is **one envelope** (`{ ok, data?, warnings?, error?, meta }`),
-  emitted as one NDJSON line under `--format json`. Text mode renders
-  human-readable frames.
-- The stream is terminated by a final **summary envelope**: frame count,
-  duration, and stop reason (`duration-elapsed`, `interrupted`, `eof`,
-  `transport-error`).
-- A mid-stream RouterOS or transport error is itself a frame with `ok: false`;
-  the **process exit code** reflects whether the stream *started* cleanly, not
-  whether every frame was `ok`.
-- `--duration` / `--count` bound an otherwise open-ended follow; Ctrl-C stops it
-  and still emits the summary envelope.
-
-## Flags (planned)
-
-| Flag | Behavior |
-| ---- | -------- |
-| `--via <protocol>` | Pin transport (`native-api` or `ssh`). REST is bounded-or-rejected. |
-| `--duration <dur>` | Stop after this wall-clock window (maps to RouterOS `duration=`). |
-| `--count <n>` | Stop after N frames. |
-| `--freeze-frame-interval <dur>` | RouterOS `freeze-frame-interval=` passthrough. |
-| `--format <text\|json>` | `json` is NDJSON (one envelope per line); `text` is human frames. |
-
-`tail` is a log-scoped alias: `centrs tail <router> /log` ≈ `tail -f` over
-`/log print follow`.
-
-## Open questions
-
-- Whether `stream` over ssh shells out to the RouterOS CLI follow or rides a
-  structured channel; settle during the SSH transport work.
-- Backpressure / max-buffered-frames policy for a fast producer.
-
-Sequencing (decided): do **not** start `stream` until (1) a native-api
-*streaming* spike confirms the reader is solid as a long-lived follow channel
-(not just request/response), and (2) `retrieve` is further along and re-reviewed
-for UX — `stream` should inherit a settled retrieve shape, not race it. The
-native-api streaming reader already exists (`src/protocols/native-api.ts`) and is
-the first follow consumer.