atmn 1.1.24 → 2.0.0

package/src/config/loadConfig.ts

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { COLLECTIONS } from "../generated/emit";
+import { ConfigError, type LintIssue } from "../generated/lintRuntime";
+import { fixtureLocation } from "../surgery/fixtureLocation";
+import { configPackageName } from "./configPackageName";
+import { isLegacyConfigText, LegacyConfigError } from "./legacyConfig";
+
+const CONFIG_FILENAMES = ["autumn.config.ts", "autumn.config.js"] as const;
+
+/** Opaque until the generator emits the real type — the wire document. */
+export type WireDocument = Record<string, unknown>;
+
+export class ConfigNotFoundError extends Error {
+	constructor(searched: string[]) {
+		super(
+			`No autumn.config.ts found. Looked in:\n${searched
+				.map((path) => `  ${path}`)
+				.join(
+					"\n",
+				)}\n\nRun \`${configPackageName()} init\` to create one, or pass -c <dir>.`,
+		);
+		this.name = "ConfigNotFoundError";
+	}
+}
+
+export const findConfigPath = ({ dirs }: { dirs: string[] }): string | null => {
+	for (const dir of dirs) {
+		for (const filename of CONFIG_FILENAMES) {
+			const path = join(dir, filename);
+			if (existsSync(path)) return path;
+		}
+	}
+	return null;
+};
+
+/** A finding's breadcrumb starts with its top-level fixture, e.g. `feature "x"`. */
+const TOP_LEVEL_FIXTURE = /^(\w+) "([^"]*)"/;
+
+/** Where a finding's fixture lives, `undefined` when its breadcrumb names none
+ * (a document-level error) or the fixture text can't be found. */
+const locationOf = ({
+	issue,
+	configPath,
+}: {
+	issue: LintIssue;
+	configPath: string;
+}): string | undefined => {
+	const match = TOP_LEVEL_FIXTURE.exec(issue.path.split(" › ")[0] ?? "");
+	if (!match) return undefined;
+	const [, builder, id] = match;
+	const collection = Object.values(COLLECTIONS).find(
+		(spec) => spec.builder === builder,
+	);
+	if (!collection || id === undefined) return undefined;
+
+	const found = fixtureLocation({
+		configPath,
+		builder: collection.builder,
+		idField: collection.idField,
+		id,
+	});
+	return found ? `${found.file}:${found.line}` : undefined;
+};
+
+/** Every locatable finding gets its source appended, so a config error points
+ * back at the file the user actually needs to open. */
+const withFixtureLocations = ({
+	error,
+	configPath,
+}: {
+	error: ConfigError;
+	configPath: string;
+}): ConfigError =>
+	new ConfigError(
+		error.issues.map((issue) => {
+			const location = locationOf({ issue, configPath });
+			return location
+				? { ...issue, message: `${issue.message} (${location})` }
+				: issue;
+		}),
+	);
+
+/**
+ * Imports the config in-process — it is the user's own code on their own
+ * machine, npm-script trust level. The subprocess + stdout contract that
+ * existed for non-TS producers is gone; this function is the seam a future
+ * `--config-json` would slot into.
+ */
+/**
+ * A fresh process per load: the root imports its collection files, and no
+ * in-process import — Bun's `?v=` bust, jiti's `moduleCache: false` — re-reads
+ * a dependency after the first load. A single push never notices; pull edits
+ * the collection files and then re-evaluates the config, so it must.
+ */
+/**
+ * Bun imports a .ts config natively. Node goes through jiti's own import,
+ * which transpiles and handles CJS/ESM interop itself; the package is resolved
+ * from this CLI's install, never from the config's folder.
+ */
+export const importConfigArgs = ({
+	path,
+	onBun = typeof Bun !== "undefined",
+}: {
+	path: string;
+	onBun?: boolean;
+}): string[] => {
+	const target = JSON.stringify(path);
+	const load = onBun
+		? `import(${target})`
+		: `import(${JSON.stringify(import.meta.resolve("jiti"))}).then(({ createJiti }) => createJiti(${target}).import(${target}))`;
+	const report = `(m) => process.stdout.write(JSON.stringify({ ok: true, module: { ...m, default: m.default } })), (e) => process.stdout.write(JSON.stringify({ ok: false, name: e?.name, message: e?.message, issues: e?.issues }))`;
+	return ["-e", `${load}.then(${report})`];
+};
+
+const importConfigModule = async ({
+	path,
+}: {
+	path: string;
+}): Promise<Record<string, unknown> & { default?: WireDocument }> => {
+	const result = spawnSync(process.execPath, importConfigArgs({ path }), {
+		cwd: dirname(path),
+		encoding: "utf8",
+	});
+	if (result.status !== 0 || result.stdout.length === 0) {
+		throw new Error(result.stderr.trim() || `Failed to load ${path}`);
+	}
+	const parsed = JSON.parse(result.stdout) as
+		| { ok: true; module: Record<string, unknown> & { default?: WireDocument } }
+		| { ok: false; name?: string; message?: string; issues?: LintIssue[] };
+	if (parsed.ok) return parsed.module;
+	if (parsed.name === "ConfigError" && parsed.issues)
+		throw new ConfigError(parsed.issues);
+	throw new Error(parsed.message ?? `Failed to load ${path}`);
+};
+
+export const loadConfig = async ({
+	dirs,
+	configPath,
+}: {
+	dirs: string[];
+	/** `-c`: an exact file, which may be named anything. */
+	configPath?: string;
+}): Promise<{ path: string; wire: WireDocument }> => {
+	// An explicit path is the whole answer: a typo must not quietly load
+	// whichever config the search would have found instead.
+	const path =
+		configPath !== undefined
+			? existsSync(configPath)
+				? configPath
+				: null
+			: findConfigPath({ dirs });
+	if (!path) throw new ConfigNotFoundError(configPath ? [configPath] : dirs);
+	// A 1.x config would die inside the import with "item is not exported";
+	// say what happened and how to move instead.
+	if (isLegacyConfigText({ text: readFileSync(path, "utf8") })) {
+		throw new LegacyConfigError({ path });
+	}
+
+	// Cache-busted because the module cache would otherwise pin the first read
+	// for the life of the process — irrelevant for a single `atmn push`, wrong
+	// for anything that pushes twice (tests today, a watch mode later).
+	// The query goes on the plain path: appended to a file:// href Bun
+	// normalises it away and serves the cached module.
+	let module: Record<string, unknown> & { default?: WireDocument };
+	try {
+		module = await importConfigModule({ path });
+	} catch (error) {
+		if (error instanceof ConfigError) {
+			throw withFixtureLocations({ error, configPath: path });
+		}
+		throw error;
+	}
+	const wire = module.default;
+
+	if (looksLikeV2Config({ module })) throw new LegacyConfigError({ path });
+	if (wire === undefined) {
+		throw new Error(
+			`${path} has no default export. It should end with \`export default atmn({ ... })\`.`,
+		);
+	}
+
+	return { path, wire };
+};
+
+/**
+ * v2 exported plain fixtures — a default object with `products`/`features`
+ * arrays, or named `feature()`/`product()` results — never a wire document,
+ * which always carries `skip_deletions`.
+ */
+/** Fields only a v2 product carries. `items` is optional — an empty plan
+ * states none — so the settings have to name the row on their own. */
+const V2_PRODUCT_FIELDS = [
+	"items",
+	"is_add_on",
+	"is_default",
+	"free_trial",
+	"group",
+] as const;
+
+/** A v2 fixture: a public `id` beside a feature's `type` or a product's own settings. */
+const isV2Row = (value: unknown): boolean => {
+	if (typeof value !== "object" || value === null) return false;
+	const row = value as Record<string, unknown>;
+	if (!("id" in row)) return false;
+	return "type" in row || V2_PRODUCT_FIELDS.some((field) => field in row);
+};
+
+export const looksLikeV2Config = ({
+	module,
+}: {
+	module: Record<string, unknown>;
+}): boolean => {
+	const defaults = module.default;
+	if (typeof defaults === "object" && defaults !== null) {
+		const bag = defaults as Record<string, unknown>;
+		if ("skip_deletions" in bag) return false;
+		if (
+			["products", "features", "plans", "rewards"].some((key) =>
+				Array.isArray(bag[key]),
+			)
+		)
+			return true;
+	}
+	// A v2 default object proves nothing on its own: the named fixtures beside
+	// it still do, so the check runs whatever the default export holds.
+	return Object.entries(module).some(
+		([name, value]) => name !== "default" && isV2Row(value),
+	);
+};

package/src/env/assertSandboxTarget.ts

@@ -0,0 +1,20 @@
+import type { Target } from "./resolveTarget";
+
+const TEST_KEY_PREFIX = "am_sk_test";
+
+export const SANDBOX_ONLY_REFUSAL =
+	"Reset only wipes sandboxes; the key for this target is a live key.";
+
+/**
+ * A live key never even reaches the server: the wipe is irreversible, so it is
+ * refused here rather than left to the server's 400.
+ */
+export const assertSandboxTarget = ({ target }: { target: Target }): void => {
+	if (target.secretKeyName === "AUTUMN_PROD_SECRET_KEY")
+		throw new Error(SANDBOX_ONLY_REFUSAL);
+
+	const key = process.env[target.secretKeyName];
+	// A key that is not set at all is requireSecretKey's error to give.
+	if (key !== undefined && !key.startsWith(TEST_KEY_PREFIX))
+		throw new Error(SANDBOX_ONLY_REFUSAL);
+};

package/src/env/loadEnv.ts

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "dotenv";
+
+/** Later files never override earlier ones; process.env always wins. */
+const FILES_IN_PRECEDENCE_ORDER = [".env.local", ".env"] as const;
+
+export type AutumnKeys = {
+	sandboxKey?: string;
+	prodKey?: string;
+};
+
+/**
+ * Reads `.env.local` then `.env` into process.env without clobbering anything
+ * already set, so injected secrets (Doppler, Infisical, CI) keep priority.
+ * Mirrors v2's precedence: process.env → .env.local → .env.
+ */
+export const loadEnvFiles = ({ dirs }: { dirs: string[] }): string[] => {
+	const loaded: string[] = [];
+
+	for (const dir of dirs) {
+		for (const file of FILES_IN_PRECEDENCE_ORDER) {
+			const path = join(dir, file);
+			if (!existsSync(path)) continue;
+
+			try {
+				for (const [key, value] of Object.entries(
+					parse(readFileSync(path, "utf8")),
+				)) {
+					if (process.env[key] === undefined) process.env[key] = value;
+				}
+				loaded.push(path);
+			} catch {
+				// An unreadable or malformed .env is not fatal — the key may well
+				// be in the real environment already.
+			}
+		}
+	}
+
+	return loaded;
+};
+
+export const readAutumnKeys = (): AutumnKeys => ({
+	sandboxKey: process.env.AUTUMN_SECRET_KEY,
+	prodKey: process.env.AUTUMN_PROD_SECRET_KEY,
+});
+
+/** Every env file the search set holds, in the order `loadEnvFiles` reads them. */
+export const findEnvFiles = ({ dirs }: { dirs: string[] }): string[] => {
+	const paths: string[] = [];
+	for (const dir of dirs) {
+		for (const file of FILES_IN_PRECEDENCE_ORDER) {
+			const path = join(dir, file);
+			if (existsSync(path)) paths.push(path);
+		}
+	}
+	return paths;
+};
+
+/** The file `loadEnvFiles` reads first, so writes land where reads look. */
+export const findEnvFile = ({ dirs }: { dirs: string[] }): string | undefined =>
+	findEnvFiles({ dirs })[0];
+
+const isAssignmentFor = ({
+	line,
+	key,
+}: {
+	line: string;
+	key: string;
+}): boolean => line.trimStart().startsWith(`${key}=`);
+
+/** Rewrites keys in place and appends the rest; every other line survives. */
+export const upsertEnvContent = ({
+	content,
+	values,
+}: {
+	content: string;
+	values: Record<string, string>;
+}): string => {
+	const trimmed = content.endsWith("\n") ? content.slice(0, -1) : content;
+	const lines = trimmed === "" ? [] : trimmed.split("\n");
+
+	for (const [key, value] of Object.entries(values)) {
+		const index = lines.findIndex((line) => isAssignmentFor({ line, key }));
+		if (index === -1) lines.push(`${key}=${value}`);
+		else lines[index] = `${key}=${value}`;
+	}
+
+	return `${lines.join("\n")}\n`;
+};
+
+/** Drops the assignments for these keys; every other line survives. */
+export const removeEnvContent = ({
+	content,
+	keys,
+}: {
+	content: string;
+	keys: string[];
+}): string => {
+	const kept = content
+		.split("\n")
+		.filter((line) => !keys.some((key) => isAssignmentFor({ line, key })));
+	// The split leaves a trailing empty segment for the final newline; rejoining
+	// without dropping it would grow a blank line on every removal.
+	const trimmed = kept[kept.length - 1] === "" ? kept.slice(0, -1) : kept;
+	return trimmed.length === 0 ? "" : `${trimmed.join("\n")}\n`;
+};
+
+/** What the env file on disk assigns — not what the process happens to carry. */
+export const readEnvFileValue = ({
+	dirs,
+	key,
+}: {
+	dirs: string[];
+	key: string;
+}): string | undefined => {
+	const path = findEnvFile({ dirs });
+	if (path === undefined) return undefined;
+	return parse(readFileSync(path, "utf8"))[key];
+};
+
+/**
+ * Removes keys from every env file that assigns one — a key left in a
+ * lower-precedence file would come back the moment the higher one loses it.
+ * The paths that changed.
+ */
+export const removeEnvValues = ({
+	dirs,
+	keys,
+}: {
+	dirs: string[];
+	keys: string[];
+}): string[] => removeWhere({ dirs, keys, keep: () => false });
+
+/** Removes a key only from the files assigning it this exact value. */
+export const removeEnvValueWhen = ({
+	dirs,
+	key,
+	equals,
+}: {
+	dirs: string[];
+	key: string;
+	equals: string;
+}): string[] =>
+	removeWhere({
+		dirs,
+		keys: [key],
+		keep: ({ content }) => parse(content)[key] !== equals,
+	});
+
+const removeWhere = ({
+	dirs,
+	keys,
+	keep,
+}: {
+	dirs: string[];
+	keys: string[];
+	keep: (params: { content: string }) => boolean;
+}): string[] => {
+	const changed: string[] = [];
+	for (const path of findEnvFiles({ dirs })) {
+		const content = readFileSync(path, "utf8");
+		if (keep({ content })) continue;
+		const next = removeEnvContent({ content, keys });
+		if (next === content) continue;
+		writeFileSync(path, next);
+		changed.push(path);
+	}
+	return changed;
+};
+
+export const writeEnvValues = ({
+	dirs,
+	values,
+}: {
+	dirs: string[];
+	values: Record<string, string>;
+}): string => {
+	const path = findEnvFile({ dirs }) ?? join(dirs[0] ?? process.cwd(), ".env");
+	const content = existsSync(path) ? readFileSync(path, "utf8") : "";
+
+	writeFileSync(path, upsertEnvContent({ content, values }));
+	return path;
+};

package/src/env/resolveTarget.ts

@@ -0,0 +1,134 @@
+import { CLI_CLIENT_ID } from "../auth/oauthConfig";
+import {
+	SANDBOX_PIN_NAME,
+	type SandboxSecretKeyName,
+	sandboxKeyName,
+} from "./sandboxKeyName";
+
+const LOCAL_HOST = "http://localhost";
+const DEFAULT_LOCAL_PORT = 8080;
+
+/** The spec's server: what every command talks to unless told otherwise. */
+export const DEFAULT_BASE_URL = "https://api.useautumn.com";
+
+/** The global flags every command shares; parsed once by the program. */
+export type TargetFlags = {
+	prod?: boolean;
+	sandbox?: string;
+	local?: boolean;
+	port?: string;
+	baseUrl?: string;
+	clientId?: string;
+};
+
+/** Every env var a command may authenticate with: the org's two, or a sandbox's own. */
+export type SecretKeyName =
+	| "AUTUMN_SECRET_KEY"
+	| "AUTUMN_PROD_SECRET_KEY"
+	| SandboxSecretKeyName;
+
+export type Target = {
+	/** Undefined means the generated client's default (the spec's server). */
+	baseUrl?: string;
+	secretKeyName: SecretKeyName;
+	/** The OAuth client the CLI identifies as; flag, then env, then the registered default. */
+	clientId: string;
+	/** A named sandbox to address instead of the org's default one. */
+	sandboxId?: string;
+};
+
+/** A sandbox's own key when one is pinned, else the org key `--prod` selects. */
+const secretKeyNameFor = ({
+	prod,
+	sandboxId,
+}: {
+	prod: boolean;
+	sandboxId: string | undefined;
+}): SecretKeyName => {
+	if (sandboxId !== undefined) return sandboxKeyName({ sandboxId });
+	return prod ? "AUTUMN_PROD_SECRET_KEY" : "AUTUMN_SECRET_KEY";
+};
+
+/**
+ * Where to send, which key to send it with, and who the CLI says it is.
+ *
+ * The most specific target wins: `--base-url`, then `--local`/`--port`, then
+ * `AUTUMN_BASE_URL`, then the spec's server. Ranking rather than refusing
+ * means a scripted `-l` can be overridden by an ad-hoc `-b` without editing
+ * the script. The env var exists so a directory can pin itself to a local
+ * server through its own `.env` — the default is production.
+ */
+export const resolveTarget = ({
+	prod,
+	sandbox,
+	local,
+	port,
+	baseUrl,
+	clientId,
+}: TargetFlags): Target => {
+	if (prod === true && sandbox !== undefined) {
+		throw new Error("Pick one of --prod and --sandbox.");
+	}
+	// `--prod` overrides a pinned sandbox rather than combining with it: keeping
+	// the pin would make the flag silently address the sandbox anyway.
+	// An empty pin is "no pin": how a parent process addresses the main
+	// sandbox for a child without editing the .env the child will read.
+	const pinned = process.env[SANDBOX_PIN_NAME];
+	const sandboxId =
+		prod === true
+			? undefined
+			: (sandbox ?? (pinned === "" ? undefined : pinned));
+
+	const identity: Omit<Target, "baseUrl"> = {
+		secretKeyName: secretKeyNameFor({ prod: prod === true, sandboxId }),
+		clientId:
+			clientId ??
+			process.env.AUTUMN_CLIENT_ID ??
+			process.env.ATMN_CLI_CLIENT_ID ??
+			CLI_CLIENT_ID,
+		...(sandboxId ? { sandboxId } : {}),
+	};
+
+	if (baseUrl) return { baseUrl, ...identity };
+	// A port implies the host: `--port 3001` alone is a local target.
+	if (local || port) {
+		return {
+			baseUrl: `${LOCAL_HOST}:${port ?? DEFAULT_LOCAL_PORT}`,
+			...identity,
+		};
+	}
+
+	const fromEnv = process.env.AUTUMN_BASE_URL;
+	return fromEnv ? { baseUrl: fromEnv, ...identity } : identity;
+};
+
+/** The concrete URL a command should hit: the target's, else the spec's server. */
+export const targetBaseUrl = ({ target }: { target: Target }): string =>
+	target.baseUrl ?? DEFAULT_BASE_URL;
+
+/**
+ * `sandbox list|create|delete` are organization operations: the server refuses a
+ * sandbox's own key for them, so they drop the pin and use the org key.
+ */
+export const managementTarget = ({ target }: { target: Target }): Target => {
+	if (target.sandboxId === undefined) return target;
+	return {
+		...(target.baseUrl === undefined ? {} : { baseUrl: target.baseUrl }),
+		secretKeyName: "AUTUMN_SECRET_KEY",
+		clientId: target.clientId,
+	};
+};
+
+const missingKeyMessage = ({ name }: { name: SecretKeyName }): string => {
+	if (name === "AUTUMN_SECRET_KEY")
+		return `${name} is not set. Run atmn login, or atmn login --keyless if you don't have an account.`;
+	if (name === "AUTUMN_PROD_SECRET_KEY")
+		return `${name} is not set. Run atmn login.`;
+	return `${name} is not set. Run atmn sandbox create, or add its key to your .env.`;
+};
+
+export const requireSecretKey = ({ target }: { target: Target }): string => {
+	const key = process.env[target.secretKeyName];
+	if (!key) throw new Error(missingKeyMessage({ name: target.secretKeyName }));
+	return key;
+};

package/src/env/sandboxKeyName.ts

@@ -0,0 +1,18 @@
+/** The env var holding one sandbox's secret key. */
+export type SandboxSecretKeyName = `AUTUMN_SANDBOX_${string}_SECRET_KEY`;
+
+const NON_ALPHANUMERIC_RUN = /[^a-z0-9]+/gi;
+
+/**
+ * A sandbox's key lives under a name derived from its id, so a `.env` can hold
+ * a key per sandbox and `--sandbox <id>` alone is enough to find the right one.
+ */
+export const sandboxKeyName = ({
+	sandboxId,
+}: {
+	sandboxId: string;
+}): SandboxSecretKeyName =>
+	`AUTUMN_SANDBOX_${sandboxId.toUpperCase().replace(NON_ALPHANUMERIC_RUN, "_")}_SECRET_KEY`;
+
+/** The env var `atmn sandbox create --use` writes to pin a target sandbox. */
+export const SANDBOX_PIN_NAME = "AUTUMN_SANDBOX_ID";