atmn 1.1.24 → 2.0.0

package/src/prompt/prompt.ts

@@ -0,0 +1,186 @@
+import chalk from "chalk";
+
+/** Where a command writes its lines. Injected so tests can capture it. */
+export type WriteLine = (text: string) => void;
+
+/**
+ * Every prompt has a flag. In a terminal the question is asked inline; with
+ * `--headless`, or no TTY, the same line is printed as a hint and the command
+ * stops there, so an agent reads what to pass and runs again.
+ */
+export type Prompter = {
+	interactive: boolean;
+	write: WriteLine;
+	/** Reads one answer, showing `prompt` at the cursor; injected for tests. */
+	readLine: (prompt: string) => Promise<string | null>;
+};
+
+export const done = (text: string): string => `${chalk.green("✓")} ${text}`;
+export const needs = (text: string): string => `${chalk.cyan("→")} ${text}`;
+export const soft = (text: string): string => `${chalk.yellow("!")} ${text}`;
+export const same = (text: string): string => `${chalk.dim("=")} ${text}`;
+export const hint = (text: string): string => `  ${chalk.cyan(text)}`;
+
+/** Thrown when a headless run stops at a prompt; the CLI exits 0 on it. */
+export class NeedsInputError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NeedsInputError";
+	}
+}
+
+/**
+ * A fresh readline per question loses keys typed before it opened; one
+ * interface per process keeps them. Readline owns the prompt text: it redraws
+ * the line on every keystroke, so anything written beside it would vanish.
+ */
+export const defaultReadLine = (() => {
+	let rl: import("node:readline").Interface | undefined;
+	return async (prompt: string): Promise<string | null> => {
+		if (rl === undefined) {
+			const { createInterface } = await import("node:readline");
+			rl = createInterface({ input: process.stdin, output: process.stdout });
+		}
+		const active = rl;
+		return new Promise((resolve) => {
+			const onClose = () => resolve(null);
+			active.once("close", onClose);
+			active.question(prompt, (answer) => {
+				active.off("close", onClose);
+				resolve(answer);
+			});
+		});
+	};
+})();
+
+/** Nothing else reads stdin after the last question; without this the process waits on it. */
+export const releaseStdin = (): void => {
+	process.stdin.pause();
+};
+
+export const createPrompter = ({
+	interactive,
+	write = (text) => process.stdout.write(text),
+	readLine = defaultReadLine,
+}: {
+	interactive: boolean;
+	write?: WriteLine;
+	readLine?: (prompt: string) => Promise<string | null>;
+}): Prompter => ({ interactive, write, readLine });
+
+/**
+ * A value the command needs. Given → returned as is. Absent and interactive →
+ * asked, the flag's example as the placeholder. Absent and headless → the
+ * `→` line and the flag hint are printed and the run stops.
+ */
+export const ask = async ({
+	prompter,
+	value,
+	question,
+	flag,
+	example,
+	defaultValue,
+}: {
+	prompter: Prompter;
+	value: string | undefined;
+	question: string;
+	/** `--path <dir>`: what a headless caller passes. */
+	flag: string;
+	example?: string;
+	/** Enter with nothing typed picks this; headless never assumes it. */
+	defaultValue?: string;
+}): Promise<string> => {
+	if (value !== undefined && value !== "") return value;
+	const flagHint = `Provide ${flag}${example === undefined ? "" : `, e.g. ${example}`}`;
+	if (!prompter.interactive) {
+		prompter.write(`${needs(question)}\n${hint(flagHint)}\n`);
+		throw new NeedsInputError(flagHint);
+	}
+	const placeholder =
+		defaultValue !== undefined
+			? chalk.dim(` (${defaultValue})`)
+			: example !== undefined
+				? chalk.dim(` (e.g. ${example})`)
+				: "";
+	const answer =
+		(await prompter.readLine(`${needs(question)}${placeholder} `))?.trim() ??
+		"";
+	if (answer !== "") return answer;
+	if (defaultValue !== undefined) return defaultValue;
+	throw new NeedsInputError(flagHint);
+};
+
+/** A yes/no. Headless prints the hint for the flag that says yes and stops. */
+export const confirm = async ({
+	prompter,
+	value,
+	question,
+	flag,
+}: {
+	prompter: Prompter;
+	value: boolean | undefined;
+	question: string;
+	flag: string;
+}): Promise<boolean> => {
+	if (value !== undefined) return value;
+	if (!prompter.interactive) {
+		prompter.write(`${needs(question)}\n${hint(`Pass ${flag} to continue`)}\n`);
+		throw new NeedsInputError(`Pass ${flag} to continue`);
+	}
+	const answer =
+		(await prompter.readLine(`${needs(question)} ${chalk.dim("[Y/n]")} `))
+			?.trim()
+			.toLowerCase() ?? "";
+	return answer === "" || answer === "y" || answer === "yes";
+};
+
+/**
+ * One question, a short list of flags as answers. Headless prints the
+ * question and one line per flag; interactive numbers them and reads a pick.
+ */
+export const choose = async <T extends string>({
+	prompter,
+	value,
+	question,
+	options,
+	defaultValue,
+}: {
+	prompter: Prompter;
+	/** The option already picked by flag, when one was. */
+	value: T | undefined;
+	question: string;
+	options: readonly { value: T; flag: string; label: string }[];
+	defaultValue: T;
+}): Promise<T> => {
+	if (value !== undefined) return value;
+	const width = Math.max(...options.map((option) => option.flag.length));
+	if (!prompter.interactive) {
+		prompter.write(
+			`${needs(question)}\n${options
+				.map((option) => hint(`${option.flag.padEnd(width)}  ${option.label}`))
+				.join("\n")}\n`,
+		);
+		throw new NeedsInputError(
+			`Pass ${options.map((option) => option.flag).join(" or ")}`,
+		);
+	}
+	const defaultIndex = options.findIndex(
+		(option) => option.value === defaultValue,
+	);
+	prompter.write(`${needs(question)}\n`);
+	for (const [index, option] of options.entries())
+		prompter.write(`  ${index + 1}) ${option.label}\n`);
+	const answer =
+		(
+			await prompter.readLine(`  ${chalk.dim(`[${defaultIndex + 1}]`)}: `)
+		)?.trim() ?? "";
+	if (answer === "") return defaultValue;
+	const picked = /^\d+$/.test(answer)
+		? options[Number(answer) - 1]
+		: options.find(
+				(option) => option.value === answer || option.flag === answer,
+			);
+	if (picked === undefined)
+		throw new NeedsInputError(`Unknown answer ${JSON.stringify(answer)}`);
+	return picked.value;
+};

package/src/prompt/select.ts

@@ -0,0 +1,162 @@
+import chalk from "chalk";
+import { hint, needs, type Prompter } from "./prompt";
+
+export type Choice = {
+	/** What is matched by the filter and returned. */
+	value: string;
+	/** Printed in white. */
+	label: string;
+	/** Printed dim in brackets. */
+	detail?: string;
+	current?: boolean;
+};
+
+const PAGE_SIZE = 10;
+
+const CURRENT_MARKER = "← current";
+
+export const renderChoices = ({
+	choices,
+	cursor,
+	filter,
+}: {
+	choices: Choice[];
+	cursor: number;
+	filter: string;
+}): string => {
+	const visible = filterChoices({ choices, filter });
+	const page = Math.floor(cursor / PAGE_SIZE);
+	const start = page * PAGE_SIZE;
+	const rows = visible.slice(start, start + PAGE_SIZE).map((choice, index) => {
+		const selected = start + index === cursor;
+		const pointer = selected ? chalk.cyan("❯") : " ";
+		const label = selected ? chalk.bold(choice.label) : choice.label;
+		const detail =
+			choice.detail === undefined ? "" : ` ${chalk.dim(`(${choice.detail})`)}`;
+		const current = choice.current ? ` ${chalk.dim(CURRENT_MARKER)}` : "";
+		return `${pointer} ${label}${detail}${current}`;
+	});
+	const footer =
+		visible.length > PAGE_SIZE
+			? chalk.dim(
+					`  ${start + 1}-${Math.min(start + PAGE_SIZE, visible.length)} of ${visible.length}`,
+				)
+			: "";
+	const search = `  ${chalk.dim("type to filter:")} ${filter}`;
+	return [...rows, ...(footer ? [footer] : []), search].join("\n");
+};
+
+export const filterChoices = ({
+	choices,
+	filter,
+}: {
+	choices: Choice[];
+	filter: string;
+}): Choice[] => {
+	const needle = filter.trim().toLowerCase();
+	if (needle === "") return choices;
+	return choices.filter(
+		(choice) =>
+			choice.label.toLowerCase().includes(needle) ||
+			choice.value.toLowerCase().includes(needle),
+	);
+};
+
+/** A name or id typed by an agent: exact id first, then exact label, then a unique prefix. */
+export const matchChoice = ({
+	choices,
+	query,
+}: {
+	choices: Choice[];
+	query: string;
+}): Choice | null => {
+	const byValue = choices.find((choice) => choice.value === query);
+	if (byValue) return byValue;
+	const lower = query.toLowerCase();
+	const byLabel = choices.filter(
+		(choice) => choice.label.toLowerCase() === lower,
+	);
+	if (byLabel.length === 1) return byLabel[0] ?? null;
+	const byPrefix = filterChoices({ choices, filter: query });
+	return byPrefix.length === 1 ? (byPrefix[0] ?? null) : null;
+};
+
+const ESC = "\u001b";
+
+/**
+ * Arrow keys move, typing filters, enter picks. Raw-mode stdin, redrawn in
+ * place. Headless callers never get here: `select` prints the hint instead.
+ */
+const interactiveSelect = async ({
+	choices,
+	write,
+}: {
+	choices: Choice[];
+	write: (text: string) => void;
+}): Promise<Choice | null> => {
+	const stdin = process.stdin;
+	let cursor = Math.max(
+		0,
+		choices.findIndex((choice) => choice.current),
+	);
+	let filter = "";
+	let lines = 0;
+
+	const draw = () => {
+		if (lines > 0) write(`${ESC}[${lines}A${ESC}[J`);
+		const text = renderChoices({ choices, cursor, filter });
+		lines = text.split("\n").length;
+		write(`${text}\n`);
+	};
+
+	return new Promise((resolve) => {
+		stdin.setRawMode?.(true);
+		stdin.resume();
+		stdin.setEncoding("utf8");
+		draw();
+		const finish = (choice: Choice | null) => {
+			stdin.off("data", onData);
+			stdin.setRawMode?.(false);
+			stdin.pause();
+			resolve(choice);
+		};
+		const onData = (key: string) => {
+			const visible = filterChoices({ choices, filter });
+			if (key === "\u0003" || key === `${ESC}`) return finish(null);
+			if (key === "\r" || key === "\n") return finish(visible[cursor] ?? null);
+			if (key === `${ESC}[A`) cursor = Math.max(0, cursor - 1);
+			else if (key === `${ESC}[B`)
+				cursor = Math.min(Math.max(0, visible.length - 1), cursor + 1);
+			else if (key === "\u007f" || key === "\b") {
+				filter = filter.slice(0, -1);
+				cursor = 0;
+			} else if (!key.startsWith(ESC) && [...key].every((c) => c >= " ")) {
+				// A paste arrives as one chunk; typing as one char at a time.
+				filter += key;
+				cursor = 0;
+			}
+			draw();
+		};
+		stdin.on("data", onData);
+	});
+};
+
+export const select = async ({
+	prompter,
+	choices,
+	question,
+	flag,
+}: {
+	prompter: Prompter;
+	choices: Choice[];
+	question: string;
+	/** `atmn sandbox use <name|id>`: what a headless caller runs instead. */
+	flag: string;
+}): Promise<Choice | null> => {
+	if (!prompter.interactive) {
+		prompter.write(`${needs(question)}\n${hint(flag)}\n`);
+		return null;
+	}
+	prompter.write(`${needs(question)}\n`);
+	return interactiveSelect({ choices, write: prompter.write });
+};

package/src/render/renderEnv.ts

@@ -0,0 +1,77 @@
+import chalk from "chalk";
+import type { OrgInfo } from "../actions/env/types/orgInfo";
+import { stripTerminalControls } from "./stripTerminalControls";
+
+const GAP = "  ";
+
+const envLabel = ({ env }: { env: string }): string => {
+	if (env === "sandbox") return "Sandbox";
+	if (env === "live") return "Production";
+	return env;
+};
+
+/**
+ * A sandbox key authenticates as the sandbox's own org, so the id the server
+ * answers with is the sandbox the key really unlocks. A pin whose key answers
+ * as something else is a stale or copied key, and worth saying out loud.
+ */
+const sandboxCell = ({
+	sandboxId,
+	authenticatedId,
+}: {
+	sandboxId: string;
+	authenticatedId: string;
+}): string =>
+	sandboxId === authenticatedId
+		? sandboxId
+		: `${sandboxId} ${chalk.yellow(`← key belongs to ${authenticatedId}`)}`;
+
+/**
+ * Headless rendering, like the sandbox table: a label column a terminal or a
+ * CI log can read. Nothing here decides anything — it reports what the server
+ * said about the key, plus where that key came from.
+ */
+export const renderEnv = ({
+	info,
+	secretKeyName,
+	baseUrl,
+	sandboxId,
+}: {
+	info: OrgInfo;
+	/** The env var the key was read from; says which flag or pin picked it. */
+	secretKeyName: string;
+	/** Only shown when it is not the spec's server. */
+	baseUrl?: string;
+	sandboxId?: string;
+}): string => {
+	const rows: [string, string][] = [
+		[
+			"Organization",
+			`${stripTerminalControls(info.name)} ${chalk.dim(`(${stripTerminalControls(info.slug)})`)}`,
+		],
+		["Environment", envLabel({ env: stripTerminalControls(info.env) })],
+	];
+	if (sandboxId !== undefined) {
+		rows.push([
+			"Sandbox",
+			sandboxCell({
+				sandboxId,
+				authenticatedId: stripTerminalControls(info.id),
+			}),
+		]);
+	}
+	if (info.claim_state === "pending")
+		rows.push([
+			"Owner",
+			`${chalk.yellow("unclaimed")} ${chalk.dim("(link with atmn login --claim <email>)")}`,
+		]);
+	if (info.user?.email !== undefined)
+		rows.push(["User", stripTerminalControls(info.user.email)]);
+	rows.push(["Key", secretKeyName]);
+	if (baseUrl !== undefined) rows.push(["Server", baseUrl]);
+
+	const width = Math.max(...rows.map(([label]) => label.length));
+	return rows
+		.map(([label, value]) => `${chalk.dim(label.padEnd(width))}${GAP}${value}`)
+		.join("\n");
+};