neonctl 2.37.0 → 2.38.0

package/dist/commands/diff.js

@@ -1,222 +0,0 @@
-import chalk from "chalk";
-import { isNeonApiError } from "../api.js";
-import { log } from "../log.js";
-import { fillSingleProject } from "../utils/enrichers.js";
-import { looksLikeBranchId } from "../utils/formats.js";
-import { renderDatabaseSchemaDiff, renderSchemaDiffReport, } from "../utils/git_diff.js";
-import { writer } from "../writer.js";
-// A top-level shortcut for `branches schema-diff`, framed like `git diff`: it
-// compares the branch you're on (pinned in `.neon`, or `--branch`) against the
-// branch you name, and prints a git-style unified schema diff. Because it has a
-// handler but no subcommands, `diff` is also listed in `NO_SUBCOMMANDS_VERBS`
-// (see index.ts) so a bare `neon diff main` isn't intercepted by the help
-// fallback.
-export const command = "diff [compare-branch]";
-export const describe = "Show a git-style schema diff between the current branch and another branch";
-export const builder = (argv) => argv
-    .usage("$0 diff [compare-branch] [options]")
-    .positional("compare-branch", {
-    describe: "Branch name or id to compare against (the reference / '---' side). " +
-        "Defaults to the current branch's parent.",
-    type: "string",
-})
-    .options({
-    "project-id": {
-        describe: "Project ID",
-        type: "string",
-    },
-    branch: {
-        alias: "b",
-        describe: "The branch to review (the '+++' side). Defaults to the branch " +
-            "pinned in the local context (.neon).",
-        type: "string",
-    },
-    database: {
-        alias: "db",
-        describe: "Limit the diff to a single database. Defaults to every database on the current branch.",
-        type: "string",
-    },
-})
-    .middleware(fillSingleProject)
-    .middleware((args) => {
-    // The positional arrives as `compare-branch`; surface it under the
-    // camelCase name the handler reads, and mirror it to `branchId` for
-    // analytics (same pattern as the `branches` command group).
-    const compareBranch = args["compare-branch"];
-    if (typeof compareBranch === "string") {
-        args.compareBranch = compareBranch;
-    }
-})
-    .example([
-    [
-        "$0 diff main",
-        "Diff the current branch's schema against the main branch",
-    ],
-    [
-        "$0 diff",
-        "Diff the current branch's schema against its parent branch",
-    ],
-    [
-        "$0 diff main --branch feature/checkout",
-        "Diff an explicit branch against main (ignoring the .neon context)",
-    ],
-    [
-        "$0 diff main --db neondb",
-        "Diff only the neondb database against main",
-    ],
-]);
-export const handler = async (props) => {
-    const branches = (await props.apiClient.listProjectBranches({
-        projectId: props.projectId,
-    })).data.branches;
-    const after = resolveAfterBranch(branches, props.branch);
-    const before = resolveBeforeBranch(branches, after, props.compareBranch);
-    if (before.branchId === after.branchId) {
-        throw new Error(`Nothing to compare: both sides resolve to branch ${after.branchName} (${after.branchId}).`);
-    }
-    const databases = await resolveDatabases(props, after);
-    const diffs = [];
-    for (const database of databases) {
-        const [beforeSql, afterSql] = await Promise.all([
-            fetchSchemaSql(props, before.branchId, database),
-            fetchSchemaSql(props, after.branchId, database),
-        ]);
-        diffs.push({
-            database,
-            before: { ...before, sql: beforeSql },
-            after: { ...after, sql: afterSql },
-        });
-    }
-    if (props.output === "json" || props.output === "yaml") {
-        writeStructured(props, diffs);
-        return;
-    }
-    log.info("%s Comparing schema %s → %s", chalk.dim("→"), chalk.red(`${before.branchName}`), chalk.green(`${after.branchName}`));
-    const { hasChanges, text } = renderSchemaDiffReport(diffs, {
-        color: props.color !== false,
-    });
-    if (!hasChanges) {
-        log.info("No schema differences between %s and %s.", before.branchName, after.branchName);
-        return;
-    }
-    writer(props).text(`${text}\n`);
-};
-/**
- * Resolve the branch under review (`+++` side). Prefers the explicit
- * `branch`/`--branch` value (name or `br-…` id), falling back to the project's
- * default branch. An unknown `br-…` id is trusted as-is (it may be too new to
- * appear in the listing); an unknown *name* is a hard error.
- */
-const resolveAfterBranch = (branches, ref) => {
-    if (ref) {
-        return resolveRef(branches, ref);
-    }
-    const def = branches.find((b) => b.default);
-    if (!def) {
-        throw new Error("No branch specified and no default branch found. Pass --branch <name|id>.");
-    }
-    return { branchId: def.id, branchName: def.name ?? def.id };
-};
-/**
- * Resolve the reference branch (`---` side). Uses the `compare-branch`
- * positional when given, otherwise the parent of the branch under review — so a
- * bare `neon diff` answers "what did I change since branching?".
- */
-const resolveBeforeBranch = (branches, after, ref) => {
-    if (ref) {
-        return resolveRef(branches, ref);
-    }
-    const afterBranch = branches.find((b) => b.id === after.branchId);
-    const parentId = afterBranch?.parent_id;
-    if (!parentId) {
-        throw new Error(`Branch "${after.branchName}" has no parent to compare against. ` +
-            "Pass a branch to compare with, e.g. `neon diff main`.");
-    }
-    const parent = branches.find((b) => b.id === parentId);
-    return {
-        branchId: parentId,
-        branchName: parent?.name ?? parentId,
-    };
-};
-/** Resolve a branch reference (name or `br-…` id) against the fetched listing. */
-const resolveRef = (branches, ref) => {
-    const found = looksLikeBranchId(ref)
-        ? branches.find((b) => b.id === ref)
-        : branches.find((b) => b.name === ref);
-    if (found) {
-        return { branchId: found.id, branchName: found.name ?? found.id };
-    }
-    // A `br-…` id absent from the listing is still usable as an id; only an
-    // unresolved name is a genuine error (mirrors resolveBranchRef in enrichers).
-    if (looksLikeBranchId(ref)) {
-        return { branchId: ref, branchName: ref };
-    }
-    throw new Error(`Branch ${ref} not found.\nAvailable branches: ${branches
-        .map((b) => b.name)
-        .join(", ")}`);
-};
-/**
- * The databases to diff: the one passed via `--database` (validated against the
- * branch under review), or every database on that branch when none is given.
- */
-const resolveDatabases = async (props, after) => {
-    const databases = (await props.apiClient.listProjectBranchDatabases(props.projectId, after.branchId)).data.databases;
-    if (props.database !== undefined) {
-        if (!databases.find((d) => d.name === props.database)) {
-            throw new Error(`Database "${props.database}" not found on branch ${after.branchName}. ` +
-                `Available: ${databases.map((d) => d.name).join(", ")}`);
-        }
-        return [props.database];
-    }
-    if (databases.length === 0) {
-        throw new Error(`No databases found on branch ${after.branchName} (${after.branchId}).`);
-    }
-    return databases.map((d) => d.name);
-};
-/**
- * Fetch a branch database's `CREATE …` SQL. A database absent from the branch
- * (404) yields an empty schema, so the diff shows it as fully added/removed
- * rather than failing — the natural outcome when a database exists on only one
- * side of the comparison.
- */
-const fetchSchemaSql = async (props, branchId, database) => {
-    try {
-        const { data } = await props.apiClient.getProjectBranchSchema({
-            projectId: props.projectId,
-            branchId,
-            db_name: database,
-        });
-        return data.sql ?? "";
-    }
-    catch (err) {
-        if (isNeonApiError(err) && err.status === 404) {
-            log.debug("diff: database %s not found on branch %s; treating schema as empty", database, branchId);
-            return "";
-        }
-        throw err;
-    }
-};
-/** Machine-readable output for `--output json|yaml`: one entry per database. */
-const writeStructured = (props, diffs) => {
-    const report = diffs.map((diff) => {
-        const rendered = renderDatabaseSchemaDiff(diff, { color: false });
-        return {
-            database: diff.database,
-            base_branch: diff.before.branchName,
-            base_branch_id: diff.before.branchId,
-            compare_branch: diff.after.branchName,
-            compare_branch_id: diff.after.branchId,
-            has_changes: rendered.hasChanges,
-            diff: rendered.text,
-        };
-    });
-    writer(props).end(report, {
-        fields: [
-            "database",
-            "base_branch",
-            "compare_branch",
-            "has_changes",
-            "diff",
-        ],
-    });
-};

package/dist/commands/env.js

@@ -1,189 +0,0 @@
-import { existsSync } from "node:fs";
-import { NEON_ENV_VAR_KEYS } from "@neon/env";
-import chalk from "chalk";
-import { ensureGitignored } from "../context.js";
-import { resolveNeonEnvVars } from "../dev/env.js";
-import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
-import { log } from "../log.js";
-import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { announceTargetBranch } from "../utils/branch_notice.js";
-import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
-export const command = "env";
-export const describe = "Manage a branch's Neon env variables locally";
-/**
- * Shown (to stderr) when `link` / `checkout` skip the bundled env pull because the user passed
- * `--no-env-pull`. Names the two ways to get the branch's vars without an on-disk file written
- * eagerly: an explicit `neonctl env pull`, or runtime injection via `neon-env run`.
- */
-export const ENV_PULL_SKIPPED_HINT = "Skipped env pull (--no-env-pull). Run `neonctl env pull` to write this branch’s env vars " +
-    "(DATABASE_URL, …) into a local .env, or inject them at runtime with `neon-env run -- <your dev command>`.";
-export const builder = (argv) => argv
-    .usage("$0 env <sub-command> [options]")
-    .options({
-    "project-id": { describe: "Project ID", type: "string" },
-    branch: { describe: "Branch ID or name", type: "string" },
-})
-    .middleware(fillSingleProject)
-    .command("pull", "Write the branch's Neon env variables to a local .env file", (yargs) => yargs
-    .usage("$0 env pull [options]")
-    .options({
-    file: {
-        describe: "Target .env file to write. Defaults to an existing .env, " +
-            "otherwise .env.local. Only Neon variables are updated; other " +
-            "lines are preserved.",
-        type: "string",
-    },
-})
-    .example("$0 env pull", "Write the linked branch's Neon vars into .env.local (or .env if present)")
-    .example("$0 env pull --branch preview --file .env.preview", "Pull a specific branch into a specific file"), async (args) => {
-    // Explicit `env pull` announces the branch it's reading from up front so the user
-    // can catch "pulled env from the wrong branch" before it overwrites their .env. The
-    // bundled auto-pull (link / checkout / apply) stays quiet — those already report the
-    // branch they pinned/applied to.
-    await pull(args, { announce: true });
-})
-    .demandCommand(1);
-export const handler = (args) => args;
-/** Every OS-level env var name `@neon/env` can emit, used only for reporting. */
-const NEON_VAR_NAMES = Object.values(NEON_ENV_VAR_KEYS).flatMap((group) => Object.values(group));
-/**
- * The Neon env vars `env pull` *owns*, so it removes any that the branch no longer has when
- * it reconciles the local `.env` (see {@link pull}). Scoped to the unambiguously Neon-named
- * vars — the `NEON_*` aliases plus `DATABASE_URL[_UNPOOLED]` — so switching a working
- * directory to a project/branch without Auth / the Data API drops the now-stale
- * `NEON_AUTH_*` / `NEON_DATA_API_*` lines instead of leaving credentials for features that
- * aren't enabled.
- *
- * Deliberately **excludes** the storage vars Neon projects onto third-party SDK names
- * (`AWS_*`): those collide with credentials a user may set by hand, so `env pull` only ever
- * writes them, never prunes them. The AI Gateway is emitted solely under its Neon-branded
- * vars (`NEON_AI_GATEWAY_*`), which are owned and pruned.
- */
-const NEON_OWNED_ENV_KEYS = [
-    ...Object.values(NEON_ENV_VAR_KEYS.postgres),
-    ...Object.values(NEON_ENV_VAR_KEYS.auth),
-    ...Object.values(NEON_ENV_VAR_KEYS.dataApi),
-    ...Object.values(NEON_ENV_VAR_KEYS.aiGateway),
-];
-export const pull = async (props, opts = {}) => {
-    const cwd = props.cwd ?? process.cwd();
-    const branch = await resolveBranchRef(props);
-    if (opts.announce) {
-        announceTargetBranch(props, branch, "Pulling env from branch");
-    }
-    const branchId = branch.branchId;
-    // Resolve the target file first and layer its current contents under the resolver's env
-    // source. This lets `fetchEnv` reuse one-time secrets that are already on disk — Neon Auth
-    // keys and the unified branch credential's `api_token` / `s3_secret_access_key`, which the
-    // API returns exactly once — instead of minting a fresh credential on every pull.
-    const targetPath = resolveEnvFilePath(cwd, props.file);
-    const fileExisted = existsSync(targetPath);
-    const existingEnv = fileExisted ? readEnvFile(targetPath) : {};
-    // Reuse `neon dev`'s tiered resolver (neon.ts policy -> plan gate -> fetchEnv, else
-    // pullConfig -> fetchEnv). Unlike dev, an unresolved context or failure is surfaced —
-    // `env pull` is an explicit action, so it should error rather than write nothing.
-    const vars = await resolveNeonEnvVars({
-        cwd,
-        projectId: props.projectId,
-        branchId,
-        env: { ...process.env, ...existingEnv },
-        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
-    });
-    const neonVars = pickNeonVars(vars);
-    if (Object.keys(neonVars).length === 0) {
-        log.info("No Neon env variables to pull for this branch (no DATABASE_URL or " +
-            "enabled Auth / Data API).");
-        return { status: "empty" };
-    }
-    // Reconcile rather than blindly merge: write the branch's current Neon vars and prune any
-    // Neon-owned vars the branch no longer has (e.g. NEON_AUTH_* / NEON_DATA_API_* carried over
-    // from a previous project/branch). Non-Neon lines are always preserved.
-    const { written, removed } = mergeEnvFile(targetPath, neonVars, {
-        managedKeys: NEON_OWNED_ENV_KEYS,
-    });
-    log.info("Pulled %d Neon variable%s into %s: %s", written.length, written.length === 1 ? "" : "s", targetPath, written.join(", "));
-    if (removed.length > 0) {
-        log.info("Removed %d stale Neon variable%s not enabled on this branch: %s", removed.length, removed.length === 1 ? "" : "s", removed.join(", "));
-    }
-    // A dotenv file *we* create holds live branch credentials (DATABASE_URL, Auth keys, service
-    // tokens), so ignore it the same way the `.neon` context file is — otherwise a fresh repo is
-    // one `git add -A` away from committing them. Only on creation: re-adding the entry on every
-    // pull would fight a user who deliberately un-ignored a file they want to commit.
-    if (!fileExisted) {
-        ensureGitignored(targetPath);
-    }
-    // When the branch has the AI Gateway enabled, the pulled credentials always work, but
-    // serving is plan-gated and the model set can be reduced on the beta — surface that as a
-    // courtesy notice (best-effort; never fails the pull). The freshly pulled token lets us
-    // probe the branch's own /v1/models to detect a reduced catalog.
-    const gatewayBaseUrl = neonVars.NEON_AI_GATEWAY_BASE_URL;
-    const gatewayToken = neonVars.NEON_AI_GATEWAY_TOKEN;
-    if (gatewayBaseUrl && gatewayToken) {
-        await warnAiGateway({
-            apiClient: props.apiClient,
-            projectId: props.projectId,
-            branchId,
-            gateway: { baseUrl: gatewayBaseUrl, token: gatewayToken },
-        });
-    }
-    return { status: "written", written, file: targetPath };
-};
-/**
- * Pull a freshly-pinned branch's Neon env vars into a local `.env`, bundled into `link` and
- * `checkout` so the branch-first loop is just *link + checkout* — `env pull` runs for you.
- *
- * On by default; `--no-env-pull` opts out (e.g. when env is injected at runtime via
- * `neon-env run` / `neon dev`, or to keep secrets out of the working tree). The pin is the
- * command's primary effect and has already succeeded by the time this runs, so a pull failure
- * degrades to a warning rather than failing the command. Returns what happened so
- * `link --agent` can fold an accurate note into its JSON message.
- */
-export const autoPullEnvAfterPin = async (props) => {
-    if (!props.envPull) {
-        log.info(chalk.dim(ENV_PULL_SKIPPED_HINT));
-        return { status: "skipped" };
-    }
-    try {
-        return await pull(props);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        log.warning("Branch pinned, but pulling its Neon env vars failed: %s\n" +
-            "Run `neonctl env pull` once resolved (e.g. `neonctl deploy` if a declared service " +
-            "is missing), or inject them at runtime with `neon-env run -- <your dev command>`.", message);
-        return { status: "failed", message };
-    }
-};
-/**
- * Render the one-line env-pull note appended to `link --agent`'s JSON `message`, so an agent
- * reading the structured output knows whether its branch env is already on disk.
- */
-export const renderAgentPullNote = (result) => {
-    switch (result.status) {
-        case "written":
-            return ` Pulled ${result.written.length} Neon env var${result.written.length === 1 ? "" : "s"} into ${result.file}.`;
-        case "empty":
-            return " No Neon env vars to pull for this branch yet.";
-        case "skipped":
-            return (" Skipped env pull (--no-env-pull); run `neonctl env pull` later, " +
-                "or inject env at runtime with `neon-env run -- <your dev command>`.");
-        case "failed":
-            return ` Could not pull env vars (${result.message}); run \`neonctl env pull\` once resolved.`;
-    }
-};
-/**
- * Keep only the recognized Neon variables from the resolved set, so a stray inherited
- * value never lands in the user's `.env` file. (Today `resolveNeonEnvVars` only emits Neon
- * vars, but filtering keeps the contract explicit and future-proof.)
- */
-const pickNeonVars = (vars) => {
-    const out = {};
-    for (const name of NEON_VAR_NAMES) {
-        const value = vars[name];
-        if (value !== undefined)
-            out[name] = value;
-    }
-    return out;
-};