neon 6.1.0 → 6.2.1

package/dist/utils/git.js

@@ -0,0 +1,220 @@
+import { log } from "../log.js";
+import { neonSafeBranchName } from "./branch_name.js";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/utils/git.ts
+/**
+* Env var the installed `post-checkout` hook sets before invoking `neon git sync`, so the
+* CLI can tell a hook-triggered run from a manual `neon checkout` / `deploy`. Read by
+* {@link buildCheckoutEvent} to construct the hook contexts' `event` field (see
+* `CheckoutEvent` in `@neon/config`) — not carried on {@link GitContext} itself.
+*/
+const GIT_HOOK_ENV_FLAG = "NEON_GIT_HOOK";
+/** Sentinel marking the `post-checkout` hook as neon-managed (safe to update/remove). */
+const HOOK_SENTINEL = "# neon:git-sync (managed — edit `neon git` instead)";
+const POST_CHECKOUT_HOOK = `#!/usr/bin/env sh
+${HOOK_SENTINEL}
+# Syncs the Neon branch to the checked-out git branch. Runs only on branch switches
+# ($3 == 1), never blocks the checkout, and no-ops when neon isn't on PATH.
+[ "$3" = "1" ] || exit 0
+command -v neon >/dev/null 2>&1 || exit 0
+${GIT_HOOK_ENV_FLAG}=1 neon git sync --quiet || true
+`;
+/** Run a git command, returning trimmed stdout, or `undefined` on any failure. */
+const git = (args, cwd) => {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return;
+	}
+};
+/** Whether `cwd` is inside a git work tree. */
+const isGitRepo = (cwd) => git(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
+/** Absolute path to the repository root (`git rev-parse --show-toplevel`), if any. */
+const gitRepoRoot = (cwd) => git(["rev-parse", "--show-toplevel"], cwd);
+/** The current branch name, or `undefined` in detached-HEAD state / outside a repo. */
+const currentGitBranch = (cwd) => {
+	const branch = git([
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"HEAD"
+	], cwd);
+	return branch && branch.length > 0 ? branch : void 0;
+};
+/** All local branch names (`refs/heads`). Empty outside a repo or with no branches. */
+const localGitBranches = (cwd) => {
+	const out = git([
+		"for-each-ref",
+		"--format=%(refname:short)",
+		"refs/heads"
+	], cwd);
+	if (!out) return [];
+	return out.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+};
+/** Whether the current branch has a configured upstream (`@{u}`) to pull from. */
+const hasUpstream = (cwd) => git([
+	"rev-parse",
+	"--abbrev-ref",
+	"--symbolic-full-name",
+	"@{u}"
+], cwd) !== void 0;
+/**
+* Fast-forward the current branch from its upstream (`git pull --ff-only`). Used by
+* `git sync` to bring local files — crucially, committed migration files — up to date with a
+* shared branch *before* a `checkout.after` migration runs, so a branch that is ahead of your
+* local tree doesn't leave code↔schema skewed.
+*
+* `--ff-only` is deliberate: it never creates a merge commit or leaves conflict markers in
+* your tree. If the branch has diverged it fails cleanly (reported, non-fatal) instead of
+* mutating the working tree mid-sync. No-ops (returns `no-upstream`) when there's nothing to
+* pull from.
+*/
+const gitPull = (cwd) => {
+	if (!hasUpstream(cwd)) return { status: "no-upstream" };
+	try {
+		execFileSync("git", ["pull", "--ff-only"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		return { status: "pulled" };
+	} catch (err) {
+		let detail;
+		if (err !== null && typeof err === "object" && "stderr" in err && typeof err.stderr === "string" && err.stderr.trim().length > 0) detail = err.stderr.trim();
+		else detail = err instanceof Error ? err.message : "unknown error";
+		return {
+			status: "failed",
+			detail
+		};
+	}
+};
+/**
+* Read the read-only git facts the hooks receive. Never throws: outside a repo (or with git
+* uninstalled) it returns `{ available: false, … }` with the optional fields absent.
+*
+* @param cwd directory to inspect.
+*/
+const readGitContext = (cwd) => {
+	if (!isGitRepo(cwd)) return {
+		available: false,
+		isDetached: false,
+		isDirty: false
+	};
+	const branch = currentGitBranch(cwd);
+	const sha = git(["rev-parse", "HEAD"], cwd);
+	const shortSha = git([
+		"rev-parse",
+		"--short",
+		"HEAD"
+	], cwd);
+	const status = git(["status", "--porcelain"], cwd);
+	const remoteHead = git([
+		"rev-parse",
+		"--abbrev-ref",
+		"origin/HEAD"
+	], cwd);
+	const defaultBranch = remoteHead?.startsWith("origin/") ? remoteHead.slice(7) : void 0;
+	const remoteUrl = git([
+		"remote",
+		"get-url",
+		"origin"
+	], cwd);
+	const repoRoot = gitRepoRoot(cwd);
+	return {
+		available: true,
+		isDetached: branch === void 0,
+		isDirty: status !== void 0 && status.length > 0,
+		...branch ? {
+			branch,
+			neonSafeBranchName: neonSafeBranchName(branch)
+		} : {},
+		...sha ? { sha } : {},
+		...shortSha ? { shortSha } : {},
+		...defaultBranch ? { defaultBranch } : {},
+		...remoteUrl ? { remoteUrl } : {},
+		...repoRoot ? { repoRoot } : {}
+	};
+};
+/**
+* Construct the `CheckoutEvent` a checkout/create hook context receives: `"git-checkout"`
+* when the installed `post-checkout` hook triggered this run (env flag {@link
+* GIT_HOOK_ENV_FLAG}), carrying the git branch that triggered it — `inputName` is never set
+* on this variant, since nothing was typed at a prompt. `"neon-checkout"` for an explicit
+* `neon checkout` invocation, carrying whatever name/id the user passed (`undefined` for
+* the interactive picker). `git sync` bails out before ever reaching a checkout when `git`
+* is detached/unavailable (see `sync` in `commands/git.ts`), so a defined `git.branch` is
+* expected whenever the env flag is set; falling back to `""` is a defensive guard against
+* that invariant breaking, not an expected runtime path.
+*/
+const buildCheckoutEvent = (git, inputName) => process.env["NEON_GIT_HOOK"] === "1" ? {
+	type: "git-checkout",
+	gitBranch: git.branch ?? ""
+} : {
+	type: "neon-checkout",
+	inputName
+};
+/**
+* Path to the `post-checkout` hook for a repo. Uses `git rev-parse --git-path hooks` so it
+* honors whatever git itself would use — `.git/hooks`, a `core.hooksPath` override (relative
+* or absolute), worktrees, etc. — instead of re-deriving the rules by hand.
+*/
+const postCheckoutHookPath = (repoRoot) => {
+	const hooksDir = git([
+		"rev-parse",
+		"--git-path",
+		"hooks"
+	], repoRoot);
+	const dir = hooksDir ? isAbsolute(hooksDir) ? hooksDir : resolve(repoRoot, hooksDir) : resolve(repoRoot, ".git", "hooks");
+	return resolve(dir, "post-checkout");
+};
+/** Whether a `post-checkout` hook exists and is neon-managed (carries our sentinel). */
+const isManagedHook = (hookPath) => {
+	if (!existsSync(hookPath)) return false;
+	try {
+		return readFileSync(hookPath, "utf-8").includes(HOOK_SENTINEL);
+	} catch {
+		return false;
+	}
+};
+/**
+* Install (or refresh) the neon-managed `post-checkout` hook. Refuses to clobber a
+* pre-existing hook we don't own, returning `{ status: 'conflict' }` so the caller can warn
+* instead of silently overwriting the user's script.
+*/
+const installPostCheckoutHook = (repoRoot) => {
+	const hookPath = postCheckoutHookPath(repoRoot);
+	const existed = existsSync(hookPath);
+	if (existed && !isManagedHook(hookPath)) return {
+		status: "conflict",
+		hookPath
+	};
+	mkdirSync(dirname(hookPath), { recursive: true });
+	writeFileSync(hookPath, POST_CHECKOUT_HOOK);
+	chmodSync(hookPath, 493);
+	return { status: existed ? "updated" : "installed" };
+};
+/** Remove the managed `post-checkout` hook. Leaves a foreign (user-authored) hook untouched. */
+const removePostCheckoutHook = (repoRoot) => {
+	const hookPath = postCheckoutHookPath(repoRoot);
+	if (!existsSync(hookPath)) return "absent";
+	if (!isManagedHook(hookPath)) return "foreign";
+	rmSync(hookPath);
+	log.debug("Removed managed post-checkout hook at %s", hookPath);
+	return "removed";
+};
+//#endregion
+export { GIT_HOOK_ENV_FLAG, buildCheckoutEvent, currentGitBranch, gitPull, gitRepoRoot, hasUpstream, installPostCheckoutHook, isGitRepo, isManagedHook, localGitBranches, postCheckoutHookPath, readGitContext, removePostCheckoutHook };

package/dist/utils/hooks.js

@@ -0,0 +1,230 @@
+import { log } from "../log.js";
+import { s as fetchEnvKeys } from "../_chunks/env-N19A7qND.js";
+import { loadConfigFromFile, runHook } from "@neon/config-runtime";
+//#region src/utils/hooks.ts
+/**
+* Load the nearest `neon.ts` for hook discovery, or `undefined` when there is none — or when
+* it fails to load. Deliberately best-effort: `checkout` on an *existing* branch must keep
+* working even with a broken `neon.ts` sitting in the repo, exactly as it did before hooks
+* existed. A load failure other than "missing" degrades to a warning rather than aborting
+* the checkout; a genuinely broken policy still surfaces loudly the moment something that
+* actually depends on it runs — `checkout --create`'s own `createBranchFromPolicyOnCheckout`,
+* or `deploy`, both load the config again through their own (throwing) path. Callers read
+* `.experimental?.hooks` off the result for the hooks block, and pass the whole thing to
+* {@link resolveHookEnv} so `after` hooks resolve exactly the namespaces the policy declares.
+*/
+const loadHookConfig = async (cwd) => {
+	try {
+		const { config } = await loadConfigFromFile({ cwd });
+		return config;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (!/Could not find a Neon config file/i.test(message)) log.warning("Could not load neon.ts for lifecycle hooks (continuing without them): %s", message);
+		return;
+	}
+};
+/** Stream hook (shell) output through the CLI logger. */
+const onOutput = (chunk) => {
+	const text = chunk.replace(/\n$/, "");
+	if (text.length > 0) log.info("%s", text);
+};
+/**
+* Run the `checkout.before` hook (if any). Returns the rewritten branch name when the hook
+* (function form) returns `{ name }`, else `undefined`. Throws propagate to abort the
+* checkout — that's the documented `before`-hook contract.
+*/
+const runCheckoutBeforeHook = async (args) => {
+	const hook = args.hooks?.checkout?.before;
+	if (!hook) return void 0;
+	return (await runHook(hook, {
+		event: args.event,
+		git: args.git
+	}, {
+		cwd: args.cwd,
+		onOutput
+	}))?.name;
+};
+/**
+* Run the `create.before` hook (if any). Fires only when a new branch is actually about to
+* be created (never for `checkout` selecting an existing one). Throws propagate to abort
+* the create — the checkout that triggered it aborts too.
+*/
+const runCreateBeforeHook = async (args) => {
+	const hook = args.hooks?.create?.before;
+	if (!hook) return;
+	await runHook(hook, {
+		branchName: args.branchName,
+		git: args.git,
+		event: args.event
+	}, {
+		cwd: args.cwd,
+		onOutput
+	});
+};
+/** Run the `deploy.before` hook (if any). Throws propagate to abort the deploy. */
+const runDeployBeforeHook = async (args) => {
+	const hook = args.hooks?.deploy?.before;
+	if (!hook) return;
+	await runHook(hook, {
+		branch: args.branch,
+		git: args.git,
+		event: args.event
+	}, {
+		cwd: args.cwd,
+		onOutput
+	});
+};
+/**
+* Run the `checkout.after` hook (if any). Failures degrade to a warning — the branch is
+* already checked out, so an `after` failure must not unwind the pin.
+*/
+const runCheckoutAfterHook = async (args) => {
+	const hook = args.hooks?.checkout?.after;
+	if (!hook) return;
+	await runAfter("checkout.after", () => runHook(hook, {
+		branch: args.branch,
+		env: args.env,
+		git: args.git,
+		event: args.event
+	}, {
+		cwd: args.cwd,
+		env: hookEnvToProcessEnv(args.env),
+		onOutput
+	}));
+};
+/**
+* Run the `create.after` hook (if any). Failures degrade to a warning — the branch already
+* exists, so an `after` failure must not unwind the create.
+*/
+const runCreateAfterHook = async (args) => {
+	const hook = args.hooks?.create?.after;
+	if (!hook) return;
+	await runAfter("create.after", () => runHook(hook, {
+		branch: args.branch,
+		env: args.env,
+		git: args.git,
+		event: args.event
+	}, {
+		cwd: args.cwd,
+		env: hookEnvToProcessEnv(args.env),
+		onOutput
+	}));
+};
+/** Run the `deploy.after` hook (if any). Failures degrade to a warning (apply already ran). */
+const runDeployAfterHook = async (args) => {
+	const hook = args.hooks?.deploy?.after;
+	if (!hook) return;
+	await runAfter("deploy.after", () => runHook(hook, {
+		branch: args.branch,
+		env: args.env,
+		result: args.result,
+		git: args.git,
+		event: args.event
+	}, {
+		cwd: args.cwd,
+		env: hookEnvToProcessEnv(args.env),
+		onOutput
+	}));
+};
+const runAfter = async (label, run) => {
+	try {
+		await run();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		log.warning("The `%s` hook failed: %s\nThe branch change already succeeded; re-run the hook manually if needed.", label, message);
+	}
+};
+/**
+* Fetch the branch's resolved Neon env (DATABASE_URL, …) for an `after` hook, shaped into
+* {@link HookEnv}. Resolved in-memory regardless of `--env-pull`, so a migration hook always
+* has a connection string even when no `.env` is written. Returns `undefined` on failure so
+* the caller can skip the hook with a warning rather than crash.
+*
+* `config` is the same policy the checkout/deploy is already working from — it decides
+* which namespaces `fetchEnvKeys` resolves (an empty/default `Config` would resolve
+* postgres only, since nothing else is declared enabled).
+*/
+const resolveHookEnv = async (config, options) => {
+	try {
+		const resolved = await fetchEnvKeys(config, options, null);
+		return shapeHookEnv(resolved);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		log.warning("Could not resolve env for the after hook: %s", message);
+		return;
+	}
+};
+/**
+* Map `@neon-internals/env-core`'s flat, all-optional {@link ResolvedNeonEnv} into
+* {@link HookEnv}. Pure — split out from {@link resolveHookEnv} so the shaping is testable
+* without a live Neon API call. `postgres` always defaults to empty strings rather than
+* being dropped: {@link HookEnv.postgres} is the one namespace every hook can rely on
+* existing, even when this particular fetch didn't select either connection string.
+*/
+const shapeHookEnv = (resolved) => ({
+	postgres: {
+		databaseUrl: resolved.postgres?.databaseUrl ?? "",
+		databaseUrlUnpooled: resolved.postgres?.databaseUrlUnpooled ?? ""
+	},
+	...resolved.branch?.name ? { branch: { name: resolved.branch.name } } : {},
+	...resolved.auth?.baseUrl !== void 0 && resolved.auth.jwksUrl !== void 0 ? { auth: {
+		baseUrl: resolved.auth.baseUrl,
+		jwksUrl: resolved.auth.jwksUrl
+	} } : {},
+	...resolved.dataApi?.url !== void 0 ? { dataApi: { url: resolved.dataApi.url } } : {},
+	...resolved.storage?.accessKeyId !== void 0 && resolved.storage.secretAccessKey !== void 0 && resolved.storage.endpoint !== void 0 && resolved.storage.region !== void 0 ? { storage: {
+		accessKeyId: resolved.storage.accessKeyId,
+		secretAccessKey: resolved.storage.secretAccessKey,
+		endpoint: resolved.storage.endpoint,
+		region: resolved.storage.region
+	} } : {},
+	...resolved.aiGateway?.apiKey !== void 0 && resolved.aiGateway.baseUrl !== void 0 ? { aiGateway: {
+		apiKey: resolved.aiGateway.apiKey,
+		baseUrl: resolved.aiGateway.baseUrl
+	} } : {},
+	...resolved.functions ? { functions: Object.fromEntries(Object.entries(resolved.functions).map(([slug, fn]) => [slug, { baseUrl: fn.baseUrl }])) } : {}
+});
+/** Re-derive the OS-level env vars from a {@link HookEnv} for shell-hook injection. */
+const hookEnvToProcessEnv = (env) => {
+	const out = {
+		DATABASE_URL: env.postgres.databaseUrl,
+		DATABASE_URL_UNPOOLED: env.postgres.databaseUrlUnpooled
+	};
+	if (env.branch?.name) out.NEON_BRANCH = env.branch.name;
+	if (env.auth) {
+		out.NEON_AUTH_BASE_URL = env.auth.baseUrl;
+		out.NEON_AUTH_JWKS_URL = env.auth.jwksUrl;
+	}
+	if (env.dataApi) out.NEON_DATA_API_URL = env.dataApi.url;
+	if (env.storage) {
+		out.AWS_ACCESS_KEY_ID = env.storage.accessKeyId;
+		out.AWS_SECRET_ACCESS_KEY = env.storage.secretAccessKey;
+		out.AWS_ENDPOINT_URL_S3 = env.storage.endpoint;
+		out.AWS_REGION = env.storage.region;
+	}
+	if (env.aiGateway) {
+		out.NEON_AI_GATEWAY_TOKEN = env.aiGateway.apiKey;
+		out.NEON_AI_GATEWAY_BASE_URL = env.aiGateway.baseUrl;
+	}
+	return out;
+};
+/**
+* Build a {@link HookBranch} from the live branch metadata. `created` is supplied by the
+* caller (only the checkout/deploy flow knows whether this op created the branch).
+*/
+const buildHookBranch = async (args) => {
+	const { data } = await args.apiClient.getProjectBranch(args.projectId, args.branchId);
+	const branch = data.branch;
+	return {
+		projectId: args.projectId,
+		id: branch.id,
+		name: branch.name,
+		created: args.created,
+		isDefault: branch.default ?? false,
+		isProtected: branch.protected ?? false,
+		...branch.parent_id ? { parentId: branch.parent_id } : {},
+		...branch.expires_at ? { expiresAt: branch.expires_at } : {}
+	};
+};
+//#endregion
+export { buildHookBranch, loadHookConfig, resolveHookEnv, runCheckoutAfterHook, runCheckoutBeforeHook, runCreateAfterHook, runCreateBeforeHook, runDeployAfterHook, runDeployBeforeHook, shapeHookEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "6.1.0",
+  "version": "6.2.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,9 +64,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.6.3",
-    "@neon/config": "1.7.3",
-    "@neon/sdk": "6.1.0"
+    "@neon/config": "1.8.1",
+    "@neon/sdk": "6.1.1",
+    "@neon/config-runtime": "1.7.1"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -99,9 +99,9 @@
     "tsx": "4.22.3",
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
-    "@neon-internals/cli-core": "0.0.0",
-    "@neon-internals/env-core": "0.0.22",
+    "@neon-internals/env-core": "0.0.24",
     "@neon/e2e-harness": "0.0.0",
+    "@neon-internals/cli-core": "0.0.0",
     "@neon/functions": "0.11.0"
   },
   "publishConfig": {