atmn 1.1.25 → 2.0.0

package/src/actions/push.ts

@@ -0,0 +1,294 @@
+import { loadConfig } from "../config/loadConfig";
+import { loadEnvFiles } from "../env/loadEnv";
+import type { AutumnClient } from "../generated/client";
+import { splitWire } from "../generated/wire";
+import { resolveProject } from "../project/resolveProject";
+import {
+	type CatalogPreview,
+	previewIsEmpty,
+	renderMigrationLinks,
+	renderPreview,
+	type SettingsPreview,
+	settingsHaveWork,
+} from "../render/renderPreview";
+import {
+	backfillInternalIds,
+	identityRowsFromApplied,
+} from "./push/backfillInternalIds";
+import {
+	deprecatedUsesIn,
+	renderDeprecatedUses,
+} from "./push/deprecatedFields";
+import { withSettingsScopeHint } from "./sandbox/withSandboxScopeHint";
+
+export type PushResult = {
+	configPath: string;
+	preview: CatalogPreview;
+	/** Absent on a dry run, or when the preview showed nothing to do. */
+	applied?: unknown;
+	migrationIds: string[];
+};
+
+/** The settings lane of one push: absent when the config states no `settings`. */
+const previewSettings = async ({
+	client,
+	body,
+}: {
+	client: AutumnClient;
+	body: Record<string, unknown> | undefined;
+}): Promise<SettingsPreview | undefined> => {
+	if (body === undefined) return undefined;
+	try {
+		return (await client.previewUpdateOrganization(body)) as SettingsPreview;
+	} catch (error) {
+		throw withSettingsScopeHint({ error });
+	}
+};
+
+export type PushOptions = {
+	client: AutumnClient;
+	cwd?: string;
+	/** `-c`: the config file or its folder; found from cwd or the root marker otherwise. */
+	configPath?: string;
+	dryRun?: boolean;
+	/** Where to write progress. Injected so tests can capture it. */
+	write?: (text: string) => void;
+	migrationLinkBase?: string;
+};
+
+type RewardBody = { id?: string; internal_id?: string };
+
+type WireLike = {
+	features?: { feature_id?: string; internal_id?: string }[];
+	plans?: { plan_id?: string; internal_id?: string }[];
+	rewards?: { coupon?: RewardBody; feature_grant?: RewardBody }[];
+	referral_programs?: { id?: string; internal_id?: string }[];
+};
+
+const fixtureCount = (count: number): string =>
+	`${count} fixture${count === 1 ? "" : "s"}`;
+
+/** One count per field: the two sets overlap only sometimes, and a fixture
+ * that took just one of them must not read as having taken both. */
+export const backfillSummary = ({
+	backfilled,
+	slugged,
+}: {
+	backfilled: string[];
+	slugged: string[];
+}): string =>
+	`Wrote ${[
+		...(backfilled.length > 0
+			? [`internalId into ${fixtureCount(backfilled.length)}`]
+			: []),
+		...(slugged.length > 0
+			? [`versionSlug into ${fixtureCount(slugged.length)}`]
+			: []),
+	].join(" and ")}.\n`;
+
+/**
+ * A rename the config cannot express shows up as a delete beside a create
+ * with no internalId. The push may be right, so this is a note, not a refusal.
+ */
+export const possibleRenameHint = ({
+	preview,
+	wire,
+}: {
+	preview: CatalogPreview;
+	wire: WireLike;
+}): string | null => {
+	const lanes: {
+		rows: {
+			action?: string;
+			featureId?: string;
+			planId?: string;
+			id?: string;
+		}[];
+		idOf: (row: {
+			featureId?: string;
+			planId?: string;
+			id?: string;
+		}) => string | undefined;
+		stated: Set<string>;
+		noun: string;
+	}[] = [
+		{
+			rows: preview.features ?? [],
+			idOf: (row) => row.featureId,
+			stated: new Set(
+				(wire.features ?? [])
+					.filter((row) => row.internal_id === undefined)
+					.map((row) => row.feature_id ?? ""),
+			),
+			noun: "feature",
+		},
+		{
+			rows: preview.plans ?? [],
+			idOf: (row) => row.planId,
+			stated: new Set(
+				(wire.plans ?? [])
+					.filter((row) => row.internal_id === undefined)
+					.map((row) => row.plan_id ?? ""),
+			),
+			noun: "plan",
+		},
+		{
+			rows: preview.rewards ?? [],
+			idOf: (row) => row.id,
+			stated: new Set(
+				(wire.rewards ?? [])
+					.map((row) => row.coupon ?? row.feature_grant)
+					.filter(
+						(body) => body !== undefined && body.internal_id === undefined,
+					)
+					.map((body) => body?.id ?? ""),
+			),
+			noun: "reward",
+		},
+		{
+			rows: preview.referralPrograms ?? [],
+			idOf: (row) => row.id,
+			stated: new Set(
+				(wire.referral_programs ?? [])
+					.filter((row) => row.internal_id === undefined)
+					.map((row) => row.id ?? ""),
+			),
+			noun: "referral program",
+		},
+	];
+	const notes: string[] = [];
+	for (const lane of lanes) {
+		const deleted = lane.rows
+			.filter((row) => row.action === "delete")
+			.map((row) => lane.idOf(row) ?? "?");
+		const createdWithoutId = lane.rows
+			.filter((row) => row.action === "create")
+			.map((row) => lane.idOf(row) ?? "?")
+			.filter((id) => lane.stated.has(id));
+		if (deleted.length === 0 || createdWithoutId.length === 0) continue;
+		notes.push(
+			`Note: this push removes ${lane.noun} ${deleted.join(", ")} and creates ${createdWithoutId.join(", ")} without an internalId. If that is a rename, pull first so the fixture carries its id, or it will be treated as delete + create.`,
+		);
+	}
+	return notes.length > 0 ? notes.join("\n") : null;
+};
+
+/** The directories a config may live in, nearest first. */
+export const configSearchDirs = ({
+	cwd,
+	configPath,
+}: {
+	cwd: string;
+	configPath?: string;
+}): string[] => {
+	const project = resolveProject({ cwd, configFlag: configPath });
+	return [...new Set([project.configDir, cwd, ...project.envDirs])];
+};
+
+/**
+ * Preview, then apply. The CLI decides nothing here — it sends the same
+ * document twice and renders what comes back, which is why a clean preview is
+ * a real guarantee rather than a guess.
+ */
+export const runPush = async ({
+	client,
+	cwd = process.cwd(),
+	configPath: configFlag,
+	dryRun = false,
+	write = (text) => process.stdout.write(text),
+	migrationLinkBase,
+}: PushOptions): Promise<PushResult> => {
+	const project = resolveProject({ cwd, configFlag });
+	const dirs = configSearchDirs({ cwd, configPath: configFlag });
+	loadEnvFiles({ dirs: project.envDirs });
+
+	const { path: configPath, wire: document } = await loadConfig({
+		dirs,
+		...(project.configPath === null ? {} : { configPath: project.configPath }),
+	});
+	// One document, two operations: the catalog and each singleton go their own way.
+	const { catalog: wire, singletons } = splitWire(document);
+
+	const deprecated = deprecatedUsesIn({ wire });
+	if (deprecated.length > 0)
+		write(`${renderDeprecatedUses({ uses: deprecated })}\n\n`);
+
+	// Settings go first, on their own: a flag like multi_currency changes what
+	// the catalog accepts, so the catalog is previewed against the settings as
+	// they will be, and a settings write can never fail on the catalog's account.
+	const settingsBody = singletons.settings;
+	const settings = await previewSettings({ client, body: settingsBody });
+	const settingsWork =
+		settingsBody !== undefined && settingsHaveWork({ settings });
+	if (settingsWork) {
+		write(`${renderPreview({ preview: { settings } })}\n`);
+		if (!dryRun) {
+			try {
+				await client.updateOrganization(settingsBody);
+			} catch (error) {
+				throw withSettingsScopeHint({ error });
+			}
+			write("\nApplied settings.\n\n");
+		}
+	}
+
+	const catalogPreview = (await client.previewUpdate(wire)) as CatalogPreview;
+	// The settings lane is already printed when it applied; the unmanaged
+	// notes still belong beside the catalog's own rows.
+	const preview: CatalogPreview = {
+		...catalogPreview,
+		...(settingsWork ? {} : { settings }),
+	};
+
+	write(`${renderPreview({ preview, migrationLinkBase })}\n`);
+
+	const renameHint = possibleRenameHint({ preview, wire: wire as WireLike });
+	if (renameHint !== null) write(`${renameHint}\n\n`);
+
+	const fullPreview: CatalogPreview = { ...catalogPreview, settings };
+	if (previewIsEmpty({ preview: catalogPreview })) {
+		return { configPath, preview: fullPreview, migrationIds: [] };
+	}
+	if (dryRun) return { configPath, preview: fullPreview, migrationIds: [] };
+
+	const applied = (await client.update(wire)) as {
+		migrations?: { id?: string }[];
+		results?: Record<string, unknown>;
+	};
+
+	const migrationIds = (applied.migrations ?? [])
+		.map((migration) => migration.id)
+		.filter((id): id is string => typeof id === "string");
+
+	write("\nApplied.\n");
+	if (migrationIds.length > 0) {
+		write(
+			`${renderMigrationLinks({
+				migrations: migrationIds.map((id) => ({ id })),
+				migrationLinkBase,
+			})}\n\n`,
+		);
+	}
+
+	// The update response has no variant edges; when the config states any,
+	// the catalog's plan rows (with each variant's resolved plan) fill them in.
+	const statesVariants = (
+		(wire as { plans?: { variants?: unknown[] }[] }).plans ?? []
+	).some((row) => Array.isArray(row.variants) && row.variants.length > 0);
+	const rows = identityRowsFromApplied({ applied });
+	if (statesVariants) {
+		const catalog = (await client.get({
+			include_versions: true,
+		})) as unknown as {
+			plans?: unknown;
+		};
+		if (Array.isArray(catalog.plans))
+			rows.plans = catalog.plans as typeof rows.plans;
+	}
+	const { backfilled, slugged } = backfillInternalIds({ rows, configPath });
+	if (backfilled.length > 0 || slugged.length > 0) {
+		write(backfillSummary({ backfilled, slugged }));
+	}
+
+	return { configPath, preview: fullPreview, applied, migrationIds };
+};

package/src/actions/reset/runReset.ts

@@ -0,0 +1,58 @@
+import { assertSandboxTarget } from "../../env/assertSandboxTarget";
+import type { Target } from "../../env/resolveTarget";
+import type { AutumnClient } from "../../generated/client";
+import type { WriteLine } from "../sandbox/types/sandboxClient";
+
+/** The one operation `atmn reset` needs, so a test can hand over a fake. */
+export type ResetClient = Pick<AutumnClient, "resetSandbox">;
+
+export type ResetOptions = {
+	client: ResetClient;
+	/** Which sandbox is wiped: reset acts on whatever the key belongs to. */
+	target: Target;
+	/** The pinned sandbox's name, when the CLI could look it up; the id is the fallback. */
+	sandboxName?: string;
+	/** Nothing is sent without this: the whole catalog goes. */
+	yes?: boolean;
+	write?: WriteLine;
+};
+
+export type ResetResult = { wiped: boolean };
+
+/** What the copy calls the sandbox: the pinned one by name, or the main one. */
+const targetName = ({
+	target,
+	sandboxName,
+}: {
+	target: Target;
+	sandboxName: string | undefined;
+}): string =>
+	target.sandboxId === undefined
+		? "your main sandbox"
+		: sandboxName === undefined
+			? `sandbox ${target.sandboxId}`
+			: `sandbox ${sandboxName} (${target.sandboxId})`;
+
+export const runReset = async ({
+	client,
+	target,
+	sandboxName,
+	yes = false,
+	write = (text) => process.stdout.write(text),
+}: ResetOptions): Promise<ResetResult> => {
+	assertSandboxTarget({ target });
+
+	const name = targetName({ target, sandboxName });
+
+	if (!yes) {
+		write(
+			`This wipes ${name}: every customer, plan, feature and migration draft. Keys and settings stay. Re-run with --yes to wipe.\n`,
+		);
+		return { wiped: false };
+	}
+
+	await client.resetSandbox({});
+
+	write(`Wiped ${name}. Run atmn push to rebuild it from your config.\n`);
+	return { wiped: true };
+};

package/src/actions/sandbox/createSandbox.ts

@@ -0,0 +1,83 @@
+import { writeEnvValues } from "../../env/loadEnv";
+import { SANDBOX_PIN_NAME, sandboxKeyName } from "../../env/sandboxKeyName";
+import type {
+	CreateSandboxParams,
+	CreateSandboxResponse,
+} from "../../generated/client";
+import { stripTerminalControls } from "../../render/stripTerminalControls";
+import type { SandboxClient, WriteLine } from "./types/sandboxClient";
+
+export type SandboxCreateOptions = {
+	client: SandboxClient;
+	name: string;
+	color?: CreateSandboxParams["color"];
+	icon?: string;
+	/** Also pin AUTUMN_SANDBOX_ID, so later commands target the new sandbox. */
+	use?: boolean;
+	json?: boolean;
+	/** Where to look for the .env the key is written to. */
+	envDirs: string[];
+	write?: WriteLine;
+	writeError?: WriteLine;
+};
+
+export type SandboxCreateResult = {
+	sandbox: CreateSandboxResponse;
+	envPath: string;
+	keyName: string;
+};
+
+export const runSandboxCreate = async ({
+	client,
+	name,
+	color,
+	icon,
+	use = false,
+	json = false,
+	envDirs,
+	write = (text) => process.stdout.write(text),
+	writeError = (text) => process.stderr.write(text),
+}: SandboxCreateOptions): Promise<SandboxCreateResult> => {
+	const sandbox = await client.createSandbox({
+		name,
+		...(color === undefined ? {} : { color }),
+		...(icon === undefined ? {} : { icon }),
+	});
+
+	// The key is readable exactly once, in this response: it reaches disk
+	// before anything else can fail.
+	const keyName = sandboxKeyName({ sandboxId: sandbox.id });
+	let envPath: string;
+	try {
+		envPath = writeEnvValues({
+			dirs: envDirs,
+			values: {
+				[keyName]: sandbox.secretKey,
+				...(use ? { [SANDBOX_PIN_NAME]: sandbox.id } : {}),
+			},
+		});
+	} catch (error) {
+		// The key exists nowhere else: show it before the failure takes it, on
+		// stderr under --json so stdout stays parseable.
+		(json ? writeError : write)(
+			`Could not write your .env. Save this key yourself:\n${keyName}=${sandbox.secretKey}\n`,
+		);
+		throw error;
+	}
+
+	if (json) {
+		write(`${JSON.stringify(sandbox, null, 2)}\n`);
+		return { sandbox, envPath, keyName };
+	}
+
+	write(
+		`Created sandbox ${stripTerminalControls(sandbox.name)} (${sandbox.id}).\nSaved its key to ${envPath} as ${keyName}.\n`,
+	);
+	if (use) {
+		write(
+			`Pinned ${SANDBOX_PIN_NAME}=${sandbox.id}; every command targets it until you change it.\n`,
+		);
+	}
+
+	return { sandbox, envPath, keyName };
+};

package/src/actions/sandbox/deleteSandbox.ts

@@ -0,0 +1,91 @@
+import { removeEnvValues, removeEnvValueWhen } from "../../env/loadEnv";
+import { SANDBOX_PIN_NAME, sandboxKeyName } from "../../env/sandboxKeyName";
+import type { SandboxRow } from "../../render/renderSandboxes";
+import { stripTerminalControls } from "../../render/stripTerminalControls";
+import type { SandboxClient, WriteLine } from "./types/sandboxClient";
+
+export type SandboxDeleteOptions = {
+	client: SandboxClient;
+	id: string;
+	/** Nothing is sent without this: delete takes the catalog and the customers too. */
+	yes?: boolean;
+	/** Where to look for the .env the sandbox's key is scrubbed from. */
+	envDirs: string[];
+	write?: WriteLine;
+	writeError?: WriteLine;
+};
+
+export type SandboxDeleteResult = {
+	deleted: boolean;
+	sandbox: SandboxRow;
+	/** Every .env that changed; empty when the sandbox had no key or pin on disk. */
+	envPaths: string[];
+};
+
+/** The key goes from every file holding it; the pin only where it pointed
+ * here, since another sandbox may own it in another file. */
+const scrubSandboxFromEnv = ({
+	sandboxId,
+	envDirs,
+}: {
+	sandboxId: string;
+	envDirs: string[];
+}): string[] => {
+	const scrubbed = [
+		...removeEnvValues({
+			dirs: envDirs,
+			keys: [sandboxKeyName({ sandboxId })],
+		}),
+		...removeEnvValueWhen({
+			dirs: envDirs,
+			key: SANDBOX_PIN_NAME,
+			equals: sandboxId,
+		}),
+	];
+	return [...new Set(scrubbed)];
+};
+
+export const runSandboxDelete = async ({
+	client,
+	id,
+	yes = false,
+	envDirs,
+	write = (text) => process.stdout.write(text),
+	writeError = (text) => process.stderr.write(text),
+}: SandboxDeleteOptions): Promise<SandboxDeleteResult> => {
+	// Listing first names the sandbox in the copy, and turns a typo into an
+	// error instead of a request the server has to refuse.
+	const { list } = await client.listSandboxes({});
+	const sandbox = list.find((entry) => entry.id === id);
+	if (sandbox === undefined) {
+		throw new Error(`No sandbox with id ${id}. Run atmn sandbox list.`);
+	}
+
+	if (!yes) {
+		write(
+			`This deletes sandbox ${stripTerminalControls(sandbox.name)} (${sandbox.id}) and everything in it. Re-run with --yes to delete.\n`,
+		);
+		return { deleted: false, sandbox, envPaths: [] };
+	}
+
+	await client.deleteSandbox({ id: sandbox.id });
+	// The remote delete is done and cannot be undone: say so before anything
+	// local can fail, so a .env error never reads as a failed deletion.
+	write(
+		`Deleted sandbox ${stripTerminalControls(sandbox.name)} (${sandbox.id}).\n`,
+	);
+
+	let envPaths: string[];
+	try {
+		envPaths = scrubSandboxFromEnv({ sandboxId: sandbox.id, envDirs });
+	} catch (error) {
+		writeError(
+			`Sandbox ${sandbox.id} is gone, but its .env could not be rewritten. Remove the line ${sandboxKeyName({ sandboxId: sandbox.id })}=... by hand, and ${SANDBOX_PIN_NAME}=${sandbox.id} if it is there.\n`,
+		);
+		throw error;
+	}
+
+	if (envPaths.length > 0)
+		write(`Dropped its key from ${envPaths.join(", ")}.\n`);
+	return { deleted: true, sandbox, envPaths };
+};

package/src/actions/sandbox/listSandboxes.ts

@@ -0,0 +1,28 @@
+import type { ListSandboxesResponse } from "../../generated/client";
+import { renderSandboxes } from "../../render/renderSandboxes";
+import type { SandboxClient, WriteLine } from "./types/sandboxClient";
+
+export type SandboxListOptions = {
+	client: SandboxClient;
+	/** The sandbox `--sandbox` or AUTUMN_SANDBOX_ID points at; marked in the table. */
+	currentSandboxId?: string;
+	json?: boolean;
+	write?: WriteLine;
+};
+
+export const runSandboxList = async ({
+	client,
+	currentSandboxId,
+	json = false,
+	write = (text) => process.stdout.write(text),
+}: SandboxListOptions): Promise<ListSandboxesResponse> => {
+	const response = await client.listSandboxes({});
+
+	if (json) {
+		write(`${JSON.stringify(response, null, 2)}\n`);
+		return response;
+	}
+
+	write(`${renderSandboxes({ sandboxes: response.list, currentSandboxId })}\n`);
+	return response;
+};

package/src/actions/sandbox/types/sandboxClient.ts

@@ -0,0 +1,16 @@
+import type { AutumnClient } from "../../../generated/client";
+
+/** The three operations `atmn sandbox` needs, so a test can hand over a fake. */
+export type SandboxClient = Pick<
+	AutumnClient,
+	"createSandbox" | "listSandboxes" | "deleteSandbox"
+>;
+
+/** What `atmn sandbox use` needs: the list to pick from, and a key when none is on disk. */
+export type UseSandboxClient = Pick<
+	AutumnClient,
+	"listSandboxes" | "createSandboxKey"
+>;
+
+/** Where a command writes its progress. Injected so tests can capture it. */
+export type WriteLine = (text: string) => void;