@voltro/cli 0.41.0 → 0.42.0

package/dist/{dataCommand-OKC5FscP.js → dataCommand-Rj57y1vg.js}

@@ -2,24 +2,24 @@ import { t as e } from "./cliError-BmdYnghb.js";
 import { c as t, i as n, o as r } from "./dev-D4l_YOzI.js";
 import { n as i, t as a } from "./cliArgs-D4p8n7EE.js";
 import { r as o } from "./dialectDriver-czCHYpeH.js";
-import { t as s } from "./dataProfile-dW-PsfLB.js";
+import { t as s } from "./dataProfile-Cm0YVKSy.js";
 import { o as c, t as l } from "./inspectFetch-EMuhTG_9.js";
-import { r as u } from "./dbCommand-BHRamDsy.js";
+import { r as u } from "./dbCommand-B237qI-j.js";
 import { createLogger as d } from "@voltro/logger";
 import { Effect as f, Stream as p } from "effect";
 import { SqlClient as m } from "@effect/sql";
 import { declaredSnapshot as h, fingerprintSchema as g, introspectSchema as _ } from "@voltro/database/sql";
 import { connectionIdentity as v, normaliseTarget as y, sameDatabase as b, streamTable as x } from "@voltro/database";
 import { STORAGE_REFS_TABLE as ee, resolveStorageProvider as S } from "@voltro/plugin-storage";
-import { assessLiveImport as te, backupArtifactName as C, backupCommand as ne, classificationFromSnapshot as re, decryptStream as w, encryptStream as ie, packBundle as T, peekBundle as E, previewMasking as ae, restoreCommand as D, runExport as O, runImport as k, runNativeStep as A, storageAssetSink as j, storageAssetSource as oe, storageBlobSink as se, storageBlobSource as ce, unpackBundle as le, unpackBundleToDir as M } from "@voltro/data-transfer";
+import { assessLiveImport as te, backupArtifactName as C, backupCommand as ne, classificationFromSnapshot as re, decryptStream as w, encryptStream as ie, packBundle as T, peekBundle as E, previewMasking as ae, restoreCommand as D, runExport as O, runImport as k, runNativeStep as A, storageAssetSink as oe, storageAssetSource as se, storageBlobSink as ce, storageBlobSource as le, unpackBundle as ue, unpackBundleToDir as j } from "@voltro/data-transfer";
 //#region src/backupStamp.ts
-var N = "voltro-backup-stamp.json", ue = (e) => ({
+var M = "voltro-backup-stamp.json", de = (e) => ({
 	stampVersion: 1,
 	dialect: e.dialect,
 	schemaFingerprint: e.schemaFingerprint,
 	voltroVersion: e.voltroVersion,
 	createdAt: e.createdAt
-}), P = (e) => {
+}), N = (e) => {
 	let t;
 	try {
 		t = JSON.parse(e);
@@ -37,10 +37,10 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		voltroVersion: n.voltroVersion,
 		createdAt: n.createdAt
 	};
-}, de = (e) => {
+}, fe = (e) => {
 	let { stamp: t, currentDialect: n, currentFingerprint: r } = e;
 	if (t === null) return {
-		warn: `no ${N} beside the dump — an older/handmade backup. Cannot verify dialect or schema version; make sure this dump is a ${n} dump.`,
+		warn: `no ${M} beside the dump — an older/handmade backup. Cannot verify dialect or schema version; make sure this dump is a ${n} dump.`,
 		info: []
 	};
 	let i = [`backup produced by @voltro/cli ${t.voltroVersion} at ${t.createdAt}`, `schema fingerprint: ${t.schemaFingerprint ?? "<none recorded>"}`];
@@ -51,20 +51,20 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		refuse: `dialect mismatch — backup is a ${t.dialect} dump, but DB_DIALECT is ${n}. A cross-dialect restore is never valid.`,
 		info: i
 	};
-}, F = (e) => {
+}, P = (e) => {
 	try {
 		let t = new URL(e), n = t.pathname.replace(/^\//, "");
 		return `${t.hostname.toLowerCase()}:${t.port || "(default)"}/${n}`;
 	} catch {
 		return e.trim();
 	}
-}, fe = (e) => {
+}, pe = (e) => {
 	let t = e.flagUrl ?? e.envUrl;
 	if (t === void 0 || t.trim() === "") return {
 		ok: !1,
 		error: "no drill target — pass `--drill-url <url>` or set `DRILL_DB_URL`. The drill restores into a THROWAWAY database (never the live one), so it needs its own connection."
 	};
-	let n = F(t);
+	let n = P(t);
 	return e.liveKeys.some((e) => e === n) ? {
 		ok: !1,
 		error: `drill target (${n}) is the LIVE database — a restore drill must target a throwaway DB, never production. It would --clean and overwrite it.`
@@ -72,7 +72,7 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		ok: !0,
 		url: t
 	};
-}, pe = (e) => {
+}, me = (e) => {
 	let { stampFingerprint: t, restoredFingerprint: n, restoredTableCount: r } = e;
 	return r === 0 ? {
 		pass: !1,
@@ -87,24 +87,24 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		pass: !0,
 		lines: [`PASS — restored ${r} table(s); schema fingerprint matches the backup stamp (${n.slice(0, 12)}).`]
 	};
-}, I = d({ scope: "voltro:data" }), me = async () => {
+}, F = d({ scope: "voltro:data" }), he = async () => {
 	try {
 		let { createRequire: e } = await import("node:module"), { join: t } = await import("node:path"), { readFileSync: n } = await import("node:fs"), r = e(t(process.cwd(), "package.json")).resolve("@voltro/cli/package.json");
 		return JSON.parse(n(r, "utf8")).version ?? "unknown";
 	} catch {
 		return "unknown";
 	}
-}, L = async (e) => {
+}, I = async (e) => {
 	try {
-		return g(await G(e));
+		return g(await U(e));
 	} catch {
 		return null;
 	}
-}, R = (e) => {
+}, L = (e) => {
 	if (e.event !== "done") return;
 	let t = e.total === void 0 ? "" : ` / ${e.total}`;
-	I.info(`${e.phase} [${e.index + 1}/${e.tableCount}] ${e.table}`, { rows: `${e.rowsDone}${t}` });
-}, z = async (e) => {
+	F.info(`${e.phase} [${e.index + 1}/${e.tableCount}] ${e.table}`, { rows: `${e.rowsDone}${t}` });
+}, ge = async (e) => {
 	let t = (e) => e?.meta?.databaseId;
 	if (e) {
 		let n = await l({
@@ -124,12 +124,12 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		};
 	}
 	return null;
-}, B = async (e) => {
-	let t = e.includes("--allow-live"), n = t ? null : await z(V(e, "--api-url")), i = v({
-		dialect: U(),
+}, R = async (e) => {
+	let t = e.includes("--allow-live"), n = t ? null : await ge(z(e, "--api-url")), i = v({
+		dialect: V(),
 		...r()
 	}), a = y({
-		dialect: U(),
+		dialect: V(),
 		...r()
 	}), { refuse: o, message: s } = te({
 		liveInstance: n?.label ?? null,
@@ -137,8 +137,8 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		sameTarget: b(i, n?.databaseId),
 		...a === void 0 ? {} : { targetLabel: `${a.host}:${a.port}/${a.database}` }
 	});
-	return !o || (I.error(s ?? "refusing: live instance detected"), !1);
-}, V = i, he = [
+	return !o || (F.error(s ?? "refusing: live instance detected"), !1);
+}, z = i, _e = [
 	"--api-url",
 	"--bundle-key",
 	"--compression",
@@ -153,44 +153,44 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 	"--target",
 	"--tenant",
 	"--token"
-], H = (e) => a(e, he), U = () => {
+], B = (e) => a(e, _e), V = () => {
 	let t = (process.env.DB_DIALECT ?? "postgres").toLowerCase();
 	if (t === "memory") throw new e("voltro data: requires a real dialect, not DB_DIALECT=memory.");
 	return t;
-}, W = async (e, t) => {
+}, H = async (e, t) => {
 	let n = (await o(e)).makeSqlLayer(t);
 	return f.runPromise(m.SqlClient.pipe(f.flatMap(_), f.provide(n)));
-}, G = (e) => W(e, r()), ge = () => {
+}, U = (e) => H(e, r()), ve = () => {
 	let e = r(), t = [];
-	return e.url && t.push(F(e.url)), (e.host || e.database) && t.push(`${(e.host ?? "localhost").toLowerCase()}:${e.port ?? "(default)"}/${e.database ?? ""}`), t;
-}, K = async () => {
+	return e.url && t.push(P(e.url)), (e.host || e.database) && t.push(`${(e.host ?? "localhost").toLowerCase()}:${e.port ?? "(default)"}/${e.database ?? ""}`), t;
+}, ye = async () => {
 	let r = process.cwd(), i = await t(r);
 	if (!i) throw new e("voltro data: no app.config.ts found in the current directory.");
-	let a = await n(i, void 0), o = U();
+	let a = await n(i, void 0), o = V();
 	return {
 		store: a,
-		snapshot: await G(o),
+		snapshot: await U(o),
 		dialect: o
 	};
-}, q = (e) => x(e, {
+}, W = (e) => x(e, {
 	table: ee,
 	chunkSize: 500
 }).pipe(p.map((e) => ({
 	key: String(e.key),
 	contentType: String(e.contentType ?? "application/octet-stream"),
 	size: Number(e.size ?? 0)
-}))), J = (e) => !!e && e.endsWith(".vbundle"), Y = (e) => V(e, "--passphrase") ?? process.env.VOLTRO_BUNDLE_KEY, _e = (e) => e.includes("--encrypt") || V(e, "--passphrase") !== void 0 || process.env.VOLTRO_BUNDLE_KEY !== void 0, ve = async (e, t) => {
+}))), G = (e) => !!e && e.endsWith(".vbundle"), K = (e) => z(e, "--passphrase") ?? process.env.VOLTRO_BUNDLE_KEY, be = (e) => e.includes("--encrypt") || z(e, "--passphrase") !== void 0 || process.env.VOLTRO_BUNDLE_KEY !== void 0, xe = async (e, t) => {
 	let { createWriteStream: n } = await import("node:fs"), { pipeline: r } = await import("node:stream/promises"), { Readable: i } = await import("node:stream");
 	await r(i.from(e), n(t));
-}, X = (e) => ({ async *[Symbol.asyncIterator]() {
+}, q = (e) => ({ async *[Symbol.asyncIterator]() {
 	let { createReadStream: t } = await import("node:fs");
 	for await (let n of t(e)) yield n instanceof Uint8Array ? n : new Uint8Array(n);
-} }), Z = (e) => (e ?? "").split(",").map((e) => e.trim()).filter(Boolean), ye = (t, n) => {
-	let r = V(t, "--tenant"), i = V(t, "--tables"), a = V(t, "--exclude");
+} }), J = (e) => (e ?? "").split(",").map((e) => e.trim()).filter(Boolean), Se = (t, n) => {
+	let r = z(t, "--tenant"), i = z(t, "--tables"), a = z(t, "--exclude");
 	if (a !== void 0) {
 		if (i !== void 0) throw new e("voltro data export: --exclude and --tables are two ways to say the same thing; use one.");
 		if (r !== void 0) throw new e("voltro data export: --exclude does not apply to --tenant, whose table set is derived from the tenant closure.");
-		let t = Z(a), o = new Set(n), s = t.filter((e) => !o.has(e));
+		let t = J(a), o = new Set(n), s = t.filter((e) => !o.has(e));
 		if (s.length > 0) throw new e(`voltro data export: --exclude names ${s.length} table(s) that do not exist: ${s.join(", ")}. An exclusion that excludes nothing would leave the run looking like it worked.`);
 		let c = new Set(t);
 		return {
@@ -203,15 +203,15 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		tenantId: r
 	} : i ? {
 		kind: "tables",
-		tables: Z(i)
+		tables: J(i)
 	} : { kind: "all" };
-}, be = async () => {
+}, Ce = async () => {
 	let e = await u(process.cwd());
 	return re(h(e));
-}, xe = "voltro/tenant", Se = async () => {
-	let e = (await u(process.cwd())).filter((e) => (e.appliedMixins ?? []).some((e) => e.id === xe)).map((e) => e.tableName);
+}, we = "voltro/tenant", Te = async () => {
+	let e = (await u(process.cwd())).filter((e) => (e.appliedMixins ?? []).some((e) => e.id === we)).map((e) => e.tableName);
 	return e.length > 0 ? e : void 0;
-}, Ce = (e) => {
+}, Ee = (e) => {
 	for (let t of e.tables) if (t.samples.length !== 0) {
 		console.log(`\n  ${t.table}`);
 		for (let e of t.samples) console.log(`    ${e.column}  [${e.action}]  ${JSON.stringify(e.before)} → ${JSON.stringify(e.after)}`);
@@ -224,21 +224,21 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		console.log("\n  ✗ unclassified (would BLOCK a real export — add .sensitive()/.safe() or a policy override):");
 		for (let t of e.unclassified) console.log(`    ${t}`);
 	} else console.log("\n  ✓ every exported column is classified — safe to run.");
-}, we = async (e) => {
-	let t = V(e, "--target") === "api", n = V(e, "--bundle-key"), r = H(e);
-	if (!r && !(t && n)) return I.error("usage: voltro data export <outDir> [--target direct|api] [--api-url <url>] [--token <secret>] [--profile <name>] [--tenant <id>] [--tables a,b] [--exclude a,b] [--bundle-key <storage-key>] [--assets] [--compression zstd|gzip|none] [--consistency live|snapshot] [--dry-run]"), 1;
+}, De = async (e) => {
+	let t = z(e, "--target") === "api", n = z(e, "--bundle-key"), r = B(e);
+	if (!r && !(t && n)) return F.error("usage: voltro data export <outDir> [--target direct|api] [--api-url <url>] [--token <secret>] [--profile <name>] [--tenant <id>] [--tables a,b] [--exclude a,b] [--bundle-key <storage-key>] [--assets] [--compression zstd|gzip|none] [--consistency live|snapshot] [--dry-run]"), 1;
 	if (t) {
-		let t = V(e, "--api-url");
-		if (!t) return I.error("--target api requires --api-url <url> (the running instance)"), 1;
-		let i = V(e, "--token") ?? process.env.VOLTRO_DATA_TRANSFER_SECRET;
-		if (!i) return I.error("--target api requires --token <secret> (or VOLTRO_DATA_TRANSFER_SECRET) matching the instance secret"), 1;
-		if (V(e, "--exclude") !== void 0) return I.error("--exclude is a direct-target flag: it expands against the live table list, which --target api does not expose. Use --tables with the explicit set."), 1;
-		let a = V(e, "--tables"), o = {
-			...V(e, "--profile") ? { profile: V(e, "--profile") } : {},
-			...V(e, "--tenant") ? { tenant: V(e, "--tenant") } : {},
+		let t = z(e, "--api-url");
+		if (!t) return F.error("--target api requires --api-url <url> (the running instance)"), 1;
+		let i = z(e, "--token") ?? process.env.VOLTRO_DATA_TRANSFER_SECRET;
+		if (!i) return F.error("--target api requires --token <secret> (or VOLTRO_DATA_TRANSFER_SECRET) matching the instance secret"), 1;
+		if (z(e, "--exclude") !== void 0) return F.error("--exclude is a direct-target flag: it expands against the live table list, which --target api does not expose. Use --tables with the explicit set."), 1;
+		let a = z(e, "--tables"), o = {
+			...z(e, "--profile") ? { profile: z(e, "--profile") } : {},
+			...z(e, "--tenant") ? { tenant: z(e, "--tenant") } : {},
 			...a ? { tables: a.split(",").map((e) => e.trim()).filter(Boolean) } : {},
-			...V(e, "--consistency") === "snapshot" ? { consistency: "snapshot" } : {},
-			...V(e, "--compression") ? { compression: V(e, "--compression") } : {},
+			...z(e, "--consistency") === "snapshot" ? { consistency: "snapshot" } : {},
+			...z(e, "--compression") ? { compression: z(e, "--compression") } : {},
 			...e.includes("--assets") ? { assets: !0 } : {},
 			...n ? { bundleKey: n } : {}
 		}, s = await fetch(`${t.replace(/\/+$/, "")}/_voltro/admin/export`, {
@@ -249,26 +249,35 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 			},
 			body: JSON.stringify(o)
 		});
-		if (!s.ok) return I.error(`api export failed: HTTP ${s.status} — ${await s.text()}`), 1;
-		if (n) return I.info("api export complete (pushed to storage)", {
+		if (!s.ok) return F.error(`api export failed: HTTP ${s.status} — ${await s.text()}`), 1;
+		if (n) return F.info("api export complete (pushed to storage)", {
 			via: t,
 			...await s.json()
 		}), 0;
 		let { resolve: c } = await import("node:path"), l = new Uint8Array(await s.arrayBuffer());
-		return await M((async function* () {
+		return await j((async function* () {
 			yield l;
-		})(), c(process.cwd(), r)), I.info("api export complete (downloaded from the running instance)", {
+		})(), c(process.cwd(), r)), F.info("api export complete (downloaded from the running instance)", {
 			outDir: r,
 			tables: s.headers.get("x-export-tables") ?? void 0,
 			rows: s.headers.get("x-export-rows") ?? void 0,
 			masked: s.headers.get("x-export-masked") ?? void 0
 		}), 0;
 	}
-	if (!r) return I.error("a <outDir> is required for a direct export"), 1;
-	let i = V(e, "--profile"), a = i ? await s(i) : {}, { store: o, snapshot: c, dialect: l } = await K(), u = e.includes("--assets") || a.assets === !0, d = u ? S({}) : void 0, p = V(e, "--compression") ?? a.compression, m = V(e, "--consistency") === "snapshot" ? "snapshot" : a.consistency ?? "live", h = a.masking, g = a.subset, _ = a.scope ?? ye(e, c.tables.map((e) => e.name)), v = h ? await be() : void 0, y = _.kind === "tenant" ? await Se() : void 0, b = y ? { tenantTables: y } : {};
+	if (!r) return F.error("a <outDir> is required for a direct export"), 1;
+	let i = z(e, "--profile"), a = i ? await s(i, { allowPath: !0 }) : {}, { store: o, snapshot: c, dialect: l } = await ye(), u = e.includes("--assets") || a.assets === !0, d = u ? S({}) : void 0, p = z(e, "--compression") ?? a.compression, m = z(e, "--consistency") === "snapshot" ? "snapshot" : a.consistency ?? "live", h = a.masking, g = a.subset, _ = a.scope ?? Se(e, c.tables.map((e) => e.name)), v = h ? await Ce() : void 0, y = _.kind === "tenant" ? await Te() : void 0, b = y ? { tenantTables: y } : {};
 	if (e.includes("--dry-run")) {
-		if (!h) return I.error("--dry-run previews masking, but the profile sets no masking policy"), 1;
-		let e = await f.runPromise(ae({
+		let e = _.kind === "tables" && _.tables ? [..._.tables] : c.tables.map((e) => e.name);
+		if (F.info("export DRY RUN — nothing was written", {
+			outDir: r,
+			tables: e.length,
+			scope: _.kind,
+			consistency: m,
+			compression: p ?? "zstd",
+			assets: u,
+			masking: h ? "profile policy applies" : "none"
+		}), F.info(`would export: ${e.join(", ")}`), !h) return 0;
+		let t = await f.runPromise(ae({
 			store: o,
 			snapshot: c,
 			masking: h,
@@ -278,9 +287,9 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 				...b
 			}
 		}));
-		return Ce(e), +(e.unclassified.length > 0);
+		return Ee(t), +(t.unclassified.length > 0);
 	}
-	if (J(r)) {
+	if (G(r)) {
 		let t = await import("node:os"), n = await import("node:fs/promises"), { resolve: i, join: a } = await import("node:path"), s = await n.mkdtemp(a(t.tmpdir(), "voltro-export-"));
 		try {
 			let t = await f.runPromise(O({
@@ -296,17 +305,17 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 				...p ? { compression: p } : {},
 				...h ? { masking: h } : {},
 				...v ? { classification: v } : {},
-				onProgress: R
+				onProgress: L
 			})), n = T({
 				dir: s,
-				...d ? { blobs: ce(d, () => q(o)) } : {}
-			}), a = _e(e);
+				...d ? { blobs: le(d, () => W(o)) } : {}
+			}), a = be(e);
 			if (a) {
-				let t = Y(e);
-				if (!t) return I.error("--encrypt requires --passphrase <p> or VOLTRO_BUNDLE_KEY (a dedicated key, NOT the transfer secret)"), 1;
+				let t = K(e);
+				if (!t) return F.error("--encrypt requires --passphrase <p> or VOLTRO_BUNDLE_KEY (a dedicated key, NOT the transfer secret)"), 1;
 				n = ie(n, t);
 			}
-			return await ve(n, i(process.cwd(), r)), I.info("export complete (single file)", {
+			return await xe(n, i(process.cwd(), r)), F.info("export complete (single file)", {
 				file: r,
 				encrypted: a,
 				assets: u,
@@ -333,10 +342,10 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		...p ? { compression: p } : {},
 		...h ? { masking: h } : {},
 		...v ? { classification: v } : {},
-		...d ? { assets: oe(d, () => q(o)) } : {},
-		onProgress: R
+		...d ? { assets: se(d, () => W(o)) } : {},
+		onProgress: L
 	}));
-	return I.info("export complete", {
+	return F.info("export complete", {
 		outDir: r,
 		tables: x.tables.length,
 		rows: x.tables.reduce((e, t) => e + t.rowCount, 0),
@@ -344,55 +353,74 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		compression: x.compression,
 		...x.masking ? { maskedColumns: x.masking.transformed.length } : {}
 	}), 0;
-}, Q = async (e) => {
-	let t = V(e, "--target") === "api", n = V(e, "--bundle-key"), i = H(e);
-	if (!i && !(t && n)) return I.error("usage: voltro data import <bundleDir> [--target direct|api] [--api-url <url>] [--token <secret>] [--bundle-key <storage-key>] [--mode upsert|append|replace] [--on-conflict skip|fail] [--atomic] [--assets] [--no-verify] [--force] [--allow-live]  (--force: import despite schema drift AND cross-dialect warnings)"), 1;
-	let a = V(e, "--mode") ?? "upsert", o = V(e, "--on-conflict") ?? "skip";
+}, Y = () => "dry run checked: schema fit, cross-dialect portability, mode legality, the table selection. It did NOT read per-table checksums (those stream during the load) and cannot see conflicts that depend on the target's current rows.", X = (e) => {
+	let t = z(e, "--tables");
+	return {
+		...t ? { tables: t.split(",").map((e) => e.trim()).filter(Boolean) } : {},
+		...e.includes("--dry-run") ? { dryRun: !0 } : {}
+	};
+}, Z = (e, t) => {
+	if (e.includes("--dry-run")) {
+		F.info("import DRY RUN — nothing was written", t), F.info(Y());
+		return;
+	}
+	F.info("import complete", t);
+}, Oe = async (e) => {
+	let t = z(e, "--target") === "api", n = z(e, "--bundle-key"), i = B(e);
+	if (!i && !(t && n)) return F.error("usage: voltro data import <bundleDir> [--target direct|api] [--api-url <url>] [--token <secret>] [--bundle-key <storage-key>] [--tables a,b] [--mode upsert|append|replace] [--on-conflict skip|fail] [--atomic] [--assets] [--no-verify] [--force] [--allow-live] [--dry-run]  (--force: import despite schema drift AND cross-dialect warnings; --dry-run: report what would move, write nothing)"), 1;
+	let a = z(e, "--mode") ?? "upsert", o = z(e, "--on-conflict") ?? "skip";
 	if (t) {
-		let t = V(e, "--api-url");
-		if (!t) return I.error("--target api requires --api-url <url> (the running instance)"), 1;
-		let r = V(e, "--token") ?? process.env.VOLTRO_DATA_TRANSFER_SECRET;
-		if (!r) return I.error("--target api requires --token <secret> (or VOLTRO_DATA_TRANSFER_SECRET) matching the instance secret"), 1;
-		let s = {
+		let t = z(e, "--api-url");
+		if (!t) return F.error("--target api requires --api-url <url> (the running instance)"), 1;
+		let r = z(e, "--token") ?? process.env.VOLTRO_DATA_TRANSFER_SECRET;
+		if (!r) return F.error("--target api requires --token <secret> (or VOLTRO_DATA_TRANSFER_SECRET) matching the instance secret"), 1;
+		let s = z(e, "--tables"), c = {
 			authorization: `Bearer ${r}`,
 			"x-import-mode": a,
 			"x-import-on-conflict": o,
 			...e.includes("--atomic") ? { "x-import-atomic": "1" } : {},
-			...e.includes("--force") ? { "x-import-force": "1" } : {}
-		}, { resolve: c } = await import("node:path"), l;
-		if (n) s["content-type"] = "application/json", l = JSON.stringify({ bundleKey: n });
-		else if (J(i)) {
-			let t = X(c(process.cwd(), i)), n = Y(e);
+			...e.includes("--force") ? { "x-import-force": "1" } : {},
+			...e.includes("--dry-run") ? { "x-import-dry-run": "1" } : {},
+			...s ? { "x-import-tables": s } : {}
+		}, { resolve: l } = await import("node:path"), u;
+		if (n) c["content-type"] = "application/json", u = JSON.stringify({ bundleKey: n });
+		else if (G(i)) {
+			let t = q(l(process.cwd(), i)), n = K(e);
 			n && (t = w(t, n));
 			let r = [];
 			for await (let e of t) r.push(Buffer.from(e));
-			s["content-type"] = "application/octet-stream", l = Buffer.concat(r);
+			c["content-type"] = "application/octet-stream", u = Buffer.concat(r);
 		} else {
-			await (await import("node:fs/promises")).access(c(process.cwd(), i, "assets", "index.ndjson")).then(() => !0, () => !1) && I.warn("this directory bundle has assets; --target api uploads DATA ONLY. Pack a single-file `.vbundle` (voltro data export <name>.vbundle --assets) to transfer assets over the API.");
+			await (await import("node:fs/promises")).access(l(process.cwd(), i, "assets", "index.ndjson")).then(() => !0, () => !1) && F.warn("this directory bundle has assets; --target api uploads DATA ONLY. Pack a single-file `.vbundle` (voltro data export <name>.vbundle --assets) to transfer assets over the API.");
 			let e = [];
-			for await (let t of T({ dir: c(process.cwd(), i) })) e.push(Buffer.from(t));
-			s["content-type"] = "application/octet-stream", l = Buffer.concat(e);
+			for await (let t of T({ dir: l(process.cwd(), i) })) e.push(Buffer.from(t));
+			c["content-type"] = "application/octet-stream", u = Buffer.concat(e);
 		}
-		let u = await fetch(`${t.replace(/\/+$/, "")}/_voltro/admin/import`, {
+		let d = await fetch(`${t.replace(/\/+$/, "")}/_voltro/admin/import`, {
 			method: "POST",
-			body: l,
-			headers: s
+			body: u,
+			headers: c
 		});
-		return u.ok ? (I.info("api import complete (imported by the running instance)", {
+		if (!d.ok) return F.error(`api import failed: HTTP ${d.status} — ${await d.text()}`), 1;
+		let f = await d.json();
+		return e.includes("--dry-run") ? (F.info("api import DRY RUN — nothing was written", {
+			via: t,
+			...f
+		}), F.info(Y()), 0) : (F.info("api import complete (imported by the running instance)", {
 			via: t,
-			...await u.json()
-		}), 0) : (I.error(`api import failed: HTTP ${u.status} — ${await u.text()}`), 1);
+			...f
+		}), 0);
 	}
-	if (!i) return I.error("a <bundleDir> is required for a direct import"), 1;
-	if (!await B(e)) return 1;
-	let { store: s, snapshot: c } = await K(), l = e.includes("--force"), u = (e) => I.warn(e), d = e.includes("--assets") ? S({}) : void 0, p = U() === "postgres" ? (await import("@voltro/sql-postgres")).makePgCopySession(r()) : void 0;
-	if (J(i)) {
+	if (!i) return F.error("a <bundleDir> is required for a direct import"), 1;
+	if (!await R(e)) return 1;
+	let { store: s, snapshot: c } = await ye(), l = e.includes("--force"), u = (e) => F.warn(e), d = e.includes("--assets") ? S({}) : void 0, p = V() === "postgres" ? (await import("@voltro/sql-postgres")).makePgCopySession(r()) : void 0;
+	if (G(i)) {
 		let t = await import("node:os"), n = await import("node:fs/promises"), { resolve: r, join: m } = await import("node:path"), h = await n.mkdtemp(m(t.tmpdir(), "voltro-import-"));
 		try {
-			let t = X(r(process.cwd(), i)), n = Y(e);
-			n && (t = w(t, n)), await le(t, {
+			let t = q(r(process.cwd(), i)), n = K(e);
+			n && (t = w(t, n)), await ue(t, {
 				dir: h,
-				blobs: se(d ?? S({}))
+				blobs: ce(d ?? S({}))
 			});
 			let m = await f.runPromise(k({
 				store: s,
@@ -401,16 +429,17 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 				onConflict: o,
 				atomic: e.includes("--atomic"),
 				verify: !e.includes("--no-verify"),
-				targetDialect: U(),
+				targetDialect: V(),
 				allowIncompatible: l,
 				targetSnapshot: c,
 				force: l,
 				onWarn: u,
-				onProgress: R,
+				onProgress: L,
 				assetsAlreadyRestored: !0,
+				...X(e),
 				...p ? { copyLoader: p } : {}
 			}));
-			return I.info("import complete (single file)", {
+			return Z(e, {
 				file: i,
 				tables: m.tables.length,
 				rows: m.tables.reduce((e, t) => e + t.rowCount, 0)
@@ -429,22 +458,23 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		onConflict: o,
 		atomic: e.includes("--atomic"),
 		verify: !e.includes("--no-verify"),
-		targetDialect: U(),
+		targetDialect: V(),
 		allowIncompatible: l,
 		targetSnapshot: c,
 		force: l,
 		onWarn: u,
-		onProgress: R,
-		...d ? { assets: j(d) } : {},
+		onProgress: L,
+		...X(e),
+		...d ? { assets: oe(d) } : {},
 		...p ? { copyLoader: p } : {}
 	})).finally(() => p?.close());
-	return I.info("import complete", {
+	return Z(e, {
 		bundleDir: i,
 		tables: m.tables.length,
 		rows: m.tables.reduce((e, t) => e + t.rowCount, 0),
 		assets: m.assets.count
 	}), 0;
-}, $ = () => {
+}, Q = () => {
 	let e = r();
 	return {
 		...e.url ? { url: e.url } : {},
@@ -454,98 +484,186 @@ var N = "voltro-backup-stamp.json", ue = (e) => ({
 		...e.password ? { password: e.password } : {},
 		...e.database ? { database: e.database } : {}
 	};
-}, Te = async (e) => {
-	let t = H(e);
-	if (!t) return I.error("usage: voltro data backup <outDir>  (native pg_dump/mysqldump/… + consistent artifact)"), 1;
-	let n = U(), { mkdir: r, writeFile: i } = await import("node:fs/promises"), { join: a } = await import("node:path");
+}, ke = async (e) => {
+	let t = B(e);
+	if (!t) return F.error("usage: voltro data backup <outDir>  (native pg_dump/mysqldump/… + consistent artifact)"), 1;
+	let n = V(), { mkdir: r, writeFile: i } = await import("node:fs/promises"), { join: a } = await import("node:path");
 	await r(t, { recursive: !0 });
 	let o = a(t, C(n));
-	await f.runPromise(A(ne(n, $(), o)));
-	let s = ue({
+	await f.runPromise(A(ne(n, Q(), o)));
+	let s = de({
 		dialect: n,
-		schemaFingerprint: await L(n),
-		voltroVersion: await me(),
+		schemaFingerprint: await I(n),
+		voltroVersion: await he(),
 		createdAt: (/* @__PURE__ */ new Date()).toISOString()
 	});
-	return await i(a(t, N), `${JSON.stringify(s, null, 2)}\n`, "utf8"), I.info("native backup complete", {
+	return await i(a(t, M), `${JSON.stringify(s, null, 2)}\n`, "utf8"), F.info("native backup complete", {
 		dialect: n,
 		artifact: o,
-		stamp: N,
+		stamp: M,
 		schemaFingerprint: s.schemaFingerprint ?? "<none>",
 		assets: "NOT included — use `voltro data export --assets` for rows + blobs"
 	}), 0;
-}, Ee = async (e, t) => {
-	let n = U(), { join: r } = await import("node:path"), { readFile: i } = await import("node:fs/promises"), a = r(e, C(n)), o = fe({
-		flagUrl: V(t, "--drill-url"),
+}, Ae = async (e, t) => {
+	let n = V(), { join: r } = await import("node:path"), { readFile: i } = await import("node:fs/promises"), a = r(e, C(n)), o = pe({
+		flagUrl: z(t, "--drill-url"),
 		envUrl: process.env.DRILL_DB_URL,
-		liveKeys: ge()
+		liveKeys: ve()
 	});
-	if (!o.ok) return I.error(`restore --drill: ${o.error}`), 1;
-	let s = await i(r(e, N), "utf8").then(P, () => null);
-	if (s && s.dialect !== n) return I.error(`restore --drill: backup is a ${s.dialect} dump but DB_DIALECT is ${n} — cross-dialect restore is never valid.`), 1;
-	I.info("restore drill: restoring into throwaway DB", {
+	if (!o.ok) return F.error(`restore --drill: ${o.error}`), 1;
+	let s = await i(r(e, M), "utf8").then(N, () => null);
+	if (s && s.dialect !== n) return F.error(`restore --drill: backup is a ${s.dialect} dump but DB_DIALECT is ${n} — cross-dialect restore is never valid.`), 1;
+	F.info("restore drill: restoring into throwaway DB", {
 		dialect: n,
-		target: F(o.url)
+		target: P(o.url)
 	}), await f.runPromise(A(D(n, { url: o.url }, a)));
 	let c = null, l = 0;
 	try {
-		let e = await W(n, { url: o.url });
+		let e = await H(n, { url: o.url });
 		c = g(e), l = e.tables.length;
 	} catch (e) {
-		return I.error(`restore --drill: could not introspect the restored DB — ${String(e)}`), 1;
+		return F.error(`restore --drill: could not introspect the restored DB — ${String(e)}`), 1;
 	}
-	let u = pe({
+	let u = me({
 		stampFingerprint: s?.schemaFingerprint ?? null,
 		restoredFingerprint: c,
 		restoredTableCount: l
 	});
-	for (let e of u.lines) u.pass ? I.info(`restore drill: ${e}`) : I.error(`restore drill: ${e}`);
+	for (let e of u.lines) u.pass ? F.info(`restore drill: ${e}`) : F.error(`restore drill: ${e}`);
 	return +!u.pass;
-}, De = async (e) => {
-	let t = H(e);
-	if (!t) return I.error("usage: voltro data restore <backupDir> [--allow-live] [--api-url <url>] [--force] [--drill [--drill-url <url>]]  (native pg_restore/mysql/…)"), 1;
-	if (e.includes("--drill")) return Ee(t, e);
-	if (!await B(e)) return 1;
-	let n = U(), { join: r } = await import("node:path"), { readFile: i } = await import("node:fs/promises"), a = r(t, C(n)), o = de({
-		stamp: await i(r(t, N), "utf8").then(P, () => null),
+}, je = async (e) => {
+	let t = B(e);
+	if (!t) return F.error("usage: voltro data restore <backupDir> [--allow-live] [--api-url <url>] [--force] [--drill [--drill-url <url>]]  (native pg_restore/mysql/…)"), 1;
+	if (e.includes("--drill")) return Ae(t, e);
+	if (!await R(e)) return 1;
+	let n = V(), { join: r } = await import("node:path"), { readFile: i } = await import("node:fs/promises"), a = r(t, C(n)), o = fe({
+		stamp: await i(r(t, M), "utf8").then(N, () => null),
 		currentDialect: n,
-		currentFingerprint: await L(n)
+		currentFingerprint: await I(n)
 	});
-	for (let e of o.info) I.info(`backup stamp: ${e}`);
-	if (o.warn && I.warn(o.warn), o.refuse) {
-		if (!e.includes("--force")) return I.error(`restore refused: ${o.refuse} (pass --force to override)`), 1;
-		I.warn(`restore proceeding despite: ${o.refuse} (--force)`);
+	for (let e of o.info) F.info(`backup stamp: ${e}`);
+	if (o.warn && F.warn(o.warn), o.refuse) {
+		if (!e.includes("--force")) return F.error(`restore refused: ${o.refuse} (pass --force to override)`), 1;
+		F.warn(`restore proceeding despite: ${o.refuse} (--force)`);
 	}
-	return await f.runPromise(A(D(n, $(), a))), I.info("native restore complete", {
+	return await f.runPromise(A(D(n, Q(), a))), F.info("native restore complete", {
 		dialect: n,
 		artifact: a
 	}), 0;
-}, Oe = async (e) => {
-	let t = H(e);
-	if (!t) return I.error("usage: voltro data inspect <file.vbundle> [--json] [--passphrase <p>]"), 1;
-	let { resolve: n } = await import("node:path"), r = n(process.cwd(), t), i = Y(e), a = () => {
-		let e = X(r);
-		return i ? w(e, i) : e;
+}, Me = async (e) => {
+	let t = B(e);
+	if (!t) return F.error("usage: voltro data inspect <file.vbundle|dir> [--json] [--passphrase <p>]"), 1;
+	let { resolve: n, join: r } = await import("node:path"), i = await import("node:fs/promises"), a = n(process.cwd(), t);
+	if ((await i.stat(a).catch(() => void 0))?.isDirectory()) {
+		let n = r(a, "manifest.json"), o = r(a, "README.md");
+		if (!e.includes("--json")) {
+			let e = await i.readFile(o, "utf8").catch(() => void 0);
+			if (e !== void 0) return console.log(e), 0;
+		}
+		let s = await i.readFile(n, "utf8").catch(() => void 0);
+		return s === void 0 ? (F.error(`'${t}' is a directory but holds no manifest.json — is it an unpacked bundle? (a bundle exported with --target api is always unpacked into a directory, even when the path ends in .vbundle)`), 1) : (console.log(s), 0);
+	}
+	let o = K(e), s = () => {
+		let e = q(a);
+		return o ? w(e, o) : e;
 	};
 	if (e.includes("--json")) {
-		let e = (await E(a(), ["manifest.json"])).get("manifest.json");
-		return e ? (console.log(e.toString("utf8")), 0) : (I.error("no manifest.json found in the bundle"), 1);
+		let e = (await E(s(), ["manifest.json"])).get("manifest.json");
+		return e ? (console.log(e.toString("utf8")), 0) : (F.error("no manifest.json found in the bundle"), 1);
 	}
-	let o = (await E(a(), ["README.md"])).get("README.md");
-	if (o) return console.log(o.toString("utf8")), 0;
-	let s = (await E(a(), ["manifest.json"])).get("manifest.json");
-	return s ? (console.log(s.toString("utf8")), 0) : (I.error("bundle has no README.md or manifest.json"), 1);
-}, ke = async (e) => {
-	let t = H(e), n = H(e.filter((e) => e !== t));
-	if (!t || !n) return I.error("usage: voltro data unpack <file.vbundle> <dir> [--passphrase <p>]"), 1;
-	let { resolve: r } = await import("node:path"), i = X(r(process.cwd(), t)), a = Y(e);
-	return a && (i = w(i, a)), await M(i, r(process.cwd(), n)), I.info("unpack complete", {
+	let c = (await E(s(), ["README.md"])).get("README.md");
+	if (c) return console.log(c.toString("utf8")), 0;
+	let l = (await E(s(), ["manifest.json"])).get("manifest.json");
+	return l ? (console.log(l.toString("utf8")), 0) : (F.error("bundle has no README.md or manifest.json"), 1);
+}, Ne = async (e) => {
+	let t = B(e), n = B(e.filter((e) => e !== t));
+	if (!t || !n) return F.error("usage: voltro data unpack <file.vbundle> <dir> [--passphrase <p>]"), 1;
+	let { resolve: r } = await import("node:path"), i = q(r(process.cwd(), t)), a = K(e);
+	return a && (i = w(i, a)), await j(i, r(process.cwd(), n)), F.info("unpack complete", {
 		file: t,
 		dir: n
 	}), 0;
-}, Ae = async (e) => {
+}, $ = {
+	export: {
+		common: [
+			"--target",
+			"--tables",
+			"--profile",
+			"--tenant",
+			"--assets",
+			"--compression",
+			"--consistency",
+			"--json"
+		],
+		directOnly: [
+			"--exclude",
+			"--passphrase",
+			"--dry-run",
+			"--encrypt"
+		],
+		apiOnly: [
+			"--api-url",
+			"--token",
+			"--bundle-key"
+		]
+	},
+	import: {
+		common: [
+			"--target",
+			"--tables",
+			"--mode",
+			"--on-conflict",
+			"--atomic",
+			"--assets",
+			"--force",
+			"--dry-run",
+			"--json"
+		],
+		directOnly: [
+			"--no-verify",
+			"--allow-live",
+			"--passphrase"
+		],
+		apiOnly: [
+			"--api-url",
+			"--token",
+			"--bundle-key"
+		]
+	},
+	unpack: { common: ["--passphrase", "--json"] },
+	inspect: { common: ["--json", "--passphrase"] },
+	backup: { common: ["--json", "--assets"] },
+	restore: { common: [
+		"--json",
+		"--allow-live",
+		"--force",
+		"--drill",
+		"--drill-url",
+		"--api-url"
+	] }
+}, Pe = (e) => e.split("=")[0], Fe = (e, t) => {
+	let n = $[e];
+	if (!n) return;
+	let r = z(t, "--target") === "api" ? "api" : "direct", i = /* @__PURE__ */ new Set([...n.common, ...r === "api" ? n.apiOnly ?? [] : n.directOnly ?? []]), a = new Set(r === "api" ? n.directOnly ?? [] : n.apiOnly ?? []);
+	for (let n of t) {
+		if (!n.startsWith("--")) continue;
+		let t = Pe(n);
+		if (i.has(t)) continue;
+		if (a.has(t)) return `voltro data ${e}: ${t} is not read with --target ${r} (it is a --target ${r === "api" ? "direct" : "api"} flag). Remove it, or change --target.`;
+		let o = Object.entries($).filter(([n, r]) => n !== e && [
+			...r.common,
+			...r.directOnly ?? [],
+			...r.apiOnly ?? []
+		].includes(t)).map(([e]) => e);
+		return o.length > 0 ? `voltro data ${e}: ${t} is not a \`${e}\` flag (it belongs to \`voltro data ${o.join("` / `")}\`). Remove it.` : `voltro data ${e}: unknown flag ${t}. Run \`voltro data --help\` for the flags this command reads.`;
+	}
+}, Ie = async (e) => {
 	let [t, ...n] = e;
-	return t === "export" ? we(n) : t === "import" ? Q(n) : t === "unpack" ? ke(n) : t === "inspect" ? Oe(n) : t === "backup" ? Te(n) : t === "restore" ? De(n) : (I.error("usage: voltro data <export|import|unpack|inspect|backup|restore> … (logical: export/import; native: backup/restore)"), t ? 2 : 1);
+	if (t !== void 0 && $[t] !== void 0) {
+		let e = Fe(t, n);
+		if (e) return F.error(e), 2;
+	}
+	return t === "export" ? De(n) : t === "import" ? Oe(n) : t === "unpack" ? Ne(n) : t === "inspect" ? Me(n) : t === "backup" ? ke(n) : t === "restore" ? je(n) : (F.error("usage: voltro data <export|import|unpack|inspect|backup|restore> … (logical: export/import; native: backup/restore)"), t ? 2 : 1);
 };
 //#endregion
-export { Ae as runDataCommand };
+export { Ie as runDataCommand };