atmn 1.1.25 → 2.0.0

package/src/actions/env.ts

@@ -0,0 +1,94 @@
+import { DEFAULT_BASE_URL, type Target } from "../env/resolveTarget";
+import { renderEnv } from "../render/renderEnv";
+import type { FetchOrgInfo, OrgInfo } from "./env/types/orgInfo";
+import type { WriteLine } from "./sandbox/types/sandboxClient";
+
+export type EnvOptions = {
+	/** Resolved by the CLI from its global flags: -p, --sandbox, -l all land here. */
+	target: Target;
+	fetchOrgInfo: FetchOrgInfo;
+	json?: boolean;
+	write?: WriteLine;
+};
+
+const isMainSandboxKey = ({ info }: { info: OrgInfo }): boolean =>
+	info.is_sandbox !== true;
+
+/** The same facts an agent reads from `--json`, plus what to do about them. */
+export const envJson = ({
+	info,
+	target,
+}: {
+	info: OrgInfo;
+	target: Target;
+}) => {
+	const isMaster = isMainSandboxKey({ info });
+	const notes: string[] = [];
+	// A pinned sandbox is meant to answer as itself; only the org's own key
+	// answering as a sandbox is the mistake worth flagging.
+	if (!isMaster && target.secretKeyName === "AUTUMN_SECRET_KEY")
+		notes.push(
+			`AUTUMN_SECRET_KEY belongs to sandbox "${info.name}" (${info.id}), not your main sandbox. Sandbox commands need the main key: run atmn login.`,
+		);
+	if (target.sandboxId !== undefined && target.sandboxId !== info.id)
+		notes.push(
+			`AUTUMN_SANDBOX_ID points at ${target.sandboxId} but the key answers as ${info.id}; run atmn sandbox use to repair the pin.`,
+		);
+	if (info.claim_state === "pending")
+		notes.push(
+			`This org has no owner yet${info.claim_expires_at ? ` (link it before ${info.claim_expires_at})` : ""}: atmn login --claim <email>.`,
+		);
+	if (target.sandboxId !== undefined)
+		notes.push("`atmn sandbox use --clear` returns to the main sandbox.");
+	else if (isMaster)
+		notes.push(
+			"`atmn sandbox use <name|id>` targets a named sandbox; `atmn sandbox list` shows them.",
+		);
+	return {
+		organization: { id: info.id, name: info.name, slug: info.slug },
+		env: info.env,
+		isMaster,
+		/** False while a keyless org waits to be linked; true for any owned org. */
+		claimed: info.claim_state !== "pending",
+		claimExpiresAt:
+			info.claim_state === "pending" ? (info.claim_expires_at ?? null) : null,
+		sandbox:
+			target.sandboxId === undefined
+				? null
+				: { id: target.sandboxId, authenticatedAs: info.id },
+		user: info.user ?? null,
+		keyName: target.secretKeyName,
+		baseUrl: target.baseUrl ?? DEFAULT_BASE_URL,
+		notes,
+	};
+};
+
+/** Report which org, env and key this directory's commands would act on. */
+export const runEnv = async ({
+	target,
+	fetchOrgInfo,
+	json = false,
+	write = (text) => process.stdout.write(text),
+}: EnvOptions): Promise<OrgInfo> => {
+	const info = await fetchOrgInfo();
+
+	if (json) {
+		write(`${JSON.stringify(envJson({ info, target }), null, 2)}\n`);
+		return info;
+	}
+
+	write(
+		`${renderEnv({
+			info,
+			secretKeyName: target.secretKeyName,
+			// The default is noise; a local or staging server is the surprise worth showing.
+			...(target.baseUrl === undefined || target.baseUrl === DEFAULT_BASE_URL
+				? {}
+				: { baseUrl: target.baseUrl }),
+			...(target.sandboxId === undefined
+				? {}
+				: { sandboxId: target.sandboxId }),
+		})}\n`,
+	);
+	return info;
+};

package/src/actions/init/runInit.ts

@@ -0,0 +1,401 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { configPackageName } from "../../config/configPackageName";
+import {
+	loadEnvFiles,
+	removeEnvValues,
+	writeEnvValues,
+} from "../../env/loadEnv";
+import { SANDBOX_PIN_NAME, sandboxKeyName } from "../../env/sandboxKeyName";
+import { AutumnApiError } from "../../generated/client";
+import { readMarker, resolveProject } from "../../project/resolveProject";
+import { writeRootMarker } from "../../project/rootMarker";
+import {
+	ask,
+	choose,
+	done,
+	hint,
+	type Prompter,
+	soft,
+} from "../../prompt/prompt";
+import { findRepoLayout } from "../../repo/findRepoRoot";
+import { version } from "../../version";
+import type { OrgInfo } from "../env/types/orgInfo";
+import type { LoginResult } from "../login";
+import {
+	CONNECT_OPTIONS,
+	CONNECT_QUESTION,
+	type KeylessDeps,
+	runKeylessLogin,
+} from "../login/keyless";
+import { scaffoldConfig } from "../pull/scaffoldConfig";
+import { installSkills, SKILLS_DIR_NAME } from "../skills/skills";
+
+/** The network, behind functions so a test can hand over fakes. */
+export type InitDeps = {
+	fetchOrgInfo: ({ secretKey }: { secretKey: string }) => Promise<OrgInfo>;
+	login: ({ envDirs }: { envDirs: string[] }) => Promise<LoginResult>;
+	keyless: KeylessDeps;
+	pull: ({
+		configDir,
+	}: {
+		configDir: string;
+	}) => Promise<{ appended: string[]; replaced: string[]; deleted: string[] }>;
+	/** `<manager> install` at the root, so the new package's config can import the CLI before pull. */
+	install: ({
+		manager,
+		repoRoot,
+	}: {
+		manager: string;
+		repoRoot: string;
+	}) => Promise<boolean>;
+};
+
+export type InitOptions = {
+	cwd?: string;
+	/** What the new package depends on for the builders; the published CLI by default. */
+	dependencySpec?: string;
+	/** Folder for the config, repo-root relative: autumn/ by default, asked for in a monorepo. */
+	path?: string;
+	/** The package's name; asked for in a monorepo. */
+	name?: string;
+	/** How to connect when no usable main key is on disk; asked for otherwise. */
+	connect?: "login" | "keyless";
+	deps: InitDeps;
+	prompter: Prompter;
+};
+
+export type InitResult = {
+	repoRoot: string;
+	configDir: string;
+	configPath: string;
+	org: OrgInfo;
+};
+
+const DEFAULT_PACKAGE_DIR = "packages/autumn";
+const DEFAULT_CONFIG_DIR = "autumn";
+const DEFAULT_PACKAGE_NAME = "autumn";
+const PACKAGE_NAME = configPackageName();
+
+type KeyCheck =
+	| { kind: "main"; info: OrgInfo }
+	| { kind: "sub"; info: OrgInfo; secretKey: string }
+	| { kind: "missing" };
+
+const checkMainKey = async ({
+	deps,
+}: {
+	deps: InitDeps;
+}): Promise<KeyCheck> => {
+	const secretKey = process.env.AUTUMN_SECRET_KEY;
+	if (!secretKey) return { kind: "missing" };
+	try {
+		const info = await deps.fetchOrgInfo({ secretKey });
+		return info.is_sandbox === true
+			? { kind: "sub", info, secretKey }
+			: { kind: "main", info };
+	} catch (error) {
+		// A rejected key is a missing key; a server that cannot be reached is not.
+		if (
+			error instanceof AutumnApiError &&
+			(error.status === 401 || error.status === 403)
+		)
+			return { kind: "missing" };
+		throw error;
+	}
+};
+
+/**
+ * A sub-sandbox key in AUTUMN_SECRET_KEY was the user working inside that
+ * sandbox; it keeps working under its own name, and the pin keeps them there.
+ */
+const relocateSubKey = ({
+	check,
+	envDirs,
+	prompter,
+}: {
+	check: Extract<KeyCheck, { kind: "sub" }>;
+	envDirs: string[];
+	prompter: Prompter;
+}): void => {
+	const keyName = sandboxKeyName({ sandboxId: check.info.id });
+	removeEnvValues({ dirs: envDirs, keys: ["AUTUMN_SECRET_KEY"] });
+	writeEnvValues({
+		dirs: envDirs,
+		values: { [keyName]: check.secretKey, [SANDBOX_PIN_NAME]: check.info.id },
+	});
+	delete process.env.AUTUMN_SECRET_KEY;
+	prompter.write(
+		`${done(`Kept the sandbox key as ${keyName} and pinned ${SANDBOX_PIN_NAME}=${check.info.id}`)}\n`,
+	);
+};
+
+export const CONNECT_CHOICES = [
+	{ value: "login", flag: "--login", label: CONNECT_OPTIONS.login },
+	{ value: "keyless", flag: "--keyless", label: CONNECT_OPTIONS.keyless },
+] as const;
+
+const authenticate = async ({
+	repoRoot,
+	envDirs,
+	connect,
+	deps,
+	prompter,
+}: {
+	repoRoot: string;
+	envDirs: string[];
+	connect: "login" | "keyless" | undefined;
+	deps: InitDeps;
+	prompter: Prompter;
+}): Promise<OrgInfo> => {
+	const check = await checkMainKey({ deps });
+	if (check.kind === "main") {
+		prompter.write(
+			`${done(`Logged in as ${check.info.name} (${check.info.slug})`)}\n`,
+		);
+		return check.info;
+	}
+
+	if (check.kind === "sub") {
+		prompter.write(
+			`${soft(`AUTUMN_SECRET_KEY belongs to sandbox "${check.info.name}" (${check.info.id}), not your main sandbox.`)}\n`,
+		);
+		prompter.write(
+			`  atmn needs your main sandbox key. Logging in mints it; the sandbox key is kept as ${sandboxKeyName({ sandboxId: check.info.id })} and pinned.\n`,
+		);
+	} else {
+		prompter.write(`${soft("No AUTUMN_SECRET_KEY found.")}\n`);
+	}
+
+	const way = await choose({
+		prompter,
+		value: connect,
+		question: CONNECT_QUESTION,
+		options: CONNECT_CHOICES,
+		defaultValue: "login",
+	});
+
+	if (check.kind === "sub") relocateSubKey({ check, envDirs, prompter });
+	if (way === "keyless") {
+		await runKeylessLogin({ repoRoot, envDirs, deps: deps.keyless, prompter });
+	} else {
+		await deps.login({ envDirs });
+		// A rejected key exported in the shell would otherwise shadow the one
+		// login just wrote, since env files never override the process.
+		delete process.env.AUTUMN_SECRET_KEY;
+		loadEnvFiles({ dirs: envDirs });
+	}
+
+	const after = await checkMainKey({ deps });
+	if (after.kind !== "main")
+		throw new Error(
+			"Login finished but AUTUMN_SECRET_KEY still does not answer as your main sandbox.",
+		);
+	prompter.write(
+		`${done(`Logged in as ${after.info.name} (${after.info.slug})`)}\n`,
+	);
+	return after.info;
+};
+
+const readJson = (path: string): Record<string, unknown> =>
+	JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+
+const writeJson = (path: string, value: Record<string, unknown>): void =>
+	writeFileSync(path, `${JSON.stringify(value, null, "\t")}\n`, "utf8");
+
+const packageJsonFor = ({
+	name,
+	dependencySpec,
+}: {
+	name: string;
+	dependencySpec: string;
+}): Record<string, unknown> => ({
+	name,
+	private: true,
+	type: "module",
+	dependencies: { [PACKAGE_NAME]: dependencySpec },
+});
+
+/** A repo with no package.json gets a minimal one: the config needs a package to depend from. */
+const ensureRootManifest = ({ repoRoot }: { repoRoot: string }): string => {
+	const manifestPath = join(repoRoot, "package.json");
+	if (!existsSync(manifestPath))
+		writeJson(manifestPath, { name: "autumn", private: true, type: "module" });
+	return manifestPath;
+};
+
+/** The config imports the CLI, so whichever package owns it depends on it.
+ * True when the manifest changed. */
+const addDependency = ({
+	manifestPath,
+	dependencySpec,
+}: {
+	manifestPath: string;
+	dependencySpec: string;
+}): boolean => {
+	if (!existsSync(manifestPath)) return false;
+	const manifest = readJson(manifestPath);
+	const deps = (manifest.dependencies ?? {}) as Record<string, string>;
+	const devDeps = (manifest.devDependencies ?? {}) as Record<string, string>;
+	if (deps[PACKAGE_NAME] !== undefined || devDeps[PACKAGE_NAME] !== undefined)
+		return false;
+	writeJson(manifestPath, {
+		...manifest,
+		dependencies: { ...deps, [PACKAGE_NAME]: dependencySpec },
+	});
+	return true;
+};
+
+const packageManager = ({ repoRoot }: { repoRoot: string }): string => {
+	if (
+		existsSync(join(repoRoot, "bun.lock")) ||
+		existsSync(join(repoRoot, "bun.lockb"))
+	)
+		return "bun";
+	if (existsSync(join(repoRoot, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(repoRoot, "yarn.lock"))) return "yarn";
+	return "npm";
+};
+
+const runnerFor = (manager: string): string =>
+	manager === "npm" ? "npm run" : manager === "yarn" ? "yarn" : manager;
+
+/**
+ * Auth, path, pull, skills, next steps. Every step prints what it did; a
+ * step that needs an answer prints what to pass and stops, so running the
+ * same command again with the flag continues from there.
+ */
+export const runInit = async ({
+	cwd = process.cwd(),
+	dependencySpec = `^${version}`,
+	path,
+	name,
+	connect,
+	deps,
+	prompter,
+}: InitOptions): Promise<InitResult> => {
+	const { repoRoot, hasWorkspaces } = findRepoLayout({ cwd });
+	const envDirs = [repoRoot];
+	loadEnvFiles({ dirs: envDirs });
+
+	const org = await authenticate({
+		repoRoot,
+		envDirs,
+		connect,
+		deps,
+		prompter,
+	});
+
+	let configDir = cwd;
+	let packageName: string | undefined;
+	// A repo init already placed keeps its answer: the marker is the path.
+	const marker = readMarker({ repoRoot });
+	if (hasWorkspaces) {
+		prompter.write(`${done("Monorepo detected")}\n`);
+		const chosen = await ask({
+			prompter,
+			value:
+				path ??
+				(marker === null
+					? undefined
+					: dirname(resolve(repoRoot, marker.config))),
+			question: "Where should the Autumn package live?",
+			flag: "--path <dir>",
+			example: `--path ${DEFAULT_PACKAGE_DIR}`,
+			defaultValue: DEFAULT_PACKAGE_DIR,
+		});
+		configDir = resolve(repoRoot, chosen);
+		prompter.write(`${done(`Path ${relative(repoRoot, configDir) || "."}`)}\n`);
+		const existingName = existsSync(join(configDir, "package.json"))
+			? (readJson(join(configDir, "package.json")).name as string | undefined)
+			: undefined;
+		packageName = await ask({
+			prompter,
+			value: name ?? existingName,
+			question: "Package name?",
+			flag: "--name <name>",
+			example: "--name @acme/autumn",
+			defaultValue: DEFAULT_PACKAGE_NAME,
+		});
+		prompter.write(`${done(`Name ${packageName}`)}\n`);
+	} else {
+		// A plain project gets its own folder too, unless a config already
+		// sits beside cwd or the marker names one.
+		const found = resolveProject({ cwd }).configPath;
+		configDir = resolve(
+			repoRoot,
+			path ?? (found === null ? DEFAULT_CONFIG_DIR : dirname(found)),
+		);
+		prompter.write(`${done(`Path ${relative(repoRoot, configDir) || "."}`)}\n`);
+	}
+
+	const configPath = join(configDir, "autumn.config.ts");
+	mkdirSync(configDir, { recursive: true });
+	const wrote: string[] = [];
+	let dependencyAdded = false;
+	const manifestPath = join(configDir, "package.json");
+	if (packageName !== undefined && !existsSync(manifestPath)) {
+		writeJson(
+			manifestPath,
+			packageJsonFor({ name: packageName, dependencySpec }),
+		);
+		wrote.push(`${relative(repoRoot, manifestPath)}`);
+		dependencyAdded = true;
+	} else if (
+		addDependency({
+			manifestPath: existsSync(manifestPath)
+				? manifestPath
+				: ensureRootManifest({ repoRoot }),
+			dependencySpec,
+		})
+	) {
+		dependencyAdded = true;
+		prompter.write(`${done(`Added ${PACKAGE_NAME} to package.json`)}\n`);
+	}
+	if (!existsSync(configPath)) {
+		scaffoldConfig({ directory: configDir });
+		wrote.push("autumn.config.ts", "features.ts", "plans.ts", "rewards.ts");
+	}
+	if (wrote.length > 0)
+		prompter.write(`${done(`Wrote ${wrote.join(", ")}`)}\n`);
+	if (writeRootMarker({ repoRoot, configPath }))
+		prompter.write(
+			`${done('Wrote "atmn" script and marker to package.json')}\n`,
+		);
+
+	const manager = packageManager({ repoRoot });
+	const runner = runnerFor(manager);
+	// The scaffolded config imports the CLI; a package written a moment ago
+	// cannot resolve it until its dependency is installed.
+	if (dependencyAdded) {
+		const installed = await deps.install({ manager, repoRoot });
+		if (!installed)
+			throw new Error(
+				`${manager} install failed; run it yourself, then atmn init again.`,
+			);
+		prompter.write(`${done(`Installed with ${manager}`)}\n`);
+	}
+
+	const pulled = await deps.pull({ configDir });
+	const count =
+		pulled.appended.length + pulled.replaced.length + pulled.deleted.length;
+	prompter.write(
+		`${done(count === 0 ? "Sandbox matches the config; nothing to pull" : `Pulled ${count} ${count === 1 ? "entry" : "entries"}`)}\n`,
+	);
+
+	const skillsDir = join(configDir, SKILLS_DIR_NAME);
+	const { written } = installSkills({ dir: skillsDir, write: () => {} });
+	prompter.write(
+		`${done(`Skills: ${relative(repoRoot, skillsDir)}/${written.join(", ")}`)}\n`,
+	);
+
+	prompter.write("\nNext:\n");
+	prompter.write(
+		`${hint(`${runner} atmn push`)}          preview your catalog against the sandbox\n`,
+	);
+	prompter.write(
+		`${hint(`npx skills add ${relative(repoRoot, skillsDir)} -y`)}      make the skills visible to your agent\n`,
+	);
+
+	return { repoRoot, configDir, configPath, org };
+};

package/src/actions/login/keyless.ts

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import {
+	type ClaimStarted,
+	type ProvisionedOrg,
+	provisionKeylessOrg,
+	slugFor,
+	startClaim,
+} from "../../auth/keyless";
+import { writeEnvValues } from "../../env/loadEnv";
+import { type Target, targetBaseUrl } from "../../env/resolveTarget";
+import { done, type Prompter } from "../../prompt/prompt";
+
+/** The one place the two ways in are described; help text and hints both read it. */
+export const CONNECT_OPTIONS = {
+	login: "sign in on the web (opens a browser; prints the URL if it can't)",
+	keyless:
+		"create a sandbox org now, no account needed; link it to an account later with `atmn login --claim <email>`",
+} as const;
+
+export const CONNECT_QUESTION = "How do you want to connect to Autumn?";
+
+export type KeylessDeps = {
+	provision: (params: {
+		name: string;
+		slug: string;
+	}) => Promise<ProvisionedOrg>;
+	startClaim: (params: {
+		secretKey: string;
+		email: string;
+	}) => Promise<ClaimStarted>;
+};
+
+export const keylessDepsFor = ({ target }: { target: Target }): KeylessDeps => {
+	const baseUrl = targetBaseUrl({ target });
+	return {
+		provision: ({ name, slug }) => provisionKeylessOrg({ baseUrl, name, slug }),
+		startClaim: ({ secretKey, email }) =>
+			startClaim({ baseUrl, secretKey, email }),
+	};
+};
+
+/** The org is named after the project: the root package's name, else the folder. */
+export const projectNameFor = ({ repoRoot }: { repoRoot: string }): string => {
+	const manifest = join(repoRoot, "package.json");
+	if (existsSync(manifest)) {
+		try {
+			const name = (
+				JSON.parse(readFileSync(manifest, "utf8")) as { name?: unknown }
+			).name;
+			if (typeof name === "string" && name.trim() !== "") return name.trim();
+		} catch {
+			// Fall through to the folder name.
+		}
+	}
+	return basename(repoRoot) || "autumn";
+};
+
+const daysUntil = (iso: string): string => {
+	const ms = new Date(iso).getTime() - Date.now();
+	if (Number.isNaN(ms)) return iso;
+	const days = Math.max(1, Math.round(ms / 86_400_000));
+	return `${days} day${days === 1 ? "" : "s"}`;
+};
+
+export type KeylessLoginResult = {
+	envPath: string;
+	orgId: string;
+	orgSlug: string;
+	claimExpiresAt: string;
+};
+
+/** A sandbox org with no owner, its key in .env; the account comes later. */
+export const runKeylessLogin = async ({
+	repoRoot,
+	envDirs,
+	name = projectNameFor({ repoRoot }),
+	deps,
+	prompter,
+}: {
+	repoRoot: string;
+	envDirs: string[];
+	/** The org's name; the slug derives from it. */
+	name?: string;
+	deps: KeylessDeps;
+	prompter: Prompter;
+}): Promise<KeylessLoginResult> => {
+	const provisioned = await deps.provision({ name, slug: slugFor(name) });
+	const envPath = writeEnvValues({
+		dirs: envDirs,
+		values: { AUTUMN_SECRET_KEY: provisioned.apiKey },
+	});
+	process.env.AUTUMN_SECRET_KEY = provisioned.apiKey;
+	prompter.write(
+		`${done(`Created sandbox org ${provisioned.organizationSlug} (keyless). Wrote AUTUMN_SECRET_KEY to ${envPath}`)}\n`,
+	);
+	prompter.write(
+		`  This org has no owner yet. Link it within ${daysUntil(provisioned.claimExpiresAt)}: atmn login --claim you@example.com\n`,
+	);
+	return {
+		envPath,
+		orgId: provisioned.organizationId,
+		orgSlug: provisioned.organizationSlug,
+		claimExpiresAt: provisioned.claimExpiresAt,
+	};
+};
+
+const minutesUntil = (iso: string): string => {
+	const ms = new Date(iso).getTime() - Date.now();
+	if (Number.isNaN(ms)) return iso;
+	return `${Math.max(1, Math.round(ms / 60_000))} min`;
+};
+
+/** Create a browser link that attaches this keyless org to the requested account. */
+export const runClaim = async ({
+	secretKey,
+	email,
+	deps,
+	prompter,
+}: {
+	secretKey: string;
+	email: string;
+	deps: KeylessDeps;
+	prompter: Prompter;
+}): Promise<ClaimStarted> => {
+	const started = await deps.startClaim({ secretKey, email });
+	prompter.write(
+		`${done(`Created a claim link for ${email} (expires in ${minutesUntil(started.expiresAt)})`)}\n`,
+	);
+	prompter.write(`  ${started.claimUrl}\n`);
+	prompter.write(
+		`  The same link was emailed to ${email}. Sign in there to claim the org; the existing key stays valid.\n`,
+	);
+	return started;
+};