@fluid-app/fluid-cli-genealogy 0.0.0-stage → 0.1.1

package/dist/index.mjs

@@ -0,0 +1,1242 @@
+import prompts from "prompts";
+import { createDomainCommand } from "@fluid-app/fluid-cli";
+//#region src/api.ts
+const BASE = "/api/company/v2026-10/genealogy";
+/** The tree `fluid genealogy` reads when --tree is not given, matching the
+*  Rails genealogy CLI. */
+const DEFAULT_TREE = "placement";
+/** Node pages hold at most 1,000 rows; history-style pages (placements,
+*  holding tank, move requests and jobs) at most 100. */
+const NODE_PAGE_MAX = 1e3;
+const HISTORY_PAGE_MAX = 100;
+/** An unbounded read stops here instead of returning a partial list. */
+const MAX_PAGES = 200;
+/** Fan-out reads (each child when ranking legs, each relation kind) run
+*  this many at a time. */
+const CONCURRENCY = 5;
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+var GenealogyError = class extends Error {
+	/** The API's failure type, when the error restates an API failure. */
+	type;
+	/** The API's HTTP status, when the error restates an API failure. */
+	status;
+	constructor(message, options = {}) {
+		super(message);
+		this.name = "GenealogyError";
+		if (options.type !== void 0) this.type = options.type;
+		if (options.status !== void 0) this.status = options.status;
+	}
+};
+function isUuid(value) {
+	return UUID.test(value);
+}
+function path(...segments) {
+	return `${BASE}/${segments.map((s) => encodeURIComponent(s)).join("/")}`;
+}
+function requireUuid(label, value) {
+	const trimmed = value.trim();
+	if (!isUuid(trimmed)) throw new GenealogyError(`${label} "${value}" isn't a UUID.`);
+	return trimmed;
+}
+/** Parse a CLI number option; undefined stays undefined. */
+function toPositiveInt(name, raw, max) {
+	if (raw === void 0) return void 0;
+	const value = typeof raw === "number" ? raw : Number(raw);
+	if (!Number.isInteger(value) || value < 1 || max != null && value > max) throw new GenealogyError(`${name} must be a whole number${max != null ? ` from 1 to ${max}` : ""}.`);
+	return value;
+}
+function requireDepth(raw) {
+	const depth = toPositiveInt("--depth", raw);
+	if (depth === void 0) throw new GenealogyError(`--depth is required: a relative depth from 1 to 7.`);
+	return depth;
+}
+function checkAsOf(asOf) {
+	if (asOf === void 0) return void 0;
+	if (Number.isNaN(Date.parse(asOf))) throw new GenealogyError(`--as-of "${asOf}" isn't an ISO 8601 timestamp, e.g. 2026-09-15T00:00:00Z.`);
+	return asOf;
+}
+async function listTrees(client) {
+	return (await client.get(path("trees"))).trees ?? [];
+}
+/** List the company's tree ids, keys and names. Unlike `listTrees`, this
+*  needs only members.view, not developer.view. */
+async function listTreeKeys(client) {
+	return (await client.get(path("tree-keys"))).trees ?? [];
+}
+const isForbidden = (err) => err.status === 403;
+const isNotFound = (err) => err.status === 404;
+/** Tree keys need members.view; a caller with only developer.view reads
+*  them from the tree definitions instead. An API that predates the
+*  tree-keys endpoint answers 404, and also falls back. */
+async function lookUpTreeKeys(client) {
+	try {
+		return await listTreeKeys(client);
+	} catch (err) {
+		if (!isForbidden(err) && !isNotFound(err)) throw err;
+	}
+	try {
+		return (await listTrees(client)).map(({ id, key, name }) => ({
+			id,
+			key,
+			name: name ?? key
+		}));
+	} catch (err) {
+		if (!isForbidden(err)) throw err;
+		throw new GenealogyError("Looking up a tree by key needs members.view or developer.view. Pass --tree <tree-uuid> instead.");
+	}
+}
+/** Resolve a tree key (e.g. "placement") or UUID to a tree UUID. Tree paths
+*  only take UUIDs, so a key is looked up in the company's tree keys. */
+async function resolveTreeId(client, keyOrId) {
+	const trimmed = keyOrId.trim();
+	if (isUuid(trimmed)) return trimmed;
+	const trees = await lookUpTreeKeys(client);
+	const match = trees.find((tree) => tree.key === trimmed);
+	if (!match) throw new GenealogyError(`No tree with key "${trimmed}" on this company. Trees: ${trees.map((tree) => tree.key).join(", ") || "none"}.`);
+	return match.id;
+}
+const TREE_KINDS = [
+	"unilevel",
+	"binary",
+	"matrix"
+];
+const TREE_ROLES = ["enrollment", "sponsor"];
+const TREE_AUTHORITIES = [
+	"authoritative",
+	"replica",
+	"unconfigured"
+];
+const MOVEMENT_APPROVALS = ["immediate", "require_approval"];
+const VOLUME_ON_MOVE = ["follows_structure", "stays_at_earning"];
+/** A tree's default rule: the placement rules plus the two role-tree rules. */
+const TREE_PLACEMENT_RULES = [
+	"exact",
+	"first_empty",
+	"left",
+	"right",
+	"inside",
+	"outside",
+	"balanced",
+	"weak_leg",
+	"strong_leg",
+	"enroller_preference",
+	"defer",
+	"under_enroller",
+	"mirror_enrollment"
+];
+const NONE = "none";
+function oneOf(flag, value, allowed) {
+	if (!allowed.includes(value)) throw new GenealogyError(`${flag} must be one of ${allowed.join(", ")}.`);
+	return value;
+}
+function wholeNumber(flag, raw, min) {
+	const value = Number(raw);
+	if (raw.trim() === "" || !Number.isInteger(value) || value < min) throw new GenealogyError(`${flag} must be a whole number, ${min} or more.`);
+	return value;
+}
+function bool(flag, raw) {
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	throw new GenealogyError(`${flag} must be true or false.`);
+}
+function legList(raw) {
+	const legs = raw.split(",").map((leg) => leg.trim());
+	if (legs.some((leg) => leg === "") || new Set(legs).size !== legs.length) throw new GenealogyError("--leg-names must be distinct, nonblank names separated by commas, e.g. left,right.");
+	return legs;
+}
+/** Build the `tree` object a create or update sends, validating each flag.
+*  Only the flags given are sent. */
+function treeFields(input) {
+	const fields = {};
+	const text = (flag, name, value) => {
+		if (value === void 0) return;
+		if (value.trim() === "") throw new GenealogyError(`${flag} can't be blank.`);
+		fields[name] = value;
+	};
+	const clearable = (name, value, parse) => {
+		if (value === void 0) return;
+		fields[name] = value === NONE ? null : parse(value);
+	};
+	text("--key", "key", input.key);
+	text("--name", "name", input.name);
+	if (input.kind !== void 0) fields["kind"] = oneOf("--kind", input.kind, TREE_KINDS);
+	clearable("role", input.role, (raw) => oneOf("--role", raw, TREE_ROLES));
+	if (input.legNames !== void 0) fields["leg_names"] = input.legNames === NONE ? [] : legList(input.legNames);
+	if (input.placementRule !== void 0) fields["default_placement_rule"] = oneOf("--placement-rule", input.placementRule, TREE_PLACEMENT_RULES);
+	if (input.movementApproval !== void 0) fields["movement_approval"] = oneOf("--movement-approval", input.movementApproval, MOVEMENT_APPROVALS);
+	if (input.maxDepth !== void 0) fields["max_depth"] = wholeNumber("--max-depth", input.maxDepth, 1);
+	for (const [prop, flag, name] of [
+		[
+			"holdingTankDays",
+			"--holding-tank-days",
+			"holding_tank_days"
+		],
+		[
+			"movementWindowDays",
+			"--movement-window-days",
+			"movement_window_days"
+		],
+		[
+			"maxMovementLevels",
+			"--max-movement-levels",
+			"max_movement_levels"
+		]
+	]) {
+		const raw = input[prop];
+		if (raw !== void 0) fields[name] = wholeNumber(flag, raw, 0);
+	}
+	clearable("volume_on_move", input.volumeOnMove, (raw) => oneOf("--volume-on-move", raw, VOLUME_ON_MOVE));
+	clearable("volume_key", input.volumeKey, (raw) => raw);
+	if (input.allowMultiplePositions !== void 0) fields["allow_multiple_positions"] = bool("--allow-multiple-positions", input.allowMultiplePositions);
+	if (input.authority !== void 0) fields["authority"] = oneOf("--authority", input.authority, TREE_AUTHORITIES);
+	clearable("owning_company_integration_id", input.owningCompanyIntegrationId, (raw) => wholeNumber("--owning-company-integration-id", raw, 1));
+	clearable("upstream_tree_ref", input.upstreamTreeRef, (raw) => raw);
+	clearable("external_integration_market_id", input.externalIntegrationMarketId, (raw) => raw);
+	return fields;
+}
+/** The body for POST /trees. Checks what the API would refuse anyway, so a
+*  mistake is named before anything is sent. */
+function createTreeBody(input) {
+	const fields = treeFields(input);
+	const missing = [
+		["key", "--key"],
+		["name", "--name"],
+		["kind", "--kind"],
+		["authority", "--authority"]
+	].filter(([name]) => fields[name] === void 0).map(([, flag]) => flag);
+	if (missing.length > 0) throw new GenealogyError(`Creating a tree needs ${missing.join(", ")}. --authority declares who owns the tree: authoritative (Fluid), replica (an integration's copy) or unconfigured (not yet decided; it takes no placements).`);
+	const kind = fields["kind"];
+	const legs = fields["leg_names"];
+	if (kind === "unilevel" && legs && legs.length > 0) throw new GenealogyError("A unilevel tree has no legs; drop --leg-names.");
+	if (kind === "binary" && legs && legs.length !== 2) throw new GenealogyError("A binary tree has exactly two legs, e.g. --leg-names left,right (the default).");
+	if (kind === "matrix" && (!legs || legs.length < 2)) throw new GenealogyError("A matrix tree needs --leg-names with two or more legs; their count is its width.");
+	if (kind !== "unilevel" && fields["volume_on_move"] == null) throw new GenealogyError(`A ${String(kind)} tree needs --volume-on-move ${VOLUME_ON_MOVE.join(" or ")}.`);
+	if (fields["authority"] === "replica" && fields["owning_company_integration_id"] == null) throw new GenealogyError("A replica tree needs --owning-company-integration-id.");
+	return { tree: fields };
+}
+/** Readable restatements of the registry's write failures. */
+function treeWriteError(err, tree, method) {
+	const status = err.status;
+	const nested = err.body?.["error"];
+	const type = nested && typeof nested === "object" ? nested.details?.type : void 0;
+	if (typeof status !== "number" || typeof type !== "string") return err;
+	const message = {
+		duplicate_key: `Another tree on this company already has the key of "${tree}". Tree keys are unique per company; pick another --key.`,
+		role_taken: "This company already has a tree with that role. Each role (enrollment, sponsor) has one tree.",
+		stale_tree: `Tree "${tree}" changed since its lock_version was read. Read it again with "fluid genealogy trees" and retry, or omit --lock-version to use the current one.`,
+		tree_has_nodes: method === "DELETE" ? `Tree "${tree}" has seats, and delete refuses a tree with nodes. Remove its seats first.` : `Tree "${tree}" has seats, so only its --name can change; other fields need a structural migration.`,
+		reserved_role: "The default enrollment and placement trees can't be deleted or have their role changed.",
+		reserved_key: "The keys \"enrollment\" and \"placement\" belong to the default role trees."
+	}[type];
+	return message ? new GenealogyError(message, {
+		type,
+		status
+	}) : err;
+}
+/** A tree's full definition by key or UUID, from the tree list. */
+async function findTree(client, keyOrId) {
+	const wanted = keyOrId.trim();
+	const trees = await listTrees(client);
+	const match = trees.find((tree) => isUuid(wanted) ? tree.id === wanted : tree.key === wanted);
+	if (!match) throw new GenealogyError(`No tree "${wanted}" on this company. Trees: ${trees.map((tree) => tree.key).join(", ") || "none"}.`);
+	return match;
+}
+function planCreateTree(input) {
+	return {
+		method: "POST",
+		path: path("trees"),
+		body: createTreeBody(input)
+	};
+}
+/** Plan a PATCH: only the given fields, at the tree's lock_version (read
+*  now unless --lock-version pins it). */
+async function planUpdateTree(client, keyOrId, input, lockVersion) {
+	const fields = treeFields(input);
+	if (Object.keys(fields).length === 0) throw new GenealogyError("Pass at least one field to change, e.g. --name or --movement-approval.");
+	const { id, version } = await treeVersion(client, keyOrId, lockVersion);
+	return {
+		method: "PATCH",
+		path: path("trees", id),
+		body: { tree: {
+			...fields,
+			lock_version: version
+		} }
+	};
+}
+async function planDeleteTree(client, keyOrId, lockVersion) {
+	const { id, version } = await treeVersion(client, keyOrId, lockVersion);
+	return {
+		method: "DELETE",
+		path: path("trees", id),
+		params: { lock_version: version }
+	};
+}
+async function treeVersion(client, keyOrId, lockVersion) {
+	const pinned = lockVersion === void 0 ? void 0 : wholeNumber("--lock-version", lockVersion, 0);
+	if (pinned !== void 0 && isUuid(keyOrId.trim())) return {
+		id: keyOrId.trim(),
+		version: pinned
+	};
+	const tree = await findTree(client, keyOrId);
+	const current = tree["lock_version"];
+	if (pinned === void 0 && typeof current !== "number") throw new GenealogyError(`Tree "${keyOrId}" was listed without a lock_version; pass --lock-version.`);
+	return {
+		id: tree.id,
+		version: pinned ?? current
+	};
+}
+/** Send a planned tree write. Returns the written tree, or a deletion
+*  receipt. */
+async function sendTreeWrite(client, write, label) {
+	try {
+		if (write.method === "POST") return withoutMeta(await client.post(write.path, write.body));
+		if (write.method === "PATCH") return withoutMeta(await client.patch(write.path, write.body));
+		await client.delete(write.path, { params: write.params });
+		return {
+			deleted: true,
+			tree: label,
+			path: write.path
+		};
+	} catch (err) {
+		throw treeWriteError(err, label, write.method);
+	}
+}
+const MIRROR_RUN_STATUSES = [
+	"queued",
+	"running",
+	"succeeded",
+	"failed",
+	"halted"
+];
+/** Whether a run has finished, one way or another. */
+function mirrorRunFinished(run) {
+	return [
+		"succeeded",
+		"failed",
+		"halted"
+	].includes(run.status);
+}
+/** Preview the mirror of the enrollment tree into the placement tree:
+*  what would be seated and re-parented. Writes nothing. */
+async function previewMirror(client, treeId) {
+	return { mirror: (await client.post(path("trees", treeId, "mirror-enrollment"), { mirror: { dry_run: true } })).mirror ?? null };
+}
+/** Queue a background run that mirrors the enrollment tree into the
+*  placement tree, or get the run already active (`started: false`). */
+async function startMirror(client, treeId) {
+	const data = await client.post(path("trees", treeId, "mirror-enrollment"), { mirror: { dry_run: false } });
+	return {
+		mirror_run: data.mirror_run ?? null,
+		started: data.started === true
+	};
+}
+async function getMirrorRun(client, id) {
+	return (await client.get(path("mirror-runs", requireUuid("Mirror run", id)))).mirror_run ?? null;
+}
+/** The company's most recent mirror runs, newest first. */
+async function listMirrorRuns(client, options = {}) {
+	if (options.status !== void 0 && !MIRROR_RUN_STATUSES.includes(options.status)) throw new GenealogyError(`--status must be one of ${MIRROR_RUN_STATUSES.join(", ")}`);
+	const params = {};
+	if (options.status !== void 0) params["status"] = options.status;
+	if (options.limit !== void 0) params["limit"] = options.limit;
+	return { mirror_runs: (await client.get(path("mirror-runs"), params)).mirror_runs ?? [] };
+}
+/** Poll a run until it finishes, reporting each reading. */
+async function waitForMirrorRun(client, run, options) {
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	let current = run;
+	options.onProgress?.(current);
+	while (!mirrorRunFinished(current)) {
+		await sleep(options.intervalMs);
+		const next = await getMirrorRun(client, current.id);
+		if (!next) throw new GenealogyError(`Mirror run ${current.id} is gone`);
+		current = next;
+		options.onProgress?.(current);
+	}
+	return current;
+}
+/** Find a member's one seat in a tree. Seats are listed across every tree,
+*  so the tree is filtered here; a member with several positions in the
+*  tree must be addressed by node id. */
+async function resolveMemberNode(client, memberId, tree = DEFAULT_TREE) {
+	const member = requireUuid("Member", memberId);
+	const treeId = await resolveTreeId(client, tree);
+	const { items } = await collectPages(client, path("members", member, "nodes"), {}, "nodes", { maxPageSize: NODE_PAGE_MAX });
+	const seats = items.filter((node) => node.tree_id === treeId);
+	if (seats.length === 0) throw new GenealogyError(`Member ${member} has no seat in tree "${tree}".`);
+	if (seats.length > 1) {
+		const listed = seats.map((seat) => `${seat.id} (position ${seat.position})`).join(", ");
+		throw new GenealogyError(`Member ${member} has ${seats.length} seats in tree "${tree}": ${listed}. Pass the node id instead.`);
+	}
+	return seats[0].id;
+}
+/** A command's subject: a node UUID, or --member resolved in --tree. */
+async function resolveSubject(client, node, member, tree = DEFAULT_TREE) {
+	if (node && member) throw new GenealogyError("Pass a node id or --member, not both.");
+	if (node) return requireUuid("Node", node);
+	if (member) return resolveMemberNode(client, member, tree);
+	throw new GenealogyError("Pass a node id or --member <member-id>.");
+}
+/** Follow next_cursor until the list ends or --limit rows are collected.
+*  A capped read reports the cursor to resume from; an uncapped read that
+*  runs past MAX_PAGES fails rather than return part of the list. */
+async function collectPages(client, endpoint, params, itemsKey, options) {
+	const pageSize = toPositiveInt("--page-size", options.pageSize, options.maxPageSize) ?? options.maxPageSize;
+	const limit = toPositiveInt("--limit", options.limit);
+	const items = [];
+	const pages = [];
+	let cursor = options.cursor;
+	for (let page = 1; page <= MAX_PAGES; page += 1) {
+		const remaining = limit === void 0 ? pageSize : limit - items.length;
+		const data = await client.get(endpoint, {
+			...params,
+			limit: Math.min(pageSize, remaining),
+			...cursor ? { cursor } : {}
+		});
+		pages.push(data);
+		const rows = data[itemsKey];
+		if (Array.isArray(rows)) items.push(...rows);
+		const next = data.meta?.pagination?.next_cursor ?? null;
+		if (!next) return {
+			items,
+			nextCursor: null,
+			pages
+		};
+		if (limit !== void 0 && items.length >= limit) return {
+			items,
+			nextCursor: next,
+			pages
+		};
+		cursor = next;
+	}
+	throw new GenealogyError(`More than ${MAX_PAGES} pages; refusing to return a partial list. Pass --limit and resume with --cursor.`);
+}
+/** Paged node reads and the query selectors each one accepts. The API
+*  refuses selectors it does not list, so only these are sent. */
+const NODE_PAGES = {
+	children: {
+		asOf: false,
+		depth: false,
+		idsOnly: true
+	},
+	siblings: {
+		asOf: false,
+		depth: false,
+		idsOnly: true
+	},
+	frontline: {
+		asOf: false,
+		depth: false,
+		idsOnly: true
+	},
+	"personally-enrolled": {
+		asOf: false,
+		depth: false,
+		idsOnly: true
+	},
+	ancestors: {
+		asOf: true,
+		depth: false,
+		idsOnly: false
+	},
+	descendants: {
+		asOf: true,
+		depth: true,
+		idsOnly: true
+	},
+	subtree: {
+		asOf: true,
+		depth: true,
+		idsOnly: true
+	},
+	level: {
+		asOf: true,
+		depth: true,
+		idsOnly: true
+	}
+};
+async function readNodePage(client, nodeId, operation, options = {}) {
+	const accepts = NODE_PAGES[operation];
+	if (options.asOf !== void 0 && !accepts.asOf) throw new GenealogyError(`--as-of is not accepted by ${operation}.`);
+	if (options.idsOnly && !accepts.idsOnly) throw new GenealogyError(`--ids-only is not accepted by ${operation}.`);
+	const params = {};
+	if (accepts.depth) params["depth"] = requireDepth(options.depth);
+	const asOf = checkAsOf(options.asOf);
+	if (asOf) params["as_of"] = asOf;
+	if (options.idsOnly) params["ids_only"] = true;
+	const itemsKey = options.idsOnly ? "ids" : "nodes";
+	const { items, nextCursor, pages } = await collectPages(client, path("nodes", nodeId, operation), params, itemsKey, {
+		...options,
+		maxPageSize: NODE_PAGE_MAX
+	});
+	const result = {
+		[itemsKey]: items,
+		next_cursor: nextCursor
+	};
+	if (operation === "frontline" || operation === "personally-enrolled") result.node = pages[0]?.node ?? null;
+	if (accepts.depth) result.depth_truncated = pages.some((page) => page.meta?.traversal?.depth_truncated === true);
+	return result;
+}
+/** Grandchildren are the nodes exactly two levels down. */
+function readGrandchildren(client, nodeId, options = {}) {
+	return readNodePage(client, nodeId, "level", {
+		...options,
+		depth: 2
+	});
+}
+/** One node; current reads include children_count and downline_count,
+*  as_of reads return the recorded placement without counts. */
+async function readNode(client, nodeId, asOf) {
+	const at = checkAsOf(asOf);
+	return { node: (await client.get(path("nodes", nodeId), at ? { as_of: at } : void 0)).node ?? null };
+}
+/** Structural counts. They include retained seats of discarded members,
+*  so they can exceed what the page reads list. */
+async function readCounts(client, nodeId) {
+	const { node } = await readNode(client, nodeId);
+	if (!node || typeof node.children_count !== "number" || typeof node.downline_count !== "number") throw new GenealogyError(`The read of node ${nodeId} returned no counts.`);
+	return {
+		node_id: node.id,
+		children_count: node.children_count,
+		downline_count: node.downline_count,
+		counts_as_of: node.counts_as_of ?? null
+	};
+}
+/** parent and root take as_of; sponsor and enroller take no selectors.
+*  The node is null for a root (and for a role-tree root). */
+async function readRelative(client, nodeId, operation, asOf) {
+	if (asOf !== void 0 && (operation === "sponsor" || operation === "enroller")) throw new GenealogyError(`--as-of is not accepted by ${operation}.`);
+	const at = checkAsOf(asOf);
+	return { node: (await client.get(path("nodes", nodeId, operation), at ? { as_of: at } : void 0)).node ?? null };
+}
+const RELATION_KINDS = [
+	"ancestor_of",
+	"descendant_of",
+	"parent_of",
+	"child_of",
+	"sibling_of",
+	"root_of",
+	"indirect_of",
+	"in_subtree_of",
+	"within_downline"
+];
+/** Answer how node relates to other: one kind, or every kind when none is
+*  given. For within_downline, other is the downline's root. */
+async function readRelation(client, nodeId, otherId, kind) {
+	const other = requireUuid("Other node", otherId);
+	if (kind !== void 0 && !RELATION_KINDS.includes(kind)) throw new GenealogyError(`--kind must be one of ${RELATION_KINDS.join(", ")}.`);
+	const answers = await mapLimit(kind ? [kind] : [...RELATION_KINDS], CONCURRENCY, async (k) => {
+		return [k, (await client.get(path("nodes", nodeId, "relation"), {
+			other,
+			kind: k
+		})).relation?.answer ?? false];
+	});
+	return {
+		node_id: nodeId,
+		other,
+		relations: Object.fromEntries(answers)
+	};
+}
+async function readLevelCounts(client, nodeId, depth) {
+	const data = await client.get(path("nodes", nodeId, "level-counts"), { depth: requireDepth(depth) });
+	return {
+		node_id: nodeId,
+		levels: data.levels ?? [],
+		counts_as_of: data.meta?.traversal?.counts_as_of ?? null,
+		depth_truncated: data.meta?.traversal?.depth_truncated ?? false
+	};
+}
+async function readPlacements(client, nodeId, options = {}) {
+	const { items, nextCursor } = await collectPages(client, path("nodes", nodeId, "placements"), {}, "placements", {
+		...options,
+		maxPageSize: HISTORY_PAGE_MAX
+	});
+	return {
+		placements: items,
+		next_cursor: nextCursor
+	};
+}
+async function readHoldingTank(client, treeId, options = {}) {
+	const { items, nextCursor } = await collectPages(client, path("trees", treeId, "holding-tank"), {}, "nodes", {
+		...options,
+		maxPageSize: HISTORY_PAGE_MAX
+	});
+	return {
+		nodes: items,
+		next_cursor: nextCursor
+	};
+}
+async function listMoveRequests(client, treeId, status, options = {}) {
+	const { items, nextCursor } = await collectPages(client, path("trees", treeId, "move-requests"), status ? { status } : {}, "move_requests", {
+		...options,
+		maxPageSize: HISTORY_PAGE_MAX
+	});
+	return {
+		move_requests: items,
+		next_cursor: nextCursor
+	};
+}
+async function listMoveJobs(client, treeId, status, options = {}) {
+	const { items, nextCursor } = await collectPages(client, path("trees", treeId, "move-jobs"), status ? { status } : {}, "move_jobs", {
+		...options,
+		maxPageSize: HISTORY_PAGE_MAX
+	});
+	return {
+		move_jobs: items,
+		next_cursor: nextCursor
+	};
+}
+async function getMoveRequest(client, id) {
+	return (await client.get(path("move-requests", requireUuid("Move request", id)))).move_request ?? null;
+}
+async function getMoveJob(client, id) {
+	return (await client.get(path("move-jobs", requireUuid("Move job", id)))).move_job ?? null;
+}
+const LEG_MEASURE = "headcount";
+const LEG_COUNTED = "seats: child plus downline_count";
+const LEG_NOTE = "Headcount only; the genealogy API has no leg volume. Counts include retained seats of discarded members.";
+/** Largest first; ties keep the tree's leg order, then node id. */
+function rankLegs(entries, legNames = []) {
+	const order = (leg) => {
+		const index = leg === null ? -1 : legNames.indexOf(leg);
+		return index === -1 ? legNames.length : index;
+	};
+	return [...entries].sort((a, b) => b.seats - a.seats || order(a.leg) - order(b.leg) || (a.node_id ?? "").localeCompare(b.node_id ?? ""));
+}
+/** Each direct child as a leg with its headcount, largest first. Named legs
+*  of a binary or matrix tree with no child are listed with 0 seats. */
+async function readLegs(client, nodeId, options = {}) {
+	const maxChildren = options.maxChildren ?? 200;
+	const [trees, settled] = await Promise.all([listTrees(client).catch((err) => {
+		if (err.status === 403) return null;
+		throw err;
+	}), readSettledLegs(client, nodeId, maxChildren)]);
+	const { anchor, counted } = settled;
+	const treeId = anchor?.tree_id ?? null;
+	const legNames = trees?.find((tree) => tree.id === treeId)?.leg_names ?? [];
+	const occupied = new Set(counted.map((entry) => entry.leg));
+	const free = legNames.filter((leg) => !occupied.has(leg));
+	const hidden = hiddenChildren(anchor, counted);
+	let unlisted;
+	const entries = [...counted];
+	if (hidden) {
+		const unknownEmpty = Math.max(0, free.length - hidden.children);
+		const ranked = hidden.children === 1;
+		if (ranked) entries.push({
+			leg: free.length === 1 ? free[0] ?? null : null,
+			node_id: null,
+			member_id: null,
+			downline_count: hidden.seats - 1,
+			seats: hidden.seats,
+			counts_as_of: anchor?.counts_as_of ?? null,
+			unlisted: true
+		});
+		unlisted = {
+			...hidden,
+			ranked,
+			unknown_empty_legs: unknownEmpty
+		};
+	} else for (const leg of free) entries.push({
+		leg,
+		node_id: null,
+		member_id: null,
+		downline_count: 0,
+		seats: 0,
+		counts_as_of: null
+	});
+	return {
+		measure: LEG_MEASURE,
+		counted: LEG_COUNTED,
+		node_id: nodeId,
+		tree_id: treeId,
+		legs: rankLegs(entries, legNames),
+		...unlisted ? { unlisted } : {},
+		leg_names_known: trees !== null,
+		note: [
+			LEG_NOTE,
+			unlisted ? unlistedNote(unlisted) : null,
+			trees === null ? "Empty named legs are not listed: reading leg names needs developer.view." : null
+		].filter(Boolean).join(" ")
+	};
+}
+function unlistedNote(unlisted) {
+	const { children, seats } = unlisted;
+	const what = `${children} direct ${children === 1 ? "child holds" : "children hold"} a discarded member's seat, which the children read leaves out`;
+	if (unlisted.ranked) return `${what}; it is listed with unlisted: true and its ${seats} ${seats === 1 ? "seat" : "seats"} from the node's counts.${unlisted.unknown_empty_legs > 0 ? " Empty named legs are not listed, since one of them is the leg it holds." : ""}`;
+	return `${what}; their ${seats} seats are not ranked, and empty named legs are not listed because one may hold them.`;
+}
+/** Reads that bracket the leg reads and disagree mean the tree changed
+*  meanwhile; read again this many times. */
+const LEG_READ_ATTEMPTS = 3;
+/** The node's children and each child's counts, read twice between reads
+*  of the node's counts, accepted only when every read agrees. The API has
+*  no read that returns them together, so agreement is what shows that no
+*  child moved in, out or between legs while they were read. */
+async function readSettledLegs(client, nodeId, maxChildren) {
+	for (let attempt = 1;; attempt += 1) {
+		const { node: before } = await readNode(client, nodeId);
+		const first = await readLegPass(client, nodeId, maxChildren);
+		const second = await readLegPass(client, nodeId, maxChildren);
+		const { node: after } = await readNode(client, nodeId);
+		if (sameCounts(before, after) && legKey(first) === legKey(second)) return {
+			anchor: after,
+			counted: second
+		};
+		if (attempt >= LEG_READ_ATTEMPTS) throw new GenealogyError(`Node ${nodeId}'s legs changed during each of ${LEG_READ_ATTEMPTS} reads, so they could not be ranked. Try again.`);
+	}
+}
+/** One read of the children and of each child's counts. */
+async function readLegPass(client, nodeId, maxChildren) {
+	const page = await collectPages(client, path("nodes", nodeId, "children"), {}, "nodes", {
+		limit: maxChildren + 1,
+		maxPageSize: NODE_PAGE_MAX
+	});
+	if (page.items.length > maxChildren) throw new GenealogyError(`Node ${nodeId} has more than ${maxChildren} direct children, and ranking legs reads each child's counts with its own request. Pass --limit <n> to count up to n children.`);
+	return mapLimit(page.items, CONCURRENCY, (child) => readCounts(client, child.id).then((counts) => ({
+		leg: child.leg,
+		node_id: child.id,
+		member_id: child.member_id,
+		downline_count: counts.downline_count,
+		seats: counts.downline_count + 1,
+		counts_as_of: counts.counts_as_of
+	})));
+}
+function sameCounts(a, b) {
+	return a?.children_count === b?.children_count && a?.downline_count === b?.downline_count;
+}
+/** Who holds which leg and how many seats, in a stable order. */
+function legKey(entries) {
+	return entries.map((entry) => `${entry.node_id}:${entry.leg}:${entry.seats}`).sort().join("|");
+}
+/** The node's structural counts include seats of discarded members, which
+*  the children read omits; the difference is what was left out. */
+function hiddenChildren(anchor, counted) {
+	if (typeof anchor?.children_count !== "number") return void 0;
+	const children = anchor.children_count - counted.length;
+	if (children <= 0) return void 0;
+	const rankedSeats = counted.reduce((sum, entry) => sum + entry.seats, 0);
+	return {
+		children,
+		seats: typeof anchor.downline_count === "number" ? Math.max(children, anchor.downline_count - rankedSeats) : children
+	};
+}
+/** The strong leg is the largest by headcount, the weak leg the smallest.
+*  With unlisted children a leg is named only when they cannot change the
+*  pick: one unlisted child is ranked with its exact size; with more, only
+*  a strong leg that outnumbers all their seats together is certain. A
+*  weak pick is withheld while an empty leg cannot be named, including
+*  when the tree's leg names could not be read. */
+function pickLeg(report, which) {
+	const legs = which === "strong" ? report.legs : [...report.legs].reverse();
+	const top = legs[0] ?? null;
+	const base = {
+		measure: report.measure,
+		counted: report.counted,
+		node_id: report.node_id
+	};
+	const tiedWith = (leg) => legs.slice(1).filter((other) => other.seats === leg.seats);
+	const { unlisted } = report;
+	if (which === "strong" ? !unlisted || unlisted.ranked || top !== null && top.seats > unlisted.seats : report.leg_names_known && (!unlisted || unlisted.ranked && unlisted.unknown_empty_legs === 0)) return {
+		...base,
+		leg: top,
+		tied_with: top ? tiedWith(top) : [],
+		...unlisted ? { unlisted } : {},
+		note: top ? report.note : "This node has no legs."
+	};
+	const reason = !report.leg_names_known ? "the tree's leg names could not be read, so an empty named leg may be smaller" : unlisted?.ranked ? "an empty named leg is smaller, but it cannot be told from the leg the unlisted child holds" : "it may be one that is not listed";
+	return {
+		...base,
+		leg: null,
+		tied_with: [],
+		...unlisted ? { unlisted } : {},
+		best_listed: top,
+		note: `${report.note} The ${which} leg cannot be told: ${reason}.${top ? " best_listed is the pick among the listed legs." : ""}`
+	};
+}
+/** Read the subtree to depth (1-7) for `tree`; every page is followed. */
+async function readTree(client, nodeId, depth) {
+	const bounded = toPositiveInt("--depth", depth ?? 3, 7);
+	const result = await readNodePage(client, nodeId, "subtree", { depth: bounded });
+	return {
+		nodes: result.nodes ?? [],
+		depthTruncated: result.depth_truncated ?? false,
+		depth: bounded
+	};
+}
+function label(node) {
+	const leg = node.leg ? ` [${node.leg}]` : "";
+	return `member ${node.member_id}${leg}  (node ${node.id})`;
+}
+/** Indent a subtree page (anchor at relative depth 0) as a text tree. */
+function renderTree(nodes, depthTruncated, depth) {
+	const anchor = nodes.find((node) => node.relative_depth === 0) ?? nodes[0];
+	if (!anchor) return "(no nodes)\n";
+	const children = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		if (node === anchor || !node.parent_node_id) continue;
+		const siblings = children.get(node.parent_node_id) ?? [];
+		siblings.push(node);
+		children.set(node.parent_node_id, siblings);
+	}
+	const lines = [label(anchor)];
+	const walk = (parentId, prefix) => {
+		const kids = children.get(parentId) ?? [];
+		kids.forEach((kid, index) => {
+			const last = index === kids.length - 1;
+			lines.push(`${prefix}${last ? "└── " : "├── "}${label(kid)}`);
+			walk(kid.id, `${prefix}${last ? "    " : "│   "}`);
+		});
+	};
+	walk(anchor.id, "");
+	if (depthTruncated) lines.push(`… more seats below depth ${depth} (depth_truncated)`);
+	return `${lines.join("\n")}\n`;
+}
+const PLACEMENT_RULES = [
+	"exact",
+	"first_empty",
+	"left",
+	"right",
+	"inside",
+	"outside",
+	"balanced",
+	"weak_leg",
+	"strong_leg",
+	"enroller_preference",
+	"defer"
+];
+function placementFields(input) {
+	if (input.rule !== void 0 && !PLACEMENT_RULES.includes(input.rule)) throw new GenealogyError(`--rule must be one of ${PLACEMENT_RULES.join(", ")}.`);
+	const fields = {};
+	if (input.parent !== void 0) fields["parent_node_id"] = input.parent === null ? null : requireUuid("Parent node", input.parent);
+	if (input.leg !== void 0) fields["leg"] = input.leg;
+	if (input.rule !== void 0) fields["rule"] = input.rule;
+	if (input.reason !== void 0) fields["reason"] = input.reason;
+	return fields;
+}
+function withoutMeta(data) {
+	if (data && typeof data === "object") {
+		const { meta: _meta, ...rest } = data;
+		return rest;
+	}
+	return data;
+}
+/** Place a seat waiting in the holding tank. */
+async function placeHeldSeat(client, nodeId, input) {
+	if (input.rule === "defer") throw new GenealogyError("A held seat can't be deferred again.");
+	if (input.parent === void 0) throw new GenealogyError("Pass --parent <node> (or --root) for the seat.");
+	return withoutMeta(await client.post(path("nodes", nodeId, "place"), { placement: placementFields(input) }));
+}
+/** Give a member a new seat in a binary or matrix tree, or hold it in the
+*  holding tank with the rule defer. */
+async function placeMember(client, treeId, memberId, input) {
+	const member = requireUuid("Member", memberId);
+	const position = input.position;
+	if (position !== void 0 && !(Number.isInteger(position) && position >= 0)) throw new GenealogyError("--position must be a whole number, 0 or more.");
+	if (input.rule === "defer") {
+		if (input.parent !== void 0 || input.leg !== void 0 || input.reason !== void 0) throw new GenealogyError("The rule defer takes no --parent, --root, --leg or --reason; give the reason when the held seat is placed.");
+	} else if (input.parent === void 0) throw new GenealogyError("Pass --parent <node> (or --root), or --rule defer to hold the seat.");
+	return withoutMeta(await client.post(path("trees", treeId, "nodes"), { node: {
+		member_id: member,
+		...placementFields(input),
+		...position !== void 0 ? { position } : {}
+	} }));
+}
+function moveBody(input) {
+	return { move: {
+		parent_node_id: input.parent === null ? null : requireUuid("Parent node", input.parent),
+		...input.leg !== void 0 ? { leg: input.leg } : {},
+		...input.reason !== void 0 ? { reason: input.reason } : {}
+	} };
+}
+/** Preview a move; writes and enqueues nothing. */
+async function validateMove(client, nodeId, input) {
+	return { validation: (await client.post(path("nodes", nodeId, "move", "validate"), moveBody(input))).validation ?? null };
+}
+/** Request a move. It applies now (status 200), or returns a move request
+*  awaiting approval or a deferred move job (status 202). */
+async function requestMove(client, nodeId, input, idempotencyKey) {
+	return withoutMeta(await client.post(path("nodes", nodeId, "move"), moveBody(input), idempotencyKey ? { headers: { "Idempotency-Key": idempotencyKey } } : void 0));
+}
+async function approveMoveRequest(client, id, reason) {
+	return withoutMeta(await client.post(path("move-requests", requireUuid("Move request", id), "approve"), reason !== void 0 ? { decision: { reason } } : void 0));
+}
+async function rejectMoveRequest(client, id, reason) {
+	if (!reason || !/\S/.test(reason)) throw new GenealogyError("Rejecting a move request needs --reason <text>.");
+	return withoutMeta(await client.post(path("move-requests", requireUuid("Move request", id), "reject"), { decision: { reason } }));
+}
+/** Map with at most `limit` calls in flight, keeping input order. */
+async function mapLimit(items, limit, fn) {
+	const results = [];
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next;
+			next += 1;
+			results[index] = await fn(items[index]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+//#endregion
+//#region src/index.ts
+async function client(ctx) {
+	return await ctx.getClient();
+}
+/**
+* Placements and moves change the live tree and need an explicit yes.
+* Scripts and agents pass `--yes`; an interactive terminal is asked. With
+* neither, nothing runs.
+*/
+async function confirmChange(question, yes, interactive = Boolean(process.stdin.isTTY)) {
+	if (yes) return;
+	if (!interactive) throw new GenealogyError(`${question} Pass --yes to confirm.`);
+	if (!(await prompts({
+		type: "confirm",
+		name: "ok",
+		message: question,
+		initial: false
+	})).ok) throw new GenealogyError("Cancelled.");
+}
+/** Print a failure as JSON on stderr and exit non-zero, so scripts and
+*  agents can read it the same way as a success. Genealogy errors carry
+*  `error.message` and a machine-readable `error.details.type`. */
+function fail(err) {
+	const status = typeof err.status === "number" ? err.status : void 0;
+	const body = err.body;
+	const nested = body?.["error"];
+	const fromBody = [
+		body?.["error_message"],
+		typeof nested === "object" ? nested?.message : nested,
+		body?.["message"]
+	].find((c) => typeof c === "string");
+	const restated = err instanceof GenealogyError;
+	const message = restated ? err.message : fromBody ?? (err instanceof Error ? err.message : String(err));
+	const details = typeof nested === "object" && nested?.details ? nested.details : void 0;
+	const type = restated && err.type ? err.type : typeof details?.["type"] === "string" ? details["type"] : void 0;
+	const { type: _type, ...reasons } = details ?? {};
+	process.stderr.write(JSON.stringify({
+		error: message,
+		...type ? { type } : {},
+		...status ? { status } : {},
+		...Object.keys(reasons).length > 0 ? { details: reasons } : {}
+	}) + "\n");
+	process.exitCode = 1;
+}
+/** One stderr line per reading while --wait follows a mirror run. */
+function reportMirrorProgress(mirrorRun) {
+	const counts = Object.entries(mirrorRun.counts).map(([outcome, n]) => `${outcome} ${n}`).join(", ");
+	const state = mirrorRunFinished(mirrorRun) ? "finished" : "progress";
+	process.stderr.write(`mirror run ${mirrorRun.id} ${state}: ${mirrorRun.status}, window ${mirrorRun.windows}${counts ? `, ${counts}` : ""}\n`);
+}
+function run(action) {
+	return action().catch(fail);
+}
+function paging(opts) {
+	return {
+		limit: toPositiveInt("--limit", opts.limit),
+		pageSize: toPositiveInt("--page-size", opts.pageSize),
+		cursor: opts.cursor
+	};
+}
+/** A command whose subject is `[node]` or `--member` in `--tree`. */
+function subjectCommand(parent, name, description) {
+	return parent.command(`${name} [node]`).description(description).option("--member <member-id>", "Use this member's seat instead of a node id").option("--tree <key-or-id>", "Tree for --member (key or UUID)", DEFAULT_TREE);
+}
+function withPaging(command, idsOnly = true) {
+	command.option("--limit <n>", "Most rows to return across pages").option("--cursor <cursor>", "Resume from a next_cursor").option("--page-size <n>", "Rows per request");
+	if (idsOnly) command.option("--ids-only", "Return node ids only", false);
+	return command;
+}
+/** Every writable tree field as a flag. Clearable fields take `none`. */
+function withTreeFields(command) {
+	return command.option("--key <key>", "Tree key, unique per company").option("--name <name>", "Display name").option("--kind <kind>", `Tree kind: ${TREE_KINDS.join(", ")}`).option("--role <role>", `Default-tree role: ${TREE_ROLES.join(", ")}, or none`).option("--leg-names <legs>", "Comma-separated legs: two for binary (default left,right), two or more for matrix").option("--placement-rule <rule>", `Default placement rule: ${TREE_PLACEMENT_RULES.join(", ")}. Binary and matrix trees accept exact, first_empty, left, right or defer; unilevel trees exact, under_enroller or mirror_enrollment`).option("--movement-approval <mode>", `Who approves member-requested moves: ${MOVEMENT_APPROVALS.join(", ")}`).option("--holding-tank-days <n>", "Days a deferred seat may wait in the holding tank (0 turns it off)").option("--max-depth <n>", "Deepest level the tree allows").option("--max-movement-levels <n>", "How many levels a member move may cross (0 = no limit)").option("--movement-window-days <n>", "Days after placement during which a seat may move (0 = no window)").option("--volume-on-move <mode>", `Where volume goes when a seat moves: ${VOLUME_ON_MOVE.join(", ")}, or none; required for binary and matrix`).option("--volume-key <key>", "Volume key the tree ranks by, or none").option("--allow-multiple-positions <bool>", "true lets a member hold several seats (matrix trees)").option("--authority <authority>", `Ownership: ${TREE_AUTHORITIES.join(", ")}. Only authoritative trees take placements`).option("--owning-company-integration-id <id>", "Integration that owns a replica tree, or none").option("--upstream-tree-ref <ref>", "The back office's id for a replica tree, or none").option("--external-integration-market-id <id>", "The back office market a replica tree belongs to, or none").option("--dry-run", "Print the request and send nothing", false).option("--yes", "Confirm without a prompt", false);
+}
+/** `trees create | update <tree> | delete <tree>`. Writes show the request
+*  and ask first unless --yes; --dry-run prints it and sends nothing. */
+function registerTreeWrites(trees, ctx) {
+	const send = async (api, write, label, opts, verb) => {
+		if (opts.dryRun) {
+			ctx.output({
+				dry_run: true,
+				request: write
+			});
+			return;
+		}
+		const shown = write.body ?? { params: write.params };
+		await confirmChange(`${verb} tree ${label} with ${write.method} ${write.path} ${JSON.stringify(shown)}?`, opts.yes);
+		ctx.output(await sendTreeWrite(await api(), write, label));
+	};
+	const permission = "Needs an admin login with developer.update; a company API token works if its role grants it.";
+	withTreeFields(trees.command("create").description(`Add a tree definition. --key, --name, --kind and --authority are required. ${permission}`)).action((opts) => run(async () => {
+		await send(() => client(ctx), planCreateTree(opts), String(opts.key), opts, "Create");
+	}));
+	withTreeFields(trees.command("update <tree>").description(`Change a tree definition by key or UUID; sends only the flags given. An occupied tree can only be renamed. ${permission}`)).option("--lock-version <n>", "Update only if the tree is still at this version (default: the current one)").action((tree, opts) => run(async () => {
+		const api = await client(ctx);
+		await send(async () => api, await planUpdateTree(api, tree, opts, opts.lockVersion), tree, opts, "Update");
+	}));
+	trees.command("mirror [tree]").description("Mirror the enrollment tree into the placement tree: seat each enrolled member without a placement seat under their enroller's seat (roots first) and re-parent unpinned seats; pinned seats stay. Idempotent. A real run is queued in the background and printed; --wait follows it to the end. Needs an admin login with members.manage, GENEALOGY_TREE_WRITES, authoritative default trees and the mirror_enrollment rule.").option("--dry-run", "Report at once what would change and write nothing", false).option("--wait", "Follow the run until it finishes; exit non-zero if it fails or halts", false).option("--interval <seconds>", "Seconds between readings with --wait", "2").option("--yes", "Confirm without a prompt", false).action((tree, opts) => run(async () => {
+		const api = await client(ctx);
+		const label = tree ?? "placement";
+		const treeId = await resolveTreeId(api, label);
+		if (opts.dryRun) {
+			ctx.output(await previewMirror(api, treeId));
+			return;
+		}
+		const intervalMs = (toPositiveInt("--interval", opts.interval) ?? 2) * 1e3;
+		await confirmChange(`Mirror the enrollment tree into tree ${label}?`, opts.yes);
+		const started = await startMirror(api, treeId);
+		if (!opts.wait || !started.mirror_run) {
+			ctx.output(started);
+			return;
+		}
+		const finished = await waitForMirrorRun(api, started.mirror_run, {
+			intervalMs,
+			onProgress: reportMirrorProgress
+		});
+		ctx.output({
+			mirror_run: finished,
+			started: started.started
+		});
+		if (finished.status !== "succeeded") throw new GenealogyError(finished.failure_description ?? `Mirror run ${finished.status}`, finished.failure_type ? { type: finished.failure_type } : {});
+	}));
+	const mirrorRuns = trees.command("mirror-runs").description("Read background placement mirror runs");
+	mirrorRuns.command("list").description("List the company's most recent mirror runs, newest first").option("--status <status>", "queued, running, succeeded, failed or halted").option("--limit <n>", "How many runs, 1 to 100 (default 25)").action((opts) => run(async () => {
+		ctx.output(await listMirrorRuns(await client(ctx), {
+			status: opts.status,
+			limit: toPositiveInt("--limit", opts.limit)
+		}));
+	}));
+	mirrorRuns.command("show <id>").description("Read a mirror run's progress").action((id) => run(async () => {
+		ctx.output({ mirror_run: await getMirrorRun(await client(ctx), id) });
+	}));
+	trees.command("delete <tree>").description(`Delete a custom tree by key or UUID. It fails with tree_has_nodes while the tree holds any seat, and the default enrollment and placement trees can't be deleted. ${permission}`).option("--lock-version <n>", "Delete only if the tree is still at this version (default: the current one)").option("--dry-run", "Print the request and send nothing", false).option("--yes", "Confirm without a prompt", false).action((tree, opts) => run(async () => {
+		const api = await client(ctx);
+		await send(async () => api, await planDeleteTree(api, tree, opts.lockVersion), tree, opts, "Delete");
+	}));
+}
+function registerGenealogyCommands(parent, ctx) {
+	const subject = async (api, node, opts) => resolveSubject(api, node, opts.member, opts.tree);
+	registerTreeWrites(parent.command("trees").description("List the company's genealogy tree definitions, or create, update or delete one (needs developer.view; writes need developer.update)").action(() => run(async () => ctx.output({ trees: await listTrees(await client(ctx)) }))), ctx);
+	subjectCommand(parent, "show", "Read a node, with child and downline counts").option("--as-of <time>", "Read the recorded placement at this time").action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		ctx.output(await readNode(api, await subject(api, node, opts), opts.asOf));
+	}));
+	subjectCommand(parent, "counts", "Children and downline counts (retained seats, including discarded members)").action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		ctx.output(await readCounts(api, await subject(api, node, opts)));
+	}));
+	for (const [operation, description, asOf] of [
+		[
+			"parent",
+			"Read the parent node (null for a root)",
+			true
+		],
+		[
+			"root",
+			"Read the root of the node's tree",
+			true
+		],
+		[
+			"sponsor",
+			"Read the sponsor: the parent in the sponsor-role tree",
+			false
+		],
+		[
+			"enroller",
+			"Read the enroller: the parent in the enrollment-role tree",
+			false
+		]
+	]) {
+		const command = subjectCommand(parent, operation, description);
+		if (asOf) command.option("--as-of <time>", "Read as of this time");
+		command.action((node, opts) => run(async () => {
+			const api = await client(ctx);
+			const id = await subject(api, node, opts);
+			ctx.output(await readRelative(api, id, operation, opts.asOf));
+		}));
+	}
+	for (const [operation, description, extra] of [
+		[
+			"ancestors",
+			"List ancestors, root first",
+			"asOf"
+		],
+		[
+			"children",
+			"List direct children",
+			null
+		],
+		[
+			"siblings",
+			"List siblings (excluding the node)",
+			null
+		],
+		[
+			"frontline",
+			"List direct children in the sponsor-role tree",
+			null
+		],
+		[
+			"personally-enrolled",
+			"List direct children in the enrollment-role tree",
+			null
+		],
+		[
+			"descendants",
+			"List descendants to --depth",
+			"depth"
+		],
+		[
+			"subtree",
+			"List the node and its descendants to --depth",
+			"depth"
+		],
+		[
+			"level",
+			"List the nodes exactly --depth levels down",
+			"depth"
+		]
+	]) {
+		const command = withPaging(subjectCommand(parent, operation, description), operation !== "ancestors");
+		if (extra === "depth") command.option("--depth <n>", `Relative depth, 1-7`);
+		if (extra) command.option("--as-of <time>", "Read as of this time");
+		command.action((node, opts) => run(async () => {
+			const api = await client(ctx);
+			const id = await subject(api, node, opts);
+			ctx.output(await readNodePage(api, id, operation, {
+				...paging(opts),
+				depth: opts.depth,
+				asOf: opts.asOf,
+				idsOnly: opts.idsOnly
+			}));
+		}));
+	}
+	withPaging(subjectCommand(parent, "grandchildren", "List the nodes two levels down")).option("--as-of <time>", "Read as of this time").action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		const id = await subject(api, node, opts);
+		ctx.output(await readGrandchildren(api, id, {
+			...paging(opts),
+			asOf: opts.asOf,
+			idsOnly: opts.idsOnly
+		}));
+	}));
+	subjectCommand(parent, "level-counts", "Count seats at each level to --depth").option("--depth <n>", `Relative depth, 1-7`).action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		const id = await subject(api, node, opts);
+		ctx.output(await readLevelCounts(api, id, opts.depth));
+	}));
+	parent.command("relation <node> <other>").description("How <node> relates to <other>: one --kind, or every kind (for within_downline, <other> is the root)").option("--kind <kind>", "ancestor_of, descendant_of, parent_of, child_of, sibling_of, root_of, indirect_of, in_subtree_of or within_downline").action((node, other, opts) => run(async () => {
+		const api = await client(ctx);
+		const id = await resolveSubject(api, node, void 0);
+		ctx.output(await readRelation(api, id, other, opts.kind));
+	}));
+	withPaging(subjectCommand(parent, "placements", "List recorded placements, newest first"), false).action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		const id = await subject(api, node, opts);
+		ctx.output(await readPlacements(api, id, paging(opts)));
+	}));
+	withPaging(parent.command("holding-tank").description("List seats waiting in a tree's holding tank, soonest due first").option("--tree <key-or-id>", "Tree (key or UUID)", DEFAULT_TREE), false).action((opts) => run(async () => {
+		const api = await client(ctx);
+		const treeId = await resolveTreeId(api, opts.tree);
+		ctx.output(await readHoldingTank(api, treeId, paging(opts)));
+	}));
+	const legLimit = (command) => command.option("--limit <n>", `Most direct children to count, one request each (default 200); more is an error`);
+	const legOptions = (opts) => ({ maxChildren: toPositiveInt("--limit", opts.limit) });
+	legLimit(subjectCommand(parent, "legs", "Rank the node's legs by headcount (child plus its downline), largest first")).action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		ctx.output(await readLegs(api, await subject(api, node, opts), legOptions(opts)));
+	}));
+	for (const which of ["strong", "weak"]) legLimit(subjectCommand(parent, `${which}-leg`, `The ${which === "strong" ? "largest" : "smallest"} leg by headcount`)).action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		const report = await readLegs(api, await subject(api, node, opts), legOptions(opts));
+		ctx.output(pickLeg(report, which));
+	}));
+	subjectCommand(parent, "tree", "Print the downline as an indented text tree").option("--depth <n>", `Levels to show, 1-7`, "3").action((node, opts) => run(async () => {
+		const api = await client(ctx);
+		const read = await readTree(api, await subject(api, node, opts), opts.depth);
+		process.stdout.write(renderTree(read.nodes, read.depthTruncated, read.depth));
+	}));
+	subjectCommand(parent, "place", "Place a held seat, or with --member give that member a new seat in --tree (changes the live tree)").option("--parent <node>", "Parent seat, or where a rule's search starts").option("--root", "Place as a root seat", false).option("--leg <leg>", "Leg under the parent, e.g. left or right; with neither --leg nor --rule the tree's default rule applies").option("--rule <rule>", "Placement rule, e.g. first_empty, left, right, defer").option("--position <n>", "Seat position (matrix trees with multiple positions)").option("--reason <text>", "Reason recorded on the placement").option("--yes", "Confirm without a prompt", false).action((node, opts) => run(async () => {
+		if (opts.parent && opts.root) throw new GenealogyError("Pass --parent or --root, not both.");
+		if (node && opts.member) throw new GenealogyError("Pass a held node id or --member, not both.");
+		const api = await client(ctx);
+		const input = {
+			parent: opts.root ? null : opts.parent,
+			leg: opts.leg,
+			rule: opts.rule,
+			reason: opts.reason
+		};
+		if (opts.member) {
+			const treeId = await resolveTreeId(api, opts.tree);
+			await confirmChange(`Place member ${opts.member} in tree ${opts.tree}?`, opts.yes);
+			ctx.output(await placeMember(api, treeId, opts.member, {
+				...input,
+				position: opts.position === void 0 ? void 0 : Number(opts.position)
+			}));
+			return;
+		}
+		if (opts.position !== void 0) throw new GenealogyError("--position applies only with --member; a held seat keeps its stored position.");
+		const id = await resolveSubject(api, node, void 0);
+		await confirmChange(`Place held seat ${id}?`, opts.yes);
+		ctx.output(await placeHeldSeat(api, id, input));
+	}));
+	subjectCommand(parent, "move", "Move a node under a new parent (changes the live tree); --validate previews only").option("--to <node>", "New parent node").option("--to-member <member-id>", "New parent: this member's seat in --tree").option("--to-root", "Make the node a root", false).option("--leg <leg>", "Leg under the new parent (binary and matrix trees)").option("--reason <text>", "Reason recorded on the move").option("--validate", "Preview the move without changing anything", false).option("--dry-run", "Same as --validate", false).option("--idempotency-key <key>", "Make a retried request safe to repeat").option("--yes", "Confirm without a prompt", false).action((node, opts) => run(async () => {
+		if ([
+			opts.to,
+			opts.toMember,
+			opts.toRoot || void 0
+		].filter((d) => d !== void 0).length !== 1) throw new GenealogyError("Pass exactly one of --to <node>, --to-member <member-id> or --to-root.");
+		const api = await client(ctx);
+		const id = await subject(api, node, opts);
+		const parentId = opts.toRoot ? null : await resolveSubject(api, opts.to, opts.toMember, opts.tree);
+		const input = {
+			parent: parentId,
+			leg: opts.leg,
+			reason: opts.reason
+		};
+		if (opts.validate || opts.dryRun) {
+			ctx.output(await validateMove(api, id, input));
+			return;
+		}
+		await confirmChange(`Move ${id} ${parentId ? `under ${parentId}` : "to a root"}?`, opts.yes);
+		ctx.output(await requestMove(api, id, input, opts.idempotencyKey));
+	}));
+	const requests = parent.command("move-requests").description("List, read, approve or reject move requests");
+	withPaging(requests.command("list").description("List a tree's move requests").option("--tree <key-or-id>", "Tree (key or UUID)", DEFAULT_TREE).option("--status <status>", "pending, approved, rejected, withdrawn, superseded or expired"), false).action((opts) => run(async () => {
+		const api = await client(ctx);
+		const treeId = await resolveTreeId(api, opts.tree);
+		ctx.output(await listMoveRequests(api, treeId, opts.status, paging(opts)));
+	}));
+	requests.command("show <id>").description("Read a move request").action((id) => run(async () => {
+		ctx.output({ move_request: await getMoveRequest(await client(ctx), id) });
+	}));
+	requests.command("approve <id>").description("Approve a move request (changes the live tree)").option("--reason <text>", "Reason recorded on the decision").option("--yes", "Confirm without a prompt", false).action((id, opts) => run(async () => {
+		await confirmChange(`Approve move request ${id}?`, opts.yes);
+		ctx.output(await approveMoveRequest(await client(ctx), id, opts.reason));
+	}));
+	requests.command("reject <id>").description("Reject a move request with a reason").requiredOption("--reason <text>", "Why the request is rejected").option("--yes", "Confirm without a prompt", false).action((id, opts) => run(async () => {
+		await confirmChange(`Reject move request ${id}?`, opts.yes);
+		ctx.output(await rejectMoveRequest(await client(ctx), id, opts.reason));
+	}));
+	const jobs = parent.command("move-jobs").description("Read deferred move jobs");
+	jobs.command("show <id>").description("Read a move job's progress").action((id) => run(async () => {
+		ctx.output({ move_job: await getMoveJob(await client(ctx), id) });
+	}));
+	withPaging(jobs.command("list").description("List a tree's move jobs").option("--tree <key-or-id>", "Tree (key or UUID)", DEFAULT_TREE).option("--status <status>", "pending, running, applied, failed or superseded"), false).action((opts) => run(async () => {
+		const api = await client(ctx);
+		const treeId = await resolveTreeId(api, opts.tree);
+		ctx.output(await listMoveJobs(api, treeId, opts.status, paging(opts)));
+	}));
+}
+const plugin = {
+	name: "@fluid-app/fluid-cli-genealogy",
+	version: "0.1.0",
+	register(ctx) {
+		ctx.program.addCommand(createDomainCommand("genealogy", "Read genealogy trees, rank legs, and place or move members", registerGenealogyCommands));
+	}
+};
+//#endregion
+export { confirmChange, plugin as default, registerGenealogyCommands };
+
+//# sourceMappingURL=index.mjs.map