@neondatabase/env 0.0.0 → 0.1.0

package/src/lib/cli/commands.ts

@@ -1,267 +0,0 @@
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import {
-	ConfigLoadError,
-	ErrorCode,
-	loadConfigFromFile,
-	MissingContextError,
-	type NeonApi,
-	PlatformError,
-} from "@neondatabase/config/v1";
-import { fetchEnv, toEntries } from "../env.js";
-import { resolveContext } from "./resolve-context.js";
-
-/** File `env run` reads to layer one-time auth keys. Matches the Vercel/Next.js convention. */
-const DEFAULT_ENV_FILE = ".env.local";
-
-/**
- * Cross-cutting environment a CLI command is allowed to touch. Injected so tests can drive
- * the handler with a custom NeonApi and a controlled `cwd` without spawning child
- * processes.
- */
-export interface CommandEnv {
-	cwd: string;
-	/**
-	 * When set, used directly as the NeonApi. When omitted, the real adapter is built from
-	 * `options.apiKey ?? NEON_API_KEY` inside `fetchEnv`.
-	 */
-	api?: NeonApi;
-}
-
-export interface CommandResult {
-	/** Process exit code. `0` for success, non-zero for failure. */
-	exitCode: number;
-	/** Text intended for stdout. */
-	stdout: string;
-	/** Text intended for stderr (human-readable status / error messages). */
-	stderr: string;
-	/** Optional structured debug payload — printed only when `--debug` is passed. */
-	debugInfo?: string;
-}
-
-export interface EnvRunCommandOptions {
-	/** The user command to spawn (after `--`). The first element is the executable. */
-	command: string[];
-	configPath?: string;
-	projectId?: string;
-	branch?: string;
-	apiKey?: string;
-}
-
-/**
- * Implementation of `neon-env run -- <cmd...>`. Loads `neon.ts`, fetches the env from
- * Neon, then spawns the user-supplied command with the env vars injected on top of the
- * inherited `process.env`. Stdio is inherited so interactive dev servers keep working.
- * The parent process exits with the child's exit code.
- */
-export async function runEnvRun(
-	options: EnvRunCommandOptions,
-	ctx: CommandEnv,
-): Promise<CommandResult> {
-	if (options.command.length === 0) {
-		return failure(
-			[
-				"`env run` requires a command to spawn.",
-				"Usage: neon-env run -- <command> [args...]",
-				"Example: neon-env run -- npm run dev",
-			].join("\n"),
-		);
-	}
-
-	// The CLI owns project/branch resolution (flags → NEON_* env → .neon file) so the
-	// library functions stay filesystem/env-agnostic.
-	const resolved = resolveContext({
-		cwd: ctx.cwd,
-		...(options.projectId ? { projectId: options.projectId } : {}),
-		...(options.branch ? { branch: options.branch } : {}),
-	});
-	if (!resolved.ok) {
-		return failure(
-			[
-				"`env run` could not resolve the Neon project and branch:",
-				...resolved.missing.map((m) => `  - ${m}`),
-			].join("\n"),
-			3,
-		);
-	}
-
-	let injected: Record<string, string>;
-	try {
-		const env = await loadConfigAndFetchEnv(options, ctx, resolved.context);
-		injected = toEntries(env);
-	} catch (err) {
-		return handleError(err);
-	}
-
-	const [executable, ...args] = options.command;
-	const exitCode = await spawnAndWait(executable, args, {
-		cwd: ctx.cwd,
-		env: { ...process.env, ...injected },
-	});
-	return { exitCode, stdout: "", stderr: "" };
-}
-
-/**
- * Load `neon.ts`, then call `fetchEnv` with the explicitly-resolved project + branch.
- * Layers any one-time Auth keys from `.env.local` (next to the config file) into the env
- * source so re-runs keep round-tripping values the Neon API only returns once at
- * integration-creation time.
- */
-async function loadConfigAndFetchEnv(
-	options: EnvRunCommandOptions,
-	ctx: CommandEnv,
-	resolved: { projectId: string; branchId: string },
-): Promise<Awaited<ReturnType<typeof fetchEnv>>> {
-	const { config, resolvedPath } = await loadConfigFromFile({
-		...(options.configPath ? { path: options.configPath } : {}),
-		cwd: ctx.cwd,
-	});
-	const envFileSource = join(dirname(resolvedPath), DEFAULT_ENV_FILE);
-	const fileEnv = existsSync(envFileSource)
-		? parseEnvFile(readFileSync(envFileSource, "utf-8"))
-		: {};
-	return fetchEnv(config, {
-		projectId: resolved.projectId,
-		branchId: resolved.branchId,
-		env: { ...process.env, ...fileEnv },
-		...(ctx.api ? { api: ctx.api } : {}),
-		...(options.apiKey ? { apiKey: options.apiKey } : {}),
-	});
-}
-
-/**
- * Spawn a child process with stdio inherited so dev servers stay interactive. Resolves
- * with the child's exit code (treating signal terminations as code 1 so the CLI surfaces
- * a non-zero exit consistently).
- */
-function spawnAndWait(
-	command: string,
-	args: string[],
-	options: { cwd: string; env: Record<string, string | undefined> },
-): Promise<number> {
-	return new Promise((resolve) => {
-		const child = spawn(command, args, {
-			cwd: options.cwd,
-			env: options.env,
-			stdio: "inherit",
-		});
-		child.on("error", (err) => {
-			process.stderr.write(
-				`neon-env run: failed to spawn '${command}': ${err.message}\n`,
-			);
-			resolve(1);
-		});
-		child.on("exit", (code, signal) => {
-			if (typeof code === "number") {
-				resolve(code);
-				return;
-			}
-			if (signal) {
-				process.stderr.write(
-					`neon-env run: child terminated by signal ${signal}\n`,
-				);
-				resolve(1);
-				return;
-			}
-			resolve(1);
-		});
-	});
-}
-
-function parseEnvFile(body: string): NodeJS.ProcessEnv {
-	const out: NodeJS.ProcessEnv = {};
-	for (const line of body.split("\n")) {
-		const parsed = parseEnvLine(line);
-		if (parsed) out[parsed.key] = parsed.value;
-	}
-	return out;
-}
-
-function parseEnvLine(line: string): { key: string; value: string } | null {
-	const match = line.match(
-		/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/,
-	);
-	const key = match?.[1];
-	const rawValue = match?.[2];
-	if (key === undefined || rawValue === undefined) return null;
-	return { key, value: unescapeEnvValue(rawValue.trim()) };
-}
-
-function unescapeEnvValue(value: string): string {
-	if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
-		return value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
-	}
-	if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
-		return value.slice(1, -1);
-	}
-	return value;
-}
-
-/**
- * Stable exit code per `PlatformError` code. Mirrors the table in the config package so
- * shell pipelines can branch on the specific failure mode without parsing free text.
- */
-const EXIT_CODE_BY_PLATFORM_ERROR_CODE: Readonly<Record<string, number>> = {
-	[ErrorCode.MissingApiKey]: 1,
-	[ErrorCode.Unauthorized]: 6,
-	[ErrorCode.Forbidden]: 7,
-	[ErrorCode.NotFound]: 8,
-	[ErrorCode.RateLimited]: 9,
-	[ErrorCode.NetworkError]: 10,
-	[ErrorCode.ServerError]: 11,
-	[ErrorCode.Locked]: 11,
-	[ErrorCode.InternalError]: 99,
-};
-
-function handleError(err: unknown): CommandResult {
-	if (err instanceof MissingContextError)
-		return errorResult(err, `Missing context: ${err.message}`, 3);
-	if (err instanceof ConfigLoadError)
-		return errorResult(err, `Failed to load config: ${err.message}`, 4);
-	if (err instanceof PlatformError) {
-		const exitCode = EXIT_CODE_BY_PLATFORM_ERROR_CODE[err.code];
-		if (exitCode !== undefined)
-			return errorResult(err, err.message, exitCode);
-		return errorResult(err, `[${err.code}] ${err.message}`, 5);
-	}
-	if (err instanceof Error) return errorResult(err, err.message, 1);
-	return failure(String(err), 1);
-}
-
-function errorResult(
-	err: unknown,
-	message: string,
-	exitCode: number,
-): CommandResult {
-	const result: CommandResult = {
-		exitCode,
-		stdout: "",
-		stderr: `${message}\n`,
-	};
-	const debug = buildDebugInfo(err);
-	if (debug) result.debugInfo = debug;
-	return result;
-}
-
-function buildDebugInfo(err: unknown): string | undefined {
-	if (!(err instanceof Error)) return undefined;
-	const lines: string[] = [];
-	if (err instanceof PlatformError) {
-		lines.push(`code     : ${err.code}`);
-		if (Object.keys(err.details).length > 0) {
-			lines.push(`details  : ${JSON.stringify(err.details, null, 2)}`);
-		}
-	}
-	if (err.cause instanceof Error) {
-		lines.push(`cause    : ${err.cause.name}: ${err.cause.message}`);
-	}
-	if (err.stack) {
-		lines.push(err.stack);
-	}
-	return lines.length > 0 ? lines.join("\n") : undefined;
-}
-
-function failure(message: string, exitCode = 1): CommandResult {
-	return { exitCode, stdout: "", stderr: `${message}\n` };
-}

package/src/lib/cli/resolve-context.test.ts

@@ -1,242 +0,0 @@
-import { afterEach, describe, expect, test } from "vitest";
-import { makeTempRepo } from "../test-utils.js";
-import { resolveContext } from "./resolve-context.js";
-
-const cleanups: Array<() => void> = [];
-afterEach(() => {
-	while (cleanups.length > 0) cleanups.shift()?.();
-});
-
-function setup(files: Record<string, string | null>) {
-	const repo = makeTempRepo(files);
-	cleanups.push(repo.cleanup);
-	return repo.root;
-}
-
-/** An env with every NEON_* key explicitly unset, so the test controls precedence. */
-const EMPTY_ENV: NodeJS.ProcessEnv = {};
-
-describe("resolveContext — precedence", () => {
-	test("explicit options win over env and file", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "proj-file",
-				branchId: "br-file",
-			}),
-		});
-		const result = resolveContext({
-			cwd: root,
-			projectId: "proj-opt",
-			branch: "br-opt",
-			env: {
-				NEON_PROJECT_ID: "proj-env",
-				NEON_BRANCH_ID: "br-env",
-			},
-		});
-		expect(result).toEqual({
-			ok: true,
-			context: { projectId: "proj-opt", branchId: "br-opt" },
-		});
-	});
-
-	test("env wins over the .neon file when no option is given", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "proj-file",
-				branchId: "br-file",
-			}),
-		});
-		const result = resolveContext({
-			cwd: root,
-			env: {
-				NEON_PROJECT_ID: "proj-env",
-				NEON_BRANCH_ID: "br-env",
-			},
-		});
-		expect(result).toMatchObject({
-			ok: true,
-			context: { projectId: "proj-env", branchId: "br-env" },
-		});
-	});
-
-	test("falls back to .neon/project.json when no option or env", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "proj-file",
-				branchId: "br-file",
-				branchName: "main",
-			}),
-		});
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		expect(result).toEqual({
-			ok: true,
-			context: {
-				projectId: "proj-file",
-				branchId: "br-file",
-				branchName: "main",
-			},
-		});
-	});
-
-	test("NEON_BRANCH_NAME populates branchName", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "p",
-				branchId: "br-1",
-			}),
-		});
-		const result = resolveContext({
-			cwd: root,
-			env: { NEON_BRANCH_NAME: "feature-x" },
-		});
-		expect(result).toMatchObject({
-			ok: true,
-			context: { branchName: "feature-x" },
-		});
-	});
-});
-
-describe("resolveContext — .neon file discovery", () => {
-	test("reads the bare `.neon` neonctl-convention file", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon": JSON.stringify({
-				projectId: "p-bare",
-				branchId: "br-bare",
-			}),
-		});
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		expect(result).toMatchObject({
-			ok: true,
-			context: { projectId: "p-bare", branchId: "br-bare" },
-		});
-	});
-
-	test("prefers .neon/project.json over a bare .neon in the same dir", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "p-dir",
-				branchId: "br-dir",
-			}),
-		});
-		// (A bare `.neon` file cannot coexist with a `.neon/` directory, so the
-		// preference is exercised structurally by the dir form resolving first.)
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		expect(result).toMatchObject({
-			ok: true,
-			context: { projectId: "p-dir" },
-		});
-	});
-
-	test("walks up from a nested dir to a workspace-root .neon", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "p-root",
-				branchId: "br-root",
-			}),
-			"packages/db/package.json": "{}",
-		});
-		const result = resolveContext({
-			cwd: `${root}/packages/db`,
-			env: EMPTY_ENV,
-		});
-		expect(result).toMatchObject({
-			ok: true,
-			context: { projectId: "p-root", branchId: "br-root" },
-		});
-	});
-
-	test("stops the upward walk at the .git boundary", () => {
-		// `.neon` lives ABOVE the repo root; the walk must not escape past `.git`.
-		const outer = setup({
-			".neon/project.json": JSON.stringify({
-				projectId: "p-outer",
-				branchId: "br-outer",
-			}),
-		});
-		// Seed an inner repo with its own `.git` and no context file.
-		const innerRepo = makeTempRepo({ "package.json": "{}" });
-		cleanups.push(innerRepo.cleanup);
-		// The inner repo is a separate temp dir, so walking from it never reaches `outer`.
-		const result = resolveContext({ cwd: innerRepo.root, env: EMPTY_ENV });
-		expect(result.ok).toBe(false);
-		void outer;
-	});
-
-	test("treats malformed .neon JSON as absent", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": "{ not valid json",
-		});
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		expect(result.ok).toBe(false);
-	});
-
-	test("ignores empty-string fields in the .neon file", () => {
-		const root = setup({
-			"package.json": "{}",
-			".neon/project.json": JSON.stringify({
-				projectId: "",
-				branchId: "br-1",
-			}),
-		});
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		// projectId empty → unresolved; branchId present.
-		expect(result.ok).toBe(false);
-	});
-});
-
-describe("resolveContext — missing fields", () => {
-	test("reports both missing when nothing resolves", () => {
-		const root = setup({ "package.json": "{}" });
-		const result = resolveContext({ cwd: root, env: EMPTY_ENV });
-		expect(result.ok).toBe(false);
-		if (result.ok) throw new Error("expected failure");
-		expect(result.missing).toHaveLength(2);
-		expect(result.missing[0]).toContain("project id");
-		expect(result.missing[1]).toContain("branch");
-	});
-
-	test("reports only branch missing when projectId resolves", () => {
-		const root = setup({ "package.json": "{}" });
-		const result = resolveContext({
-			cwd: root,
-			projectId: "p",
-			env: EMPTY_ENV,
-		});
-		expect(result.ok).toBe(false);
-		if (result.ok) throw new Error("expected failure");
-		expect(result.missing).toHaveLength(1);
-		expect(result.missing[0]).toContain("branch");
-	});
-
-	test("reports only project missing when branch resolves", () => {
-		const root = setup({ "package.json": "{}" });
-		const result = resolveContext({
-			cwd: root,
-			branch: "br-1",
-			env: EMPTY_ENV,
-		});
-		expect(result.ok).toBe(false);
-		if (result.ok) throw new Error("expected failure");
-		expect(result.missing).toHaveLength(1);
-		expect(result.missing[0]).toContain("project id");
-	});
-
-	test("trims whitespace-only values to missing", () => {
-		const root = setup({ "package.json": "{}" });
-		const result = resolveContext({
-			cwd: root,
-			projectId: "   ",
-			branch: "  ",
-			env: EMPTY_ENV,
-		});
-		expect(result.ok).toBe(false);
-	});
-});

package/src/lib/cli/resolve-context.ts

@@ -1,142 +0,0 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
-
-/**
- * Resolved project + branch context for the `neon-env` CLI. The CLI owns this resolution
- * (flags → `NEON_*` env → `.neon[/project.json]` file) so the `@neondatabase/env` library
- * functions can stay filesystem- and env-agnostic.
- */
-export interface ResolvedContext {
-	projectId: string;
-	branchId: string;
-	/** Branch name for `parseEnv`-style policy evaluation, when known. */
-	branchName?: string;
-}
-
-export interface ResolveContextOptions {
-	projectId?: string;
-	branch?: string;
-	cwd: string;
-	env?: NodeJS.ProcessEnv;
-}
-
-/**
- * Resolve `projectId` and `branch` for a CLI invocation. Precedence (each wins over the
- * next): explicit flag → `NEON_*` env var → `.neon[/project.json]` walked up from `cwd`.
- *
- * Returns the resolved values plus a list of human-readable reasons for any field that
- * could not be resolved (so the caller can render one combined error).
- */
-export function resolveContext(
-	options: ResolveContextOptions,
-): { ok: true; context: ResolvedContext } | { ok: false; missing: string[] } {
-	const env = options.env ?? process.env;
-	const file = findNeonFile(options.cwd);
-
-	const projectId =
-		nonEmpty(options.projectId) ??
-		nonEmpty(env.NEON_PROJECT_ID) ??
-		file?.projectId;
-
-	const branchId =
-		nonEmpty(options.branch) ??
-		nonEmpty(env.NEON_BRANCH_ID) ??
-		file?.branchId;
-
-	const branchName = nonEmpty(env.NEON_BRANCH_NAME) ?? file?.branchName;
-
-	const missing: string[] = [];
-	if (!projectId) {
-		missing.push(
-			"project id — pass `--project-id`, set `NEON_PROJECT_ID`, or add `projectId` to `.neon/project.json` (run `npx neonctl link`).",
-		);
-	}
-	if (!branchId) {
-		missing.push(
-			"branch — pass `--branch`, set `NEON_BRANCH_ID`, or add `branchId` to `.neon/project.json` (run `npx neonctl checkout <branch>`).",
-		);
-	}
-	if (!projectId || !branchId) return { ok: false, missing };
-
-	return {
-		ok: true,
-		context: {
-			projectId,
-			branchId,
-			...(branchName ? { branchName } : {}),
-		},
-	};
-}
-
-interface NeonFile {
-	projectId?: string;
-	branchId?: string;
-	branchName?: string;
-}
-
-/**
- * Walk up from `cwd` looking for `.neon/project.json` (preferred) or `.neon` (neonctl
- * convention). Stops at the first `.git` directory or the home directory. Read-only.
- */
-function findNeonFile(cwd: string): NeonFile | null {
-	let current = resolve(cwd);
-	const stop = resolve(homedir());
-	let lastSeen: string | null = null;
-
-	while (true) {
-		const parsed =
-			readNeonFileAt(resolve(current, ".neon", "project.json")) ??
-			readNeonFileAt(resolve(current, ".neon"));
-		if (parsed) return parsed;
-
-		if (current === stop) return null;
-		if (existsSync(resolve(current, ".git"))) return null;
-
-		const parent = dirname(current);
-		if (parent === current || parent === lastSeen) return null;
-		lastSeen = current;
-		current = parent;
-	}
-}
-
-function readNeonFileAt(path: string): NeonFile | null {
-	if (!isFile(path)) return null;
-	let raw: string;
-	try {
-		raw = readFileSync(path, "utf-8");
-	} catch {
-		return null;
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-		return null;
-	const obj = parsed as Record<string, unknown>;
-	const out: NeonFile = {};
-	if (typeof obj.projectId === "string" && obj.projectId !== "")
-		out.projectId = obj.projectId;
-	if (typeof obj.branchId === "string" && obj.branchId !== "")
-		out.branchId = obj.branchId;
-	if (typeof obj.branchName === "string" && obj.branchName !== "")
-		out.branchName = obj.branchName;
-	return out;
-}
-
-function isFile(path: string): boolean {
-	try {
-		return statSync(path).isFile();
-	} catch {
-		return false;
-	}
-}
-
-function nonEmpty(value: string | undefined): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const trimmed = value.trim();
-	return trimmed === "" ? undefined : trimmed;
-}