@fluid-app/fluid-cli-connect 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1603 @@
+import prompts from "prompts";
+import { NAV_HELP, assertInteractive, createDomainCommand, terminalPrompter } from "@fluid-app/fluid-cli";
+//#region src/providers.ts
+const MSSQL_CREDENTIALS = [
+	{
+		key: "mssql.dataserver",
+		label: "SQL Server host (data server)"
+	},
+	{
+		key: "mssql.database",
+		label: "SQL Server database name"
+	},
+	{
+		key: "mssql.username",
+		label: "SQL Server login username"
+	},
+	{
+		key: "mssql.password",
+		label: "SQL Server login password",
+		secret: true
+	}
+];
+const PROVIDERS = {
+	exigo: {
+		label: "Exigo",
+		slug: "exigo",
+		dropletName: "Exigo",
+		credentialGroups: ["api", "mssql"],
+		credentials: [
+			{
+				key: "api.company",
+				label: "Exigo company login (company code)"
+			},
+			{
+				key: "api.username",
+				label: "Exigo API service-account username"
+			},
+			{
+				key: "api.password",
+				label: "Exigo API service-account password",
+				secret: true
+			},
+			...MSSQL_CREDENTIALS
+		],
+		environments: true,
+		targetOptions: true
+	},
+	bydesign: {
+		label: "ByDesign",
+		slug: "bydesign",
+		dropletName: "ByDesign",
+		credentialGroups: ["api"],
+		credentials: [
+			{
+				key: "api.company",
+				label: "ByDesign tenant (company) code"
+			},
+			{
+				key: "api.username",
+				label: "ByDesign API service-account username"
+			},
+			{
+				key: "api.password",
+				label: "ByDesign API service-account password",
+				secret: true
+			},
+			{
+				key: "api.api_url",
+				label: "Freedom API host (blank for Fluid's default)",
+				optional: true
+			}
+		],
+		environments: false,
+		targetOptions: false
+	},
+	infotrax: {
+		label: "InfoTrax",
+		slug: "infotrax",
+		dropletName: "Infotrax",
+		credentialGroups: ["api", "mssql"],
+		credentials: MSSQL_CREDENTIALS,
+		environments: false,
+		targetOptions: false
+	},
+	pillars: {
+		label: "Pillars",
+		slug: "pillars",
+		dropletName: "Pillars",
+		credentialGroups: ["api"],
+		credentials: [{
+			key: "api.token",
+			label: "Pillars API token",
+			secret: true
+		}, {
+			key: "api.api_url",
+			label: "Pillars API base URL"
+		}],
+		environments: false,
+		targetOptions: false
+	}
+};
+const PROVIDER_IDS = Object.keys(PROVIDERS);
+/** Scopes the Connect droplet is installed with (the same set Mist uses). */
+const CONNECT_DROPLET_SCOPES = [
+	"main",
+	"members",
+	"prospects",
+	"products",
+	"orders",
+	"users",
+	"settings"
+];
+var ConnectError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConnectError";
+	}
+};
+function providerOf(id) {
+	const key = id.trim().toLowerCase();
+	if (!(key in PROVIDERS)) throw new ConnectError(`Unknown provider "${id}". Use one of: ${PROVIDER_IDS.join(", ")}.`);
+	return {
+		id: key,
+		...PROVIDERS[key]
+	};
+}
+/** fluid-integrations, where Connect's configuration lives. It accepts the
+*  same Fluid API token the CLI sends to api.fluid.app. */
+function integrationsBase() {
+	return (process.env["FLUID_INTEGRATIONS_BASE"] ?? "https://fluid-integrations-106074092699.us-west3.run.app").trim().replace(/\/$/, "");
+}
+/** The provider's integration as fluid-integrations sees this company. */
+async function providerStatus(integrations, provider) {
+	let wire;
+	try {
+		wire = await integrations.get(`/api/v1/integrations/${provider.slug}`);
+	} catch (error) {
+		if (error.status === 404) throw new ConnectError(`${provider.label} isn't available on fluid-integrations for this company.`);
+		throw error;
+	}
+	const ciId = wire.company_integration_id ?? null;
+	return {
+		provider: provider.id,
+		label: provider.label,
+		installed: ciId !== null,
+		connected: wire.is_connected === true,
+		companyIntegrationId: ciId,
+		dropletUuid: wire.droplet_uuid ?? null,
+		integrationId: wire.id ?? null
+	};
+}
+/** The company integration id, or a ConnectError saying to install first. */
+async function companyIntegrationId(integrations, provider) {
+	const status = await providerStatus(integrations, provider);
+	if (status.companyIntegrationId === null) throw new ConnectError(`${provider.label} isn't installed for this company. Run \`fluid connect install ${provider.id} --yes\` first.`);
+	return status.companyIntegrationId;
+}
+async function getCompanyIntegration(integrations, ciId) {
+	return integrations.get(`/api/v1/company_integrations/${ciId}`);
+}
+/** Save credentials. fluid-integrations tests the connection with them and
+*  answers 422 with the reason when it fails, so nothing broken is saved. */
+async function setCredentials(integrations, ciId, authSettings) {
+	await integrations.put(`/api/v1/company_integrations/${ciId}`, { company_integration: { auth_settings: authSettings } });
+	return { saved: true };
+}
+/**
+* Save credentials, creating the connection when the droplet is installed
+* but its install hasn't created the connection yet (the same request
+* Fluid's admin makes). Without an installed droplet nothing is created, so
+* `install` still installs it. Either way fluid-integrations tests the
+* connection first and answers 422 with the reason when it fails, so
+* nothing broken is saved.
+*/
+async function saveCredentials(integrations, fluid, provider, authSettings) {
+	const status = await providerStatus(integrations, provider);
+	if (status.companyIntegrationId !== null) {
+		await setCredentials(integrations, status.companyIntegrationId, authSettings);
+		return {
+			saved: true,
+			created: false,
+			companyIntegrationId: status.companyIntegrationId
+		};
+	}
+	const dropletUuid = status.dropletUuid ?? await findDropletUuid(fluid, provider).catch(() => null);
+	if (status.integrationId === null || dropletUuid === null || !await dropletInstalled(fluid, dropletUuid)) throw new ConnectError(`${provider.label} isn't installed for this company. Run \`fluid connect install ${provider.id} --yes\` first.`);
+	const created = await integrations.post("/api/v1/company_integrations", { company_integration: {
+		integration_id: status.integrationId,
+		name: provider.label,
+		droplet_uuid: dropletUuid,
+		auth_settings: authSettings
+	} });
+	const id = created?.id ?? created?.data?.id ?? (await providerStatus(integrations, provider)).companyIntegrationId;
+	if (typeof id !== "number") throw new ConnectError(`${provider.label} accepted the credentials, but the connection's id didn't come back. Run \`fluid connect show ${provider.id}\`.`);
+	return {
+		saved: true,
+		created: true,
+		companyIntegrationId: id
+	};
+}
+/** Merge a sync-settings patch into the saved settings. */
+async function updateSyncSettings(integrations, ciId, patch) {
+	await integrations.put(`/api/v1/company_integrations/${ciId}`, { company_integration: { sync_settings: patch } });
+	return getCompanyIntegration(integrations, ciId);
+}
+/** A mapping type as its route names it, e.g. `customer_type`. */
+function mappingPath(ciId, type) {
+	if (!/^[a-z_]+$/.test(type)) throw new ConnectError(`"${type}" isn't a mapping type. Use names like customer_type or warehouse (see \`fluid connect show\`).`);
+	return `/api/v1/company_integrations/${ciId}/${type}_mappings`;
+}
+async function listMappings(integrations, ciId, type) {
+	return integrations.get(mappingPath(ciId, type));
+}
+/** Values to choose from: Fluid's for the source side, and for Exigo also
+*  Exigo's own for the target side. */
+async function mappingOptions(integrations, ciId, type, provider) {
+	let fluid = null;
+	try {
+		fluid = await integrations.get(`${mappingPath(ciId, type)}/source_options`);
+	} catch (error) {
+		if (error.status !== 404) throw error;
+		if (!provider.targetOptions) throw error;
+	}
+	if (!provider.targetOptions) return { fluid };
+	return {
+		fluid,
+		provider: await integrations.get(`${mappingPath(ciId, type)}/exigo_options`)
+	};
+}
+/** Create one mapping row. `fields` are the row's attributes, wrapped in
+*  the singular resource key the API expects (`customer_type_mapping`). */
+async function createMapping(integrations, ciId, type, fields) {
+	return integrations.post(mappingPath(ciId, type), { [`${type}_mapping`]: fields });
+}
+async function deleteMapping(integrations, ciId, type, id) {
+	await integrations.delete(`${mappingPath(ciId, type)}/${id}`);
+	return {
+		deleted: true,
+		id
+	};
+}
+/** Whether the company has the droplet installed and active in Fluid (one
+*  pending uninstall is listed, but inactive). */
+async function dropletInstalled(fluid, dropletUuid) {
+	for (let page = 1; page <= CATALOG_PAGES; page += 1) {
+		const data = await fluid.get("/api/droplet_installations", {
+			page,
+			per_page: 100
+		});
+		const rows = data.droplet_installations ?? [];
+		if (rows.some((row) => row.droplet_uuid === dropletUuid && row.active !== false)) return true;
+		const totalPages = data.meta?.pagination?.total_pages ?? 1;
+		if (page >= totalPages || rows.length < 100) break;
+	}
+	return false;
+}
+const CATALOG_PAGES = 10;
+/** Install the provider's droplet in Fluid, which creates its company
+*  integration on fluid-integrations. */
+async function installProvider(fluid, provider, officialUuid = null) {
+	const dropletUuid = officialUuid ?? await findDropletUuid(fluid, provider);
+	await fluid.post("/api/droplet_installations", {
+		droplet_uuid: dropletUuid,
+		scopes: CONNECT_DROPLET_SCOPES
+	});
+	return {
+		installed: true,
+		dropletUuid
+	};
+}
+async function findDropletUuid(fluid, provider) {
+	const wanted = provider.dropletName.toLowerCase();
+	const matches = /* @__PURE__ */ new Set();
+	for (let page = 1; page <= CATALOG_PAGES; page += 1) {
+		const data = await fluid.get("/api/droplets", {
+			page,
+			per_page: 100
+		});
+		for (const droplet of data.droplets ?? []) if (droplet.uuid && droplet.name?.trim().toLowerCase() === wanted) matches.add(droplet.uuid);
+		const totalPages = data.meta?.pagination?.total_pages ?? 1;
+		if (page >= totalPages || (data.droplets ?? []).length < 100) break;
+	}
+	if (matches.size === 1) return [...matches][0];
+	if (matches.size > 1) throw new ConnectError(`More than one droplet is named ${provider.dropletName}, and fluid-integrations didn't say which is ${provider.label}'s. Ask Fluid to check the ${provider.label} integration's droplet.`);
+	throw new ConnectError(`The ${provider.label} droplet isn't in this company's droplet catalog. Ask Fluid to make it available.`);
+}
+//#endregion
+//#region src/settings.ts
+/**
+* Parse `--set` values into the nested object the API takes.
+*
+* `api.username=alice` → `{ api: { username: "alice" } }`. Values that read
+* as JSON (true, 42, ["a","b"], {"x":1}) are parsed; anything else stays a
+* string, so a password like `abc123` is never mangled.
+*/
+function parseAssignments(assignments, opts = {}) {
+	const out = {};
+	for (const assignment of assignments) {
+		const at = assignment.indexOf("=");
+		if (at <= 0) throw new ConnectError(`"${assignment}" isn't key=value. Use dots for nesting, e.g. api.username=alice.`);
+		const path = assignment.slice(0, at).split(".");
+		if (path.some((part) => part.length === 0)) throw new ConnectError(`"${assignment}" has an empty key segment.`);
+		if (path.some((part) => UNSAFE_KEYS.has(part))) throw new ConnectError(`"${assignment}" uses a reserved key name.`);
+		const raw = assignment.slice(at + 1);
+		setPath$1(out, path, opts.strings ? raw : parseValue(raw));
+	}
+	return out;
+}
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function parseValue(raw) {
+	if (/^(true|false|null|-?\d+(\.\d+)?)$/.test(raw) || /^[[{]/.test(raw)) try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+	return raw;
+}
+function setPath$1(target, path, value) {
+	let node = target;
+	for (const key of path.slice(0, -1)) {
+		const next = node[key];
+		if (typeof next !== "object" || next === null || Array.isArray(next)) node[key] = {};
+		node = node[key];
+	}
+	node[path[path.length - 1]] = value;
+}
+/**
+* Sync settings are saved per entity as the schema entry itself, with the
+* chosen value under `value`: `entities.<entity>.settings.<key>.value`.
+* `--set` takes the short `<entity>.<key>=value` form `fluid connect
+* settings` prints, and this expands it. Exigo's `sponsor_tree` is the one
+* top-level setting (`sync_settings.sponsor_tree.value`); write it as
+* `sponsor_tree.sponsor_tree=value`.
+*/
+function syncSettingsPatch(assignments) {
+	const entries = [];
+	for (const assignment of assignments) {
+		const parsed = parseAssignments([assignment]);
+		const [group, values] = Object.entries(parsed)[0];
+		if (typeof values !== "object" || values === null || Array.isArray(values)) throw new ConnectError(`"${assignment}" needs an entity and a setting, e.g. order.refund_handling=hold.`);
+		for (const [key, value] of Object.entries(values)) entries.push([`${group}.${key}`, value]);
+	}
+	return patchFromEntries(entries);
+}
+/**
+* A patch that puts settings back to their schema defaults: all of them,
+* or only the `<entity>.<key>` names in `only`. Unknown names are refused
+* rather than silently skipped.
+*/
+function defaultsPatch(schema, only = []) {
+	const all = Object.entries(schema).flatMap(([entity, settings]) => Object.entries(settings).map(([key, setting]) => [`${entity}.${key}`, setting.value]));
+	const withDefault = all.filter(([, value]) => value !== void 0);
+	if (only.length === 0) return patchFromEntries(withDefault);
+	const known = new Map(all);
+	const unknown = only.filter((key) => !known.has(key));
+	if (unknown.length > 0) throw new ConnectError(`Unknown setting(s): ${unknown.join(", ")}. List them with \`fluid connect settings <provider>\`.`);
+	const noDefault = only.filter((key) => known.get(key) === void 0);
+	if (noDefault.length > 0) throw new ConnectError(`No default to restore for: ${noDefault.join(", ")}.`);
+	return patchFromEntries(only.map((key) => [key, known.get(key)]));
+}
+/** Settings worth deciding before the first sync, in the order the setup
+*  guides list them. A provider without one of them skips it. */
+const COMMON_SETTINGS = [
+	"customer.duplicate_customer_handling",
+	"customer.unverified_customer_handling",
+	"customer.customer_creation_sync",
+	"customer.customer_changelog_sync",
+	"order.refund_handling",
+	"order.duplicate_order_handling",
+	"order.order_creation_sync",
+	"order.order_changelog_sync",
+	"product.new_inactive",
+	"product.warehouseless_product_handling",
+	"rank.sync_ranks",
+	"rank.pulled_from",
+	"sponsor_tree.sponsor_tree",
+	"customer.fetch_mode",
+	"order_payment.skip_payment_on_export"
+];
+/** A patch setting `<entity>.<key>` names to values exactly as given (no
+*  parsing), in the shape `--set` and `--defaults` send. */
+function settingsPatch(values) {
+	return patchFromEntries(Object.entries(values));
+}
+function patchFromEntries(entries) {
+	const entities = {};
+	const patch = {};
+	for (const [name, value] of entries) {
+		const at = name.indexOf(".");
+		const group = name.slice(0, at);
+		const key = name.slice(at + 1);
+		if (group === "sponsor_tree" && key === "sponsor_tree") {
+			patch["sponsor_tree"] = { value };
+			continue;
+		}
+		entities[group] ??= { settings: {} };
+		entities[group].settings[key] = { value };
+	}
+	if (Object.keys(entities).length > 0) patch["entities"] = entities;
+	return patch;
+}
+//#endregion
+//#region src/summary.ts
+/**
+* Every sync setting the provider supports, with the value saved for this
+* company next to the default. Saved values live at
+* `entities.<entity>.settings.<key>.value` (Exigo's `sponsor_tree` at
+* `sponsor_tree.value`); a setting never saved reads as its default.
+*/
+function summarizeSettings(ci) {
+	const schema = ci.settings_schema ?? {};
+	const saved = ci.sync_settings ?? {};
+	const out = [];
+	for (const [entity, settings] of Object.entries(schema)) for (const [name, setting] of Object.entries(settings)) out.push(summarize(entity, name, setting, savedValue(saved, entity, name)));
+	return out;
+}
+function summarize(entity, name, setting, saved) {
+	return {
+		key: `${entity}.${name}`,
+		label: setting.label ?? null,
+		description: setting.description ?? null,
+		type: setting.type ?? null,
+		value: saved.found ? saved.value : setting.value ?? null,
+		default: setting.value ?? null,
+		...setting.options ? { options: setting.options.map((o) => o.value) } : {},
+		...setting.multiple !== void 0 ? { multiple: setting.multiple } : {},
+		...setting.depends_on ? { dependsOn: setting.depends_on } : {}
+	};
+}
+function savedValue(saved, entity, name) {
+	const entry = entity === "sponsor_tree" && name === "sponsor_tree" ? saved["sponsor_tree"] : dig(saved, [
+		"entities",
+		entity,
+		"settings",
+		name
+	]);
+	if (entry && typeof entry === "object" && "value" in entry) return {
+		found: true,
+		value: entry.value
+	};
+	return {
+		found: false,
+		value: void 0
+	};
+}
+function dig(node, path) {
+	let current = node;
+	for (const key of path) {
+		if (!current || typeof current !== "object") return void 0;
+		current = current[key];
+	}
+	return current;
+}
+//#endregion
+//#region src/unmapped.ts
+/** The field each mapping type keeps the Fluid (source) value in. A row
+*  whose source is `*` is the fallback for every value without its own row. */
+const SOURCE_FIELD = {
+	customer_type: "source_type_slug",
+	customer_status: "source_status_slug",
+	order_status: "source_status_slug",
+	order_type: "source_type_slug",
+	payable_type: "source_type_slug",
+	price_type: "source_price_type_title",
+	warehouse: "source_warehouse_title",
+	customer_warehouse: "source_country_code",
+	payment_type: "source_payment_method",
+	wallet_type: "source_payment_method",
+	fraud_decision: "source_decision",
+	ship_method: "source_shipping_method_title",
+	product_type: "source_title",
+	country_market: "source_title",
+	tree: "source_title",
+	rank: "source_title"
+};
+/** The field each mapping type keeps the provider's (target) value in. */
+const TARGET_FIELD = {
+	customer_type: "target_type_id",
+	customer_status: "target_status_id",
+	order_status: "target_status_id",
+	order_type: "target_type_id",
+	payable_type: "target_payable_id",
+	price_type: "target_price_type_id",
+	warehouse: "external_warehouse_id",
+	customer_warehouse: "target_warehouse_id",
+	payment_type: "target_payment_type",
+	wallet_type: "target_wallet_type_id",
+	fraud_decision: "target_field_value",
+	ship_method: "exigo_ship_method_id",
+	product_type: "target_title",
+	country_market: "target_title",
+	tree: "target_title",
+	rank: "target_title"
+};
+/** Types whose Fluid values the API lists (`source_options`), with a
+*  `mapped` flag on each. Ranks and ship methods have no such list. */
+const LISTS_FLUID_VALUES = new Set([
+	"customer_type",
+	"customer_status",
+	"order_status",
+	"order_type",
+	"payable_type",
+	"price_type",
+	"warehouse",
+	"customer_warehouse",
+	"payment_type",
+	"wallet_type",
+	"fraud_decision",
+	"currency_point_account",
+	"product_type",
+	"country_market",
+	"tree"
+]);
+/** How to build a row from a Fluid option and the Exigo option with the
+*  same title. Only types whose target is an Exigo id are listed: a title
+*  match then names exactly one Exigo record. */
+const AUTO_MAP = {
+	customer_type: (f, p) => f.slug ? {
+		source_type_slug: f.slug,
+		target_type_id: String(p.id)
+	} : null,
+	customer_status: (f, p) => f.slug ? {
+		source_status_slug: f.slug,
+		target_status_id: String(p.id)
+	} : null,
+	order_status: (f, p) => f.slug ? {
+		source_status_slug: f.slug,
+		target_status_id: String(p.id)
+	} : null,
+	order_type: (f, p) => f.slug ? {
+		source_type_slug: f.slug,
+		target_type_id: String(p.id)
+	} : null,
+	payable_type: (f, p) => f.slug ? {
+		source_type_slug: f.slug,
+		target_payable_id: String(p.id)
+	} : null,
+	price_type: (f, p) => f.title ? {
+		source_price_type_title: f.title,
+		target_price_type_id: String(p.id)
+	} : null,
+	warehouse: (f, p) => f.title && f.id !== void 0 ? {
+		fluid_warehouse_id: f.id,
+		source_warehouse_title: f.title,
+		external_warehouse_id: String(p.id)
+	} : null
+};
+const norm = (text) => (text ?? "").trim().toLowerCase();
+/** The value a row's source field takes for a Fluid option: the title for
+*  fields keyed by title (`source_price_type_title`), else the slug. */
+function sourceValue(option, sourceField) {
+	const value = sourceField?.endsWith("_title") ? option.title ?? option.slug ?? option.id : option.slug ?? option.title ?? option.id;
+	return String(value ?? "");
+}
+/** Pair unmapped Fluid options with provider options whose title matches
+*  exactly (ignoring case and edge spaces). A title that more than one
+*  provider option shares is ambiguous and left for a person. */
+function exactTitleMatches(unmapped, providerOptions) {
+	const byTitle = /* @__PURE__ */ new Map();
+	for (const option of providerOptions) {
+		const key = norm(option.title);
+		if (!key || option.id === void 0 || option.id === null) continue;
+		byTitle.set(key, [...byTitle.get(key) ?? [], option]);
+	}
+	const pairs = [];
+	for (const fluid of unmapped) {
+		const candidates = byTitle.get(norm(fluid.title)) ?? [];
+		if (candidates.length === 1) pairs.push({
+			fluid,
+			provider: candidates[0]
+		});
+	}
+	return pairs;
+}
+function optionsOf(response) {
+	const options = response?.options;
+	return Array.isArray(options) ? options : [];
+}
+function rowsOf(response, type) {
+	const rows = response?.[`${type}_mappings`];
+	return Array.isArray(rows) ? rows : [];
+}
+function errorText(error) {
+	const body = error.body;
+	const detail = body?.["error"] ?? body?.["errors"];
+	if (typeof detail === "string") return detail;
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* For every mapping type the provider supports, the Fluid values that still
+* need a row. With `autoMap`, rows are first created for values whose title
+* matches exactly one provider value (Exigo only, and only types whose target
+* is an id), so what's returned is what a person still has to decide.
+*/
+async function unmappedReport(integrations, ciId, provider, autoMap) {
+	const types = ((await getCompanyIntegration(integrations, ciId)).supported_mappings ?? []).map((card) => card.replace(/_title$/, "")).filter((type) => type in SOURCE_FIELD || LISTS_FLUID_VALUES.has(type));
+	const reports = [];
+	for (const type of types) reports.push(await reportFor(integrations, ciId, provider, type, autoMap));
+	return reports;
+}
+async function reportFor(integrations, ciId, provider, type, autoMap) {
+	const sourceField = SOURCE_FIELD[type] ?? null;
+	if (!LISTS_FLUID_VALUES.has(type)) return {
+		type,
+		status: "check_by_hand",
+		sourceField
+	};
+	const autoMapped = [];
+	try {
+		const path = mappingPath(ciId, type);
+		const [optionsResponse, rowsResponse] = await Promise.all([integrations.get(`${path}/source_options`), integrations.get(path)]);
+		if (sourceField !== null && rowsOf(rowsResponse, type).some((row) => row[sourceField] === "*")) return {
+			type,
+			status: "covered",
+			sourceField,
+			fallback: true
+		};
+		let unmapped = optionsOf(optionsResponse).filter((option) => option.mapped === false);
+		const build = AUTO_MAP[type];
+		if (autoMap && provider.targetOptions && build && unmapped.length > 0) {
+			const providerOptions = optionsOf(await integrations.get(`${path}/exigo_options`));
+			for (const { fluid, provider: match } of exactTitleMatches(unmapped, providerOptions)) {
+				const fields = build(fluid, match);
+				if (!fields) continue;
+				await createMapping(integrations, ciId, type, fields);
+				autoMapped.push(fields);
+				unmapped = unmapped.filter((option) => option !== fluid);
+			}
+		}
+		return {
+			type,
+			status: unmapped.length === 0 ? "covered" : "needs_mapping",
+			sourceField,
+			unmapped: unmapped.map((option) => ({
+				value: sourceValue(option, sourceField),
+				title: option.title ?? null,
+				...option.id !== void 0 && option.id !== null ? { id: option.id } : {}
+			})),
+			...autoMapped.length > 0 ? { autoMapped } : {}
+		};
+	} catch (error) {
+		return {
+			type,
+			status: "error",
+			sourceField,
+			error: errorText(error),
+			...autoMapped.length > 0 ? { autoMapped } : {}
+		};
+	}
+}
+//#endregion
+//#region src/walk.ts
+const PHASE_NAMES = {
+	credentials: "Credentials",
+	mappings: "Mappings",
+	settings: "Settings"
+};
+const DONE = { done: true };
+const FALLBACK = "*";
+/** The reason a request failed: the provider's, on a failed connection test. */
+function reasonOf(error) {
+	const body = error.body;
+	const detail = body?.["errors"] ?? body?.["error"] ?? body?.["error_message"];
+	if (typeof detail === "string") return detail;
+	if (Array.isArray(detail)) return detail.map(String).join("; ");
+	if (detail && typeof detail === "object") return Object.entries(detail).map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : String(value)}`).join("; ");
+	return error instanceof Error ? error.message : String(error);
+}
+const words = (type) => type.replace(/_/g, " ");
+function display(value) {
+	if (value === void 0 || value === null || value === "") return "(none)";
+	if (typeof value === "boolean") return value ? "Yes" : "No";
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+function setPath(target, key, value) {
+	const path = key.split(".");
+	let node = target;
+	for (const part of path.slice(0, -1)) {
+		if (typeof node[part] !== "object" || node[part] === null) node[part] = {};
+		node = node[part];
+	}
+	node[path[path.length - 1]] = value;
+}
+function rowIdOf(response, type) {
+	const record = response;
+	const row = record?.[`${type}_mapping`] ?? record;
+	return typeof row?.id === "number" ? row.id : void 0;
+}
+async function walkConnect(deps) {
+	const { integrations, provider, prompter } = deps;
+	const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const label = provider.label;
+	const result = {
+		provider: provider.id,
+		installed: false,
+		connected: false,
+		credentialsSaved: false,
+		autoMapped: 0,
+		rowsAdded: 0,
+		mappingsDone: null,
+		stillUnmapped: [],
+		settingsChanged: [],
+		settingsRestored: false,
+		skipped: [],
+		stopped: false
+	};
+	prompter.note(NAV_HELP);
+	let status = await providerStatus(integrations, provider);
+	if (!status.installed) {
+		if (await prompter.menu(`${label} isn't installed for this company. Installing it adds the ${label} droplet in Fluid, which creates the connection (changes live config).`, [{
+			title: `Install ${label}`,
+			value: "install"
+		}, {
+			title: "Stop",
+			value: "stop"
+		}]) !== "install") {
+			result.stopped = true;
+			return result;
+		}
+		await installProvider(deps.fluid, provider, status.dropletUuid);
+		prompter.note(`Installed ${label}. Waiting for the connection…`);
+		for (let attempt = 0; attempt < 10 && !status.installed; attempt += 1) {
+			await sleep(2e3);
+			status = await providerStatus(integrations, provider);
+		}
+		if (!status.installed) prompter.note(`The connection isn't there yet, so saving the credentials will create it.`);
+	}
+	result.installed = true;
+	result.connected = status.connected;
+	/** Null until the connection exists; saving credentials creates it. */
+	let ciId = status.companyIntegrationId;
+	let ci = ciId === null ? { id: 0 } : await getCompanyIntegration(integrations, ciId);
+	/** The connection, for the parts that need one (guarded at mappings-start). */
+	const connection = () => {
+		if (ciId === null) throw new ConnectError(`${label} has no connection yet. Save its credentials first.`);
+		return ciId;
+	};
+	const steps = [];
+	const history = [];
+	const skipped = /* @__PURE__ */ new Map();
+	const answers = /* @__PURE__ */ new Map();
+	let index = 0;
+	/** The step reached by back or the menu: asked even if answered. */
+	let targeted;
+	const indexOf = (id) => steps.findIndex((s) => s.id === id);
+	/** Put `fresh` in place of the group's steps, right after `afterId`. */
+	const replaceGroup = (group, afterId, fresh) => {
+		for (let i = steps.length - 1; i >= 0; i -= 1) if (steps[i].group === group) {
+			answers.delete(steps[i].id);
+			skipped.delete(steps[i].id);
+			steps.splice(i, 1);
+		}
+		steps.splice(indexOf(afterId) + 1, 0, ...fresh);
+	};
+	const ask = (question, canGoBack) => prompter.ask({
+		...question,
+		canGoBack
+	});
+	const draft = /* @__PURE__ */ new Map();
+	const credentialSteps = [];
+	const firstCredential = () => credentialSteps.find((s) => s.asks && s.id !== "credentials-keep").id;
+	if (status.connected) credentialSteps.push({
+		id: "credentials-keep",
+		phase: "credentials",
+		title: "Change the credentials?",
+		asks: true,
+		run: async (canGoBack) => {
+			const reply = await ask({
+				section: PHASE_NAMES.credentials,
+				message: `${label} is connected. Change its credentials?`,
+				kind: "select",
+				choices: [{
+					title: "Keep the saved credentials",
+					value: "keep"
+				}, {
+					title: "Change them",
+					value: "change"
+				}]
+			}, canGoBack);
+			if ("nav" in reply) return reply;
+			if (reply.value === "keep") {
+				answers.set("credentials-keep", "Keep");
+				history.push("credentials-keep");
+				return { goto: "mappings-start" };
+			}
+			return {
+				done: true,
+				answer: "Change"
+			};
+		}
+	});
+	const required = (field) => !field.optional && !result.connected;
+	const credentialStep = (field, when) => ({
+		id: `credential:${field.key}`,
+		phase: "credentials",
+		title: field.label,
+		asks: true,
+		...when ? { when } : {},
+		run: async (canGoBack) => {
+			const typed = draft.get(field.key);
+			const reply = await ask({
+				section: `${PHASE_NAMES.credentials} · ${field.key}`,
+				message: field.label,
+				kind: field.secret ? "secret" : "text",
+				...typed !== void 0 ? { current: field.secret ? "••••••" : typed } : {},
+				...result.connected ? { hint: "Enter keeps the saved value" } : field.optional ? { hint: "optional; Enter leaves it blank" } : {}
+			}, canGoBack);
+			if ("nav" in reply) return reply;
+			const value = reply.value.trim();
+			if (value === "") {
+				if (typed !== void 0 || !required(field)) return {
+					done: true,
+					answer: typed !== void 0 ? "(entered)" : "(unchanged)"
+				};
+				prompter.note(`${label} needs this. Type it, or > to skip.`);
+				return { retry: true };
+			}
+			draft.set(field.key, value);
+			return {
+				done: true,
+				answer: field.secret ? "(entered)" : value
+			};
+		}
+	});
+	if (provider.environments) {
+		credentialSteps.push({
+			id: "credential:environment",
+			phase: "credentials",
+			title: `${label} environment`,
+			asks: true,
+			run: async (canGoBack) => {
+				const reply = await ask({
+					section: `${PHASE_NAMES.credentials} · environment`,
+					message: `Which ${label} environment?`,
+					kind: "select",
+					choices: [{
+						title: "Production (your live Exigo)",
+						value: "production"
+					}, {
+						title: "Sandbox",
+						value: "sandbox"
+					}],
+					...draft.get("environment") ?? ci.environment ? { current: draft.get("environment") ?? ci.environment ?? void 0 } : {}
+				}, canGoBack);
+				if ("nav" in reply) return reply;
+				const environment = reply.value.trim() || draft.get("environment") || ci.environment;
+				if (!environment) {
+					prompter.note("Choose an environment, or > to skip.");
+					return { retry: true };
+				}
+				draft.set("environment", environment);
+				return {
+					done: true,
+					answer: environment
+				};
+			}
+		});
+		credentialSteps.push(credentialStep({
+			key: "sandbox_id",
+			label: "Exigo sandbox ID (the number in sandboxapi<ID>.exigo.com)"
+		}, () => (draft.get("environment") ?? ci.environment) !== "production"));
+	}
+	for (const field of provider.credentials) credentialSteps.push(credentialStep(field));
+	credentialSteps.push({
+		id: "credentials-save",
+		phase: "credentials",
+		title: "Save the credentials",
+		asks: false,
+		run: async () => {
+			if (draft.size === 0) return DONE;
+			const authSettings = {};
+			for (const [key, value] of draft) setPath(authSettings, key, value);
+			prompter.note(`Testing the connection to ${label}…`);
+			try {
+				ciId = (await saveCredentials(integrations, deps.fluid, provider, authSettings)).companyIntegrationId;
+			} catch (error) {
+				prompter.note(`${label} didn't accept the credentials, so nothing was saved: ${reasonOf(error)}`);
+				prompter.note("Check the values and answer again. Enter keeps what you typed.");
+				for (const step of credentialSteps) answers.delete(step.id);
+				return { goto: firstCredential() };
+			}
+			draft.clear();
+			result.credentialsSaved = true;
+			result.connected = true;
+			prompter.note("Connected. The credentials are saved.");
+			return DONE;
+		}
+	});
+	steps.push(...credentialSteps);
+	let autoMap = false;
+	const providerChoices = /* @__PURE__ */ new Map();
+	/** Types a `*` row now covers, so their other values aren't asked. */
+	const fallbackTypes = /* @__PURE__ */ new Set();
+	/** The row each mapping answer created, replaced when it's changed. */
+	const rowsByStep = /* @__PURE__ */ new Map();
+	steps.push({
+		id: "mappings-start",
+		phase: "mappings",
+		title: "Mappings",
+		asks: false,
+		run: async () => {
+			if (ciId !== null) return DONE;
+			prompter.note(`Mappings and settings need the connection, which saving ${label}'s credentials creates. Answer the credentials, or run \`fluid connect credentials ${provider.id}\`.`);
+			return { stop: true };
+		}
+	});
+	if (provider.targetOptions) steps.push({
+		id: "mappings-automap",
+		phase: "mappings",
+		title: "Map exact name matches",
+		asks: true,
+		run: async (canGoBack) => {
+			const reply = await ask({
+				section: PHASE_NAMES.mappings,
+				message: `Add a mapping wherever a Fluid value's name matches exactly one ${label} value? (changes live config)`,
+				kind: "select",
+				choices: [{
+					title: "Yes, map exact name matches first",
+					value: "yes"
+				}, {
+					title: "No, I'll map each one",
+					value: "no"
+				}],
+				...answers.has("mappings-automap") ? { current: autoMap ? "yes" : "no" } : {}
+			}, canGoBack);
+			if ("nav" in reply) return reply;
+			autoMap = reply.value === "yes";
+			return {
+				done: true,
+				answer: autoMap ? "Yes" : "No"
+			};
+		}
+	});
+	/** The provider's values for a type, as pick-list choices (Exigo). */
+	const choicesFor = async (type) => {
+		if (!provider.targetOptions) return [];
+		const cached = providerChoices.get(type);
+		if (cached) return cached;
+		let choices = [];
+		try {
+			const response = await integrations.get(`${mappingPath(connection(), type)}/exigo_options`);
+			const byTitle = (TARGET_FIELD[type] ?? "").endsWith("_title");
+			choices = (response?.options ?? []).filter((o) => o.id !== void 0 && o.id !== null).map((o) => ({
+				title: o.title ? `${o.title} (${String(o.id)})` : String(o.id),
+				value: byTitle && o.title ? o.title : String(o.id)
+			}));
+		} catch {
+			choices = [];
+		}
+		providerChoices.set(type, choices);
+		return choices;
+	};
+	/** Ask for the provider's value: a pick list for Exigo, typed otherwise. */
+	const askTarget = async (type, message, section, canGoBack, offerFallback, current) => {
+		const choices = await choicesFor(type);
+		const fallback = offerFallback ? [{
+			title: `* Use one ${label} value for every remaining ${words(type)}`,
+			value: FALLBACK
+		}] : [];
+		if (choices.length > 0) return ask({
+			section,
+			message,
+			kind: "search",
+			choices: [...choices, ...fallback],
+			hint: "type to filter",
+			...current ? { current } : {}
+		}, canGoBack);
+		const targetIsName = (TARGET_FIELD[type] ?? "").endsWith("_title");
+		return ask({
+			section,
+			message,
+			kind: "text",
+			hint: [`${label}'s ${words(type)} ${targetIsName ? "name" : "ID"}, from your ${label} back office`, offerFallback ? `or * to use one value for every remaining ${words(type)}` : ""].filter(Boolean).join("; "),
+			...current ? { current } : {}
+		}, canGoBack);
+	};
+	/** Save one row, replacing the row this step saved before. */
+	const saveRow = async (stepId, type, fields, fallback) => {
+		let response;
+		try {
+			response = await createMapping(integrations, connection(), type, fields);
+		} catch (error) {
+			prompter.note(`Not saved: ${reasonOf(error)}`);
+			return false;
+		}
+		const previous = rowsByStep.get(stepId);
+		if (previous) {
+			if (previous.fallback) fallbackTypes.delete(previous.type);
+			if (previous.id !== void 0) try {
+				await deleteMapping(integrations, connection(), previous.type, previous.id);
+			} catch (error) {
+				prompter.note(`The earlier row (${previous.id}) is still there: ${reasonOf(error)}. Remove it with \`fluid connect unmap ${provider.id} ${previous.type} ${previous.id} --yes\`.`);
+			}
+		} else result.rowsAdded += 1;
+		const id = rowIdOf(response, type);
+		rowsByStep.set(stepId, {
+			type,
+			...id !== void 0 ? { id } : {},
+			fallback
+		});
+		if (fallback) fallbackTypes.add(type);
+		return true;
+	};
+	const valueStep = (report, value, position) => {
+		const type = report.type;
+		const id = `map:${type}:${value.value}`;
+		const name = value.title && value.title !== value.value ? `"${value.title}" (${value.value})` : `"${value.value}"`;
+		const section = `${PHASE_NAMES.mappings} · ${words(type)} · ${position} of ${report.unmapped.length}`;
+		return {
+			id,
+			phase: "mappings",
+			group: "mapping-values",
+			title: `${words(type)}: ${value.title ?? value.value}`,
+			asks: true,
+			when: () => !fallbackTypes.has(type) || rowsByStep.get(id)?.fallback === true,
+			run: async (canGoBack) => {
+				const reply = await askTarget(type, `${label} ${words(type)} for Fluid's ${name}`, section, canGoBack, true, answers.get(id));
+				if ("nav" in reply) return reply;
+				let target = reply.value.trim();
+				if (target === "") {
+					if (answers.has(id)) return {
+						done: true,
+						answer: answers.get(id)
+					};
+					prompter.note("Choose a value, or > to skip.");
+					return { retry: true };
+				}
+				if (target === answers.get(id)) return {
+					done: true,
+					answer: target
+				};
+				const fallback = target === FALLBACK;
+				if (fallback) {
+					const second = await askTarget(type, `${label} ${words(type)} for every Fluid ${words(type)} without its own row`, section, canGoBack, false);
+					if ("nav" in second) return second.nav === "back" ? { retry: true } : second;
+					target = second.value.trim();
+					if (target === "") return { retry: true };
+				}
+				const fields = {
+					[SOURCE_FIELD[type]]: fallback ? FALLBACK : value.value,
+					[TARGET_FIELD[type]]: target
+				};
+				if (type === "warehouse" && !fallback && value.id !== void 0) {
+					fields["fluid_warehouse_id"] = value.id;
+					fields["source_warehouse_title"] = value.title ?? value.value;
+				}
+				if (!await saveRow(id, type, fields, fallback)) return { retry: true };
+				const answer = fallback ? `* → ${target}` : target;
+				prompter.note(fallback ? `Saved a * row: every other ${words(type)} maps to ${target}.` : `Saved: ${value.title ?? value.value} → ${target}.`);
+				return {
+					done: true,
+					answer
+				};
+			}
+		};
+	};
+	/** Ranks and ship methods: the API can't list Fluid's values. */
+	const byHandStep = (report) => {
+		const type = report.type;
+		const id = `by-hand:${type}`;
+		return {
+			id,
+			phase: "mappings",
+			group: "mapping-values",
+			title: `${words(type)} (by hand)`,
+			asks: true,
+			run: async (canGoBack) => {
+				const section = `${PHASE_NAMES.mappings} · ${words(type)}`;
+				const reply = await ask({
+					section,
+					message: `Fluid can't list its ${words(type)}s, so compare \`fluid connect mappings ${provider.id} ${type}\` with them yourself. Add a ${words(type)} row now?`,
+					kind: "select",
+					choices: [{
+						title: "Not now",
+						value: "no"
+					}, {
+						title: `Add a ${words(type)} row`,
+						value: "add"
+					}]
+				}, canGoBack);
+				if ("nav" in reply) return reply;
+				if (reply.value !== "add") return {
+					done: true,
+					answer: answers.get(id) ?? "Not now"
+				};
+				const sourceField = report.sourceField ?? SOURCE_FIELD[type];
+				const source = await ask({
+					section,
+					message: `Fluid ${words(type)} name (or * for every one without its own row)`,
+					kind: "text"
+				}, true);
+				if ("nav" in source) return source.nav === "back" ? { retry: true } : source;
+				if (source.value.trim() === "") return { retry: true };
+				const target = await askTarget(type, `${label} ${words(type)} for "${source.value.trim()}"`, section, true, false);
+				if ("nav" in target) return target.nav === "back" ? { retry: true } : target;
+				if (target.value.trim() === "") return { retry: true };
+				const fields = {
+					[sourceField]: source.value.trim(),
+					[TARGET_FIELD[type]]: target.value.trim()
+				};
+				if (type === "ship_method") {
+					const country = await ask({
+						section,
+						message: "Country code for this ship method (Enter for any country)",
+						kind: "text"
+					}, true);
+					if ("nav" in country) return country.nav === "back" ? { retry: true } : country;
+					if (country.value.trim() !== "") fields["country_code"] = country.value.trim().toUpperCase();
+				}
+				try {
+					await createMapping(integrations, connection(), type, fields);
+				} catch (error) {
+					prompter.note(`Not saved: ${reasonOf(error)}`);
+					return { retry: true };
+				}
+				result.rowsAdded += 1;
+				const added = Number(answers.get(`${id}#count`) ?? "0") + 1;
+				answers.set(`${id}#count`, String(added));
+				answers.set(id, `${added} row(s) added`);
+				prompter.note(`Saved: ${source.value.trim()} → ${target.value.trim()}.`);
+				return { retry: true };
+			}
+		};
+	};
+	steps.push({
+		id: "mappings-report",
+		phase: "mappings",
+		title: "Find what needs mapping",
+		asks: false,
+		run: async () => {
+			prompter.note(autoMap ? "Mapping exact name matches, then checking what's left…" : "Checking what needs mapping…");
+			const report = await unmappedReport(integrations, connection(), provider, autoMap);
+			const fresh = [];
+			let added = 0;
+			for (const entry of report) {
+				added += entry.autoMapped?.length ?? 0;
+				if (entry.status === "needs_mapping" && entry.sourceField && TARGET_FIELD[entry.type]) entry.unmapped.forEach((value, i) => fresh.push(valueStep(entry, value, i + 1)));
+				else if (entry.status === "needs_mapping") prompter.note(`${words(entry.type)}: ${entry.unmapped.length} value(s) to map. Add them with \`fluid connect map ${provider.id} ${entry.type} --set field=value --yes\`.`);
+				else if (entry.status === "check_by_hand" && TARGET_FIELD[entry.type]) fresh.push(byHandStep(entry));
+				else if (entry.status === "error") prompter.note(`${words(entry.type)}: couldn't read its values (${entry.error}). Check it later with \`fluid connect unmapped ${provider.id}\`.`);
+			}
+			if (added > 0) {
+				result.autoMapped += added;
+				prompter.note(`Added ${added} row(s) by matching names.`);
+			}
+			const toMap = fresh.filter((s) => s.id.startsWith("map:")).length;
+			prompter.note(toMap === 0 ? "Every value Fluid lists is mapped." : `${toMap} value(s) to map. Pick the ${label} value for each; * covers every remaining value of that type.`);
+			replaceGroup("mapping-values", "mappings-report", fresh);
+			return DONE;
+		}
+	});
+	const settingStep = (key, setting, position, total) => {
+		return {
+			id: `setting:${key}`,
+			phase: "settings",
+			group: "settings-values",
+			title: setting.label ?? key,
+			asks: true,
+			run: async (canGoBack) => {
+				const summary = summarizeSettings(ci).find((s) => s.key === key);
+				const current = summary ? summary.value : setting.value;
+				const fallbackLabel = (value) => setting.options?.find((o) => o.value === value)?.label ?? display(value);
+				const question = {
+					section: `${PHASE_NAMES.settings} · ${position} of ${total} · ${key}`,
+					message: `${setting.label ?? key} (default: ${fallbackLabel(setting.value)})`,
+					kind: "text",
+					...setting.description ? { hint: setting.description } : {}
+				};
+				let choices;
+				if (setting.options && setting.options.length > 0 && !setting.multiple) choices = setting.options.map((o, i) => ({
+					title: `${o.label ?? display(o.value)}${o.value === setting.value ? " (default)" : ""}`,
+					value: String(i),
+					raw: o.value
+				}));
+				else if (setting.type === "boolean") choices = [{
+					title: `Yes${setting.value === true ? " (default)" : ""}`,
+					value: "yes",
+					raw: true
+				}, {
+					title: `No${setting.value === false ? " (default)" : ""}`,
+					value: "no",
+					raw: false
+				}];
+				if (choices) {
+					question.kind = "select";
+					question.choices = choices.map(({ raw: _raw, ...c }) => c);
+					const now = choices.find((c) => c.raw === current);
+					if (now) question.current = now.title;
+				} else {
+					if (current !== null && current !== void 0 && current !== "") question.current = display(current);
+					question.hint = [setting.description, "JSON for lists and objects"].filter(Boolean).join(" · ");
+				}
+				const reply = await ask(question, canGoBack);
+				if ("nav" in reply) return reply;
+				let value;
+				if (choices) value = choices.find((c) => c.value === reply.value)?.raw;
+				else {
+					const raw = reply.value.trim();
+					if (raw === "") return {
+						done: true,
+						answer: display(current)
+					};
+					try {
+						value = /^(true|false|null|-?\d+(\.\d+)?)$|^[[{]/.test(raw) ? JSON.parse(raw) : raw;
+					} catch {
+						value = raw;
+					}
+				}
+				if (JSON.stringify(value) === JSON.stringify(current)) return {
+					done: true,
+					answer: fallbackLabel(value)
+				};
+				try {
+					ci = await updateSyncSettings(integrations, connection(), settingsPatch({ [key]: value }));
+				} catch (error) {
+					prompter.note(`Not saved: ${reasonOf(error)}`);
+					return { retry: true };
+				}
+				if (!result.settingsChanged.includes(key)) result.settingsChanged.push(key);
+				prompter.note(`Saved: ${setting.label ?? key} → ${fallbackLabel(value)}.`);
+				return {
+					done: true,
+					answer: fallbackLabel(value)
+				};
+			}
+		};
+	};
+	steps.push({
+		id: "settings-choice",
+		phase: "settings",
+		title: "Sync settings",
+		asks: true,
+		run: async (canGoBack) => {
+			ci = await getCompanyIntegration(integrations, connection());
+			const schema = ci.settings_schema ?? {};
+			const common = COMMON_SETTINGS.flatMap((key) => {
+				const [entity, name] = key.split(".");
+				const setting = schema[entity]?.[name];
+				return setting ? [{
+					key,
+					setting
+				}] : [];
+			});
+			const reply = await ask({
+				section: PHASE_NAMES.settings,
+				message: `Sync settings. A new connection starts on the defaults, and each default is safe.`,
+				kind: "select",
+				choices: [
+					{
+						title: "Keep every setting as it is",
+						value: "keep"
+					},
+					{
+						title: `Go through the ${common.length} common settings`,
+						value: "review"
+					},
+					{
+						title: "Put every setting back to its default",
+						value: "defaults"
+					}
+				]
+			}, canGoBack);
+			if ("nav" in reply) return reply;
+			if (reply.value === "review") {
+				replaceGroup("settings-values", "settings-choice", common.map(({ key, setting }, i) => settingStep(key, setting, i + 1, common.length)));
+				return {
+					done: true,
+					answer: "Go through the common settings"
+				};
+			}
+			replaceGroup("settings-values", "settings-choice", []);
+			if (reply.value === "defaults") {
+				try {
+					ci = await updateSyncSettings(integrations, connection(), defaultsPatch(schema));
+				} catch (error) {
+					prompter.note(`Not saved: ${reasonOf(error)}`);
+					return { retry: true };
+				}
+				result.settingsRestored = true;
+				prompter.note("Every setting is back on its default.");
+				return {
+					done: true,
+					answer: "Put back to defaults"
+				};
+			}
+			return {
+				done: true,
+				answer: "Keep as is"
+			};
+		}
+	});
+	const goBack = () => {
+		let previous = history.pop();
+		while (previous !== void 0 && indexOf(previous) < 0) previous = history.pop();
+		if (previous === void 0) {
+			prompter.note("This is the first question.");
+			return false;
+		}
+		skipped.delete(previous);
+		index = indexOf(previous);
+		targeted = previous;
+		return true;
+	};
+	/** True when the walk should stop. */
+	const openMenu = async () => {
+		const phases = Object.keys(PHASE_NAMES).filter((phase) => steps.some((s) => s.phase === phase));
+		const answered = steps.filter((s) => s.asks && answers.has(s.id));
+		const action = await prompter.menu("What next?", [
+			{
+				title: "Continue",
+				value: "continue"
+			},
+			{
+				title: "Back to the previous question",
+				value: "back",
+				disabled: history.length === 0
+			},
+			...phases.map((phase) => ({
+				title: `Go to ${PHASE_NAMES[phase]}`,
+				value: `phase:${phase}`
+			})),
+			{
+				title: "Change an answer",
+				value: "change",
+				disabled: answered.length === 0
+			},
+			{
+				title: "Finish: show the summary",
+				value: "finish"
+			},
+			{
+				title: "Stop for now (answers are saved)",
+				value: "quit"
+			}
+		]);
+		if (action === null || action === "quit") return true;
+		if (action === "back") goBack();
+		else if (action === "finish") index = steps.length;
+		else if (action.startsWith("phase:")) {
+			const phase = action.slice(6);
+			index = indexOf(phase === "mappings" ? "mappings-start" : steps.find((s) => s.phase === phase).id);
+			targeted = steps.find((s, i) => i >= index && s.asks)?.id;
+		} else if (action === "change") {
+			const id = await prompter.menu("Which answer?", answered.map((s) => ({
+				title: `${s.title} — ${answers.get(s.id)}`,
+				value: s.id
+			})));
+			if (id) {
+				index = indexOf(id);
+				targeted = id;
+			}
+		}
+		return false;
+	};
+	while (index < steps.length) {
+		const step = steps[index];
+		if (step.when && !step.when()) {
+			index += 1;
+			continue;
+		}
+		if (step.asks && answers.has(step.id) && targeted !== step.id) {
+			index += 1;
+			continue;
+		}
+		const outcome = await step.run(history.length > 0);
+		if ("stop" in outcome) {
+			result.stopped = true;
+			break;
+		}
+		if ("goto" in outcome) {
+			index = indexOf(outcome.goto);
+			targeted = steps[index]?.id;
+			continue;
+		}
+		if ("retry" in outcome) {
+			targeted = step.id;
+			continue;
+		}
+		if ("nav" in outcome) {
+			if (outcome.nav === "quit") {
+				result.stopped = true;
+				break;
+			}
+			if (outcome.nav === "back") {
+				if (!goBack()) targeted = step.id;
+				continue;
+			}
+			if (outcome.nav === "skip") {
+				skipped.set(step.id, step.title);
+				history.push(step.id);
+				index += 1;
+				continue;
+			}
+			targeted = step.id;
+			if (await openMenu()) {
+				result.stopped = true;
+				break;
+			}
+			continue;
+		}
+		if (step.asks) {
+			history.push(step.id);
+			skipped.delete(step.id);
+			answers.set(step.id, outcome.answer ?? "");
+		}
+		targeted = void 0;
+		index += 1;
+	}
+	status = await providerStatus(integrations, provider);
+	result.connected = status.connected;
+	result.skipped = [...skipped.values()];
+	try {
+		if (ciId === null) throw new ConnectError("there's no connection yet");
+		const report = await unmappedReport(integrations, ciId, provider, false);
+		result.mappingsDone = report.every((r) => r.status === "covered");
+		result.stillUnmapped = report.filter((r) => r.status !== "covered").map((r) => ({
+			type: r.type,
+			count: r.unmapped?.length ?? null,
+			status: r.status
+		}));
+	} catch (error) {
+		prompter.note(`Couldn't check the mappings: ${reasonOf(error)}`);
+	}
+	const lines = [
+		`${label}: ${result.connected ? "connected" : "not connected yet"}.`,
+		result.credentialsSaved ? "Credentials saved and tested." : "",
+		result.autoMapped + result.rowsAdded > 0 ? `Mapping rows added: ${result.rowsAdded}${result.autoMapped > 0 ? `, plus ${result.autoMapped} by name` : ""}.` : "",
+		result.mappingsDone ? "Every mapping type is covered." : result.stillUnmapped.length > 0 ? `Still to map or check: ${result.stillUnmapped.map((r) => `${words(r.type)}${r.count ? ` (${r.count})` : r.status === "check_by_hand" ? " (check by hand)" : ""}`).join(", ")}. See \`fluid connect unmapped ${provider.id}\`.` : "",
+		result.settingsRestored ? "Every sync setting is on its default." : "",
+		result.settingsChanged.length > 0 ? `Settings changed: ${result.settingsChanged.join(", ")}.` : "",
+		result.skipped.length > 0 ? `Skipped: ${result.skipped.join("; ")}.` : "",
+		`Run \`fluid connect walk ${provider.id}\` again to pick up where you left off.`
+	].filter(Boolean);
+	prompter.note(`\n${lines.join("\n")}`);
+	return result;
+}
+//#endregion
+//#region src/index.ts
+async function fluidClient(ctx) {
+	return await ctx.getClient();
+}
+async function integrationsClient(ctx) {
+	return await ctx.getClientFor(integrationsBase());
+}
+/**
+* Changes to a live connection 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 ConnectError(`${question} Pass --yes to confirm.`);
+	if (!(await prompts({
+		type: "confirm",
+		name: "ok",
+		message: question,
+		initial: false
+	})).ok) throw new ConnectError("Cancelled.");
+}
+/** Print a failure as JSON on stderr and exit non-zero. A failed connection
+*  test (422) carries the provider's reason in `errors`. */
+function fail(err) {
+	const status = typeof err.status === "number" ? err.status : void 0;
+	const body = err.body;
+	const detail = body && (body["errors"] ?? body["error"] ?? body["error_message"]);
+	const message = typeof detail === "string" ? detail : err instanceof Error ? err.message : String(err);
+	process.stderr.write(JSON.stringify({
+		error: message,
+		...status ? { status } : {},
+		...detail && typeof detail === "object" ? { details: detail } : {}
+	}) + "\n");
+	process.exitCode = 1;
+}
+function run(action) {
+	return action().catch(fail);
+}
+const collect = (value, previous = []) => [...previous, value];
+function registerConnectCommands(parent, ctx) {
+	parent.command("list").description(`Show ${PROVIDER_IDS.join(", ")} and whether each is installed`).action(() => run(async () => {
+		const integrations = await integrationsClient(ctx);
+		ctx.output(await Promise.all(PROVIDER_IDS.map((id) => providerStatus(integrations, providerOf(id)))));
+	}));
+	parent.command("install <provider>").description("Install the provider's droplet, which creates its connection (changes live config)").option("--yes", "Confirm without a prompt", false).action((providerId, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		const status = await providerStatus(await integrationsClient(ctx), provider);
+		if (status.installed) {
+			ctx.output({
+				...status,
+				alreadyInstalled: true
+			});
+			return;
+		}
+		await confirmChange(`Install ${provider.label} for this company?`, opts.yes);
+		ctx.output(await installProvider(await fluidClient(ctx), provider, status.dropletUuid));
+	}));
+	parent.command("show <provider>").description("Show the connection: state, supported mappings, and every sync setting with its current value").action((providerId) => run(async () => {
+		const provider = providerOf(providerId);
+		const integrations = await integrationsClient(ctx);
+		const ci = await getCompanyIntegration(integrations, await companyIntegrationId(integrations, provider));
+		ctx.output({
+			provider: provider.id,
+			companyIntegrationId: ci.id,
+			initialized: ci.initialized ?? null,
+			environment: ci.environment ?? null,
+			liveSyncState: ci.live_sync_state ?? null,
+			liveSyncDegradedReason: ci.live_sync_degraded_reason ?? null,
+			credentialGroups: provider.credentialGroups,
+			supportedMappings: ci.supported_mappings ?? [],
+			settings: summarizeSettings(ci)
+		});
+	}));
+	parent.command("credentials <provider>").description("Save credentials; the connection is tested before anything is saved, and created if the install has not yet (changes live config). Values here land in shell history; `fluid connect walk` asks for passwords hidden").option("--set <key=value>", "A credential, e.g. api.username=alice or mssql.dataserver=sql.example.com (repeatable)", collect, []).option("--yes", "Confirm without a prompt", false).action((providerId, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		if (opts.set.length === 0) throw new ConnectError(`Pass credentials with --set, e.g. --set api.username=alice. ${provider.label} uses: ${provider.credentialGroups.join(", ")}.`);
+		const authSettings = parseAssignments(opts.set, { strings: true });
+		const integrations = await integrationsClient(ctx);
+		await confirmChange(`Save new ${provider.label} credentials?`, opts.yes);
+		ctx.output(await saveCredentials(integrations, await fluidClient(ctx), provider, authSettings));
+	}));
+	parent.command("settings <provider>").description("List sync settings, change them with --set entity.key=value, or restore defaults with --defaults (changes live config)").option("--set <key=value>", "A setting from `fluid connect show`, e.g. order.refund_handling=hold (repeatable)", collect, []).option("--defaults", "Restore settings to their defaults: all of them, or only those named with --only", false).option("--only <key>", "With --defaults, restore just this setting, e.g. order.refund_handling (repeatable)", collect, []).option("--yes", "Confirm without a prompt", false).action((providerId, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		if (opts.defaults && opts.set.length > 0) throw new ConnectError("Use --set or --defaults, not both.");
+		if (opts.only.length > 0 && !opts.defaults) throw new ConnectError("--only goes with --defaults.");
+		const integrations = await integrationsClient(ctx);
+		const ciId = await companyIntegrationId(integrations, provider);
+		if (opts.defaults) {
+			const patch = defaultsPatch((await getCompanyIntegration(integrations, ciId)).settings_schema ?? {}, opts.only);
+			await confirmChange(`Restore ${opts.only.length > 0 ? `${opts.only.length} setting(s)` : "every sync setting"} to the default for ${provider.label}?`, opts.yes);
+			ctx.output(summarizeSettings(await updateSyncSettings(integrations, ciId, patch)));
+			return;
+		}
+		if (opts.set.length === 0) {
+			ctx.output(summarizeSettings(await getCompanyIntegration(integrations, ciId)));
+			return;
+		}
+		const patch = syncSettingsPatch(opts.set);
+		await confirmChange(`Change ${opts.set.length} ${provider.label} sync setting(s)?`, opts.yes);
+		ctx.output(summarizeSettings(await updateSyncSettings(integrations, ciId, patch)));
+	}));
+	parent.command("walk <provider>").description("Set up the connection question by question in the terminal: install, credentials, mappings, and settings. Go back with <, skip with >, open the menu with ?; each answer is saved as you go (changes live config)").action((providerId) => run(async () => {
+		assertInteractive("`install`, `credentials`, `unmapped`, `map`, and `settings` with --yes (see `fluid connect --help`)");
+		const provider = providerOf(providerId);
+		ctx.output(await walkConnect({
+			fluid: await fluidClient(ctx),
+			integrations: await integrationsClient(ctx),
+			provider,
+			prompter: terminalPrompter()
+		}));
+	}));
+	parent.command("unmapped <provider>").description("List only the data mappings a person still has to add; --auto-map first maps exact name matches (Exigo)").option("--auto-map", "Exigo: add rows where a Fluid value's name matches exactly one Exigo value (changes live config)", false).option("--yes", "Confirm --auto-map without a prompt", false).action((providerId, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		const integrations = await integrationsClient(ctx);
+		const ciId = await companyIntegrationId(integrations, provider);
+		if (opts.autoMap) {
+			if (!provider.targetOptions) throw new ConnectError(`--auto-map needs ${provider.label}'s own values, which only Exigo lists. Run without it to see what to map.`);
+			await confirmChange(`Add ${provider.label} mappings for exact name matches?`, opts.yes);
+		}
+		const report = await unmappedReport(integrations, ciId, provider, opts.autoMap);
+		ctx.output({
+			provider: provider.id,
+			done: report.every((r) => r.status === "covered"),
+			mappings: report
+		});
+		if (report.some((r) => r.status === "error")) process.exitCode = 1;
+	}));
+	parent.command("mappings <provider> <type>").description("List one mapping type's rows (e.g. customer_type, warehouse); --options lists the values to choose from").option("--options", "List the Fluid values, and for Exigo the Exigo values, instead of the saved rows", false).action((providerId, type, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		const integrations = await integrationsClient(ctx);
+		const ciId = await companyIntegrationId(integrations, provider);
+		ctx.output(opts.options ? await mappingOptions(integrations, ciId, type, provider) : await listMappings(integrations, ciId, type));
+	}));
+	parent.command("map <provider> <type>").description("Add a mapping row, e.g. --set source_type_slug=rep --set target_type_id=2 (changes live config)").option("--set <field=value>", "A field of the mapping row (repeatable)", collect, []).option("--yes", "Confirm without a prompt", false).action((providerId, type, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		if (opts.set.length === 0) throw new ConnectError("Pass the row's fields with --set field=value.");
+		const integrations = await integrationsClient(ctx);
+		const ciId = await companyIntegrationId(integrations, provider);
+		await confirmChange(`Add a ${type} mapping to ${provider.label}?`, opts.yes);
+		ctx.output(await createMapping(integrations, ciId, type, parseAssignments(opts.set)));
+	}));
+	parent.command("unmap <provider> <type> <id>").description("Remove one mapping row (changes live config)").option("--yes", "Confirm without a prompt", false).action((providerId, type, id, opts) => run(async () => {
+		const provider = providerOf(providerId);
+		const rowId = Number(id);
+		if (!Number.isInteger(rowId) || rowId <= 0) throw new ConnectError(`"${id}" isn't a mapping row id.`);
+		const integrations = await integrationsClient(ctx);
+		const ciId = await companyIntegrationId(integrations, provider);
+		await confirmChange(`Remove ${type} mapping ${rowId} from ${provider.label}?`, opts.yes);
+		ctx.output(await deleteMapping(integrations, ciId, type, rowId));
+	}));
+}
+const plugin = {
+	name: "@fluid-app/fluid-cli-connect",
+	version: "0.1.0",
+	register(ctx) {
+		ctx.program.addCommand(createDomainCommand("connect", "Connect Exigo, InfoTrax, ByDesign, or Pillars: credentials, data mappings, and sync settings", registerConnectCommands));
+	}
+};
+//#endregion
+export { confirmChange, plugin as default, registerConnectCommands };
+
+//# sourceMappingURL=index.mjs.map