neonctl 2.37.1 → 2.38.1

package/dist/dev/env.js

@@ -1,244 +0,0 @@
-import { loadConfigFromFile } from "@neon/config";
-import { plan, pullConfig } from "@neon/config-runtime";
-import { fetchEnv, toEntries } from "@neon/env";
-import { log } from "../log.js";
-/** The API-targeting options every runtime call forwards from the context. */
-const apiOptions = (ctx) => ({
-    ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
-    ...(ctx.apiHost ? { apiHost: ctx.apiHost } : {}),
-    ...(ctx.api ? { api: ctx.api } : {}),
-});
-/**
- * Thrown when a `neon.ts` policy declares a branch-level resource (Neon Auth,
- * Data API, a bucket, the AI Gateway) that the linked remote branch does not
- * have yet. Unlike every other failure in {@link resolveDevEnv} — which degrades
- * to "run without injection" — this is a hard stop: the user's intent (a policy)
- * cannot be honored, and silently dropping the secret would be more confusing
- * than refusing to start. The fix is to provision the resource first.
- */
-export class DevEnvMismatchError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "DevEnvMismatchError";
-    }
-}
-/**
- * Signals that no project/branch context could be resolved, so there is nothing to
- * resolve env from. `resolveDevEnv` degrades on this (dev runs without injection);
- * `env pull` surfaces it (an explicit pull needs a branch).
- */
-export class MissingBranchContextError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "MissingBranchContextError";
-    }
-}
-/**
- * Resolve the branch's Neon env vars (pooled / direct `DATABASE_URL`, plus Auth /
- * Data API when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
- * injects them) and `neon env pull` (which writes them to a `.env` file).
- *
- * Tiered:
- *
- *   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
- *      check it against the branch's live state (`plan`); if it declares a resource
- *      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
- *      `neonctl deploy`. Otherwise `fetchEnv` evaluates the policy.
- *   2. no `neon.ts`, but a project + branch are known -> `pullConfig` reads the
- *      branch's live state (Auth / Data API enablement plus any object-storage
- *      buckets) into a config, then `fetchEnv` resolves what is actually enabled —
- *      so a branch with a bucket gets its `AWS_*` storage vars pulled with no policy.
- *   3. otherwise -> throw {@link MissingBranchContextError}.
- *
- * Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
- * handle them.
- */
-export const resolveNeonEnvVars = async (ctx) => {
-    const config = await loadNeonConfig(ctx.cwd);
-    if (config) {
-        if (!ctx.projectId || !ctx.branchId) {
-            throw new MissingBranchContextError("Found a neon.ts but could not resolve the project/branch. " +
-                "Run `neonctl link` and `neonctl checkout <branch>`, or pass " +
-                "--project-id / --branch.");
-        }
-        // Resolve env from the policy with its `preview.functions` removed. Functions carry no
-        // branch-level secrets — their env comes from the local `neon.ts` `functions.<slug>.env`,
-        // layered per-function by the dev server — so env resolution never needs the functions
-        // API. Probing it (via `plan`/`fetchEnv`) only adds a failure mode: an undeployed
-        // function, or a project where the Functions Preview isn't enabled, would error and sink
-        // ALL injection (including DATABASE_URL). Stripping functions keeps env resolution honest
-        // while leaving buckets / AI Gateway / Auth / Data API fully checked — those DO carry
-        // secrets, so a declared-but-missing one still hard-stops (see assertPolicyMatchesBranch).
-        const envConfig = withoutPreviewFunctions(config);
-        await assertPolicyMatchesBranch(envConfig, ctx);
-        return await fetchAndProject(envConfig, ctx);
-    }
-    if (ctx.projectId && ctx.branchId) {
-        const pulled = await pullConfig({
-            projectId: ctx.projectId,
-            branchId: ctx.branchId,
-            ...apiOptions(ctx),
-        });
-        // `pulled.config` is already a `Config` (static auth/dataApi toggles, any
-        // object-storage `preview.buckets`, and a branch tuning closure), so it feeds
-        // straight into fetchEnv — no wrapping needed. pullConfig excludes functions and
-        // the AI Gateway (neither can be faithfully read back), so fetchEnv never probes
-        // the functions API here and only mints a storage credential when a bucket exists.
-        return await fetchAndProject(pulled.config, ctx);
-    }
-    throw new MissingBranchContextError("No project/branch context found. Link a branch (`neonctl link` / " +
-        "`neonctl checkout`) or pass --project-id and --branch.");
-};
-/**
- * `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
- *
- * - Success → `{ vars }` (possibly just the always-present Postgres URLs).
- * - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
- *   function still runs locally, just without Neon env.
- * - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
- *   cause; again non-fatal.
- * - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
- *   is the one hard stop and is re-thrown for the caller to surface.
- */
-export const resolveDevEnv = async (ctx) => {
-    try {
-        return { vars: await resolveNeonEnvVars(ctx) };
-    }
-    catch (err) {
-        if (err instanceof DevEnvMismatchError)
-            throw err;
-        if (err instanceof MissingBranchContextError) {
-            log.debug("dev: %s; skipping env injection", err.message);
-            return {
-                vars: {},
-                skipped: {
-                    reason: "no linked Neon branch — run `neonctl link`, then " +
-                        "`neonctl checkout <branch>`, to inject DATABASE_URL and friends",
-                },
-            };
-        }
-        const detail = err instanceof Error ? err.message : String(err);
-        log.debug("dev: env resolution failed: %s", detail);
-        return {
-            vars: {},
-            skipped: {
-                reason: `could not reach Neon (${detail}); running without Neon env`,
-            },
-        };
-    }
-};
-/**
- * Return the policy with its `preview.functions` removed, so the env path never enumerates
- * functions against the Neon API. Functions are local-source-bundled and produce no
- * branch-level secrets, so they are irrelevant to env resolution; probing them only risks
- * failing the whole resolve (undeployed function, or Functions Preview disabled on the
- * project). Buckets / AI Gateway and the top-level Auth / Data API toggles are preserved —
- * they DO carry env, so they must still be checked and resolved. Returns the config
- * unchanged when it declares no functions.
- */
-const withoutPreviewFunctions = (config) => {
-    const preview = config.preview;
-    if (!preview?.functions)
-        return config;
-    const previewWithoutFunctions = { ...preview };
-    delete previewWithoutFunctions.functions;
-    return { ...config, preview: previewWithoutFunctions };
-};
-/**
- * Tier-1 guard. Dry-run the policy against the branch's live state and stop if
- * it declares a branch-level resource the branch is missing. Built on `plan` so
- * it covers every present and future provisionable resource for free: any
- * `create` action is a resource `neonctl deploy` would provision.
- *
- * Called with functions already stripped (see {@link withoutPreviewFunctions}), so the
- * `plan` probe never enumerates the functions API — an undeployed function, or a project
- * without the Functions Preview, must never block local dev or sink env injection.
- */
-const assertPolicyMatchesBranch = async (config, ctx) => {
-    const result = await plan(config, {
-        projectId: ctx.projectId,
-        branchId: ctx.branchId,
-        ...apiOptions(ctx),
-    });
-    const missing = result.applied.filter(isMissingResource);
-    if (missing.length === 0)
-        return;
-    const names = missing.map((change) => change.identifier).join(", ");
-    throw new DevEnvMismatchError(`Your neon.ts declares ${names} for branch ${ctx.branchId}, but the branch ` +
-        "does not have it yet, so the matching env vars cannot be injected. " +
-        "Provision it first with `neonctl deploy` (or `neonctl config apply`), " +
-        "then re-run `neonctl dev`.");
-};
-/**
- * A planned change that provisions a branch-level resource the branch lacks: a
- * `create` on a service (Neon Auth, Data API, a bucket, the AI Gateway). Branch
- * setting drift (`update`) and `noop`s are ignored — they don't block local dev
- * — and functions are excluded (see {@link assertPolicyMatchesBranch}).
- */
-const isMissingResource = (change) => change.kind === "service" &&
-    change.action === "create" &&
-    !change.identifier.startsWith("function:");
-const fetchAndProject = async (config, ctx) => {
-    const env = await fetchEnv(config, {
-        projectId: ctx.projectId,
-        branch: ctx.branchId,
-        ...apiOptions(ctx),
-        ...(ctx.env ? { env: ctx.env } : {}),
-    });
-    return toEntries(env);
-};
-/**
- * Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo
- * root. Returns `null` when there is none (the common "no config" case), and
- * surfaces real load errors (e.g. a syntax error in an existing file).
- */
-/**
- * Substrings that mark a module-resolution failure while loading `neon.ts` —
- * almost always because the project's dependencies aren't installed yet (the
- * config imports `@neon/config` & friends). Deliberately specific:
- * the generic "…or a missing dependency…" hint the loader always appends is
- * NOT in here, so a real syntax/runtime error doesn't get mislabeled.
- */
-const MISSING_DEPENDENCY_HINTS = [
-    "cannot find module",
-    "cannot find package",
-    "err_module_not_found",
-    "failed to resolve",
-    "could not resolve",
-    "module not found",
-];
-/** Flatten an error and its `cause` chain to one lowercased string for matching. */
-const errorChainText = (err) => {
-    const parts = [];
-    let current = err;
-    for (let depth = 0; current instanceof Error && depth < 6; depth++) {
-        parts.push(current.message);
-        current = current.cause;
-    }
-    return parts.join("\n").toLowerCase();
-};
-const looksLikeMissingDependency = (err) => {
-    const text = errorChainText(err);
-    return MISSING_DEPENDENCY_HINTS.some((hint) => text.includes(hint));
-};
-const loadNeonConfig = 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)) {
-            return null;
-        }
-        // A neon.ts that imports a package which isn't installed fails here with a
-        // cryptic "Cannot find module …". Turn that into the actionable thing to do.
-        if (looksLikeMissingDependency(err)) {
-            throw new Error("Could not load neon.ts: a package it imports is not installed. " +
-                "Did you run `npm install`? Install your dependencies " +
-                "(npm / pnpm / yarn / bun), then try again.\n" +
-                `Original error: ${message}`);
-        }
-        throw err;
-    }
-};

package/dist/dev/functions.js

@@ -1,70 +0,0 @@
-import { existsSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
-import { loadConfigFromFile, resolveConfig, } from "@neon/config";
-/**
- * Load `neon.ts` (if any) and resolve the list of functions it declares into
- * {@link PlannedFunction}s for `neon dev` to serve. Returns `null` when there is no
- * `neon.ts` on the path from `cwd` up to the repo root — the caller turns that into a
- * "no --source and no neon.ts" error.
- *
- * `branchName` is used only to evaluate a policy that switches on `branch.name`; the
- * function list is otherwise branch-independent, so a placeholder is fine when unknown.
- */
-export const resolveFunctionsFromConfig = async (cwd, branchName) => {
-    const loaded = await loadNeonConfig(cwd);
-    if (!loaded)
-        return null;
-    const { config, configDir, configPath } = loaded;
-    const resolved = resolveConfig(config, {
-        name: branchName ?? "local",
-        exists: branchName !== undefined,
-    });
-    const functions = resolved.preview?.functions ?? [];
-    const planned = functions.map((fn) => {
-        const source = isAbsolute(fn.source)
-            ? fn.source
-            : resolve(configDir, fn.source);
-        if (!existsSync(source)) {
-            throw new Error(`Function "${fn.slug}" points at a source that does not exist: ${source} ` +
-                `(from neon.ts "${fn.source}"). Fix the source path and re-run.`);
-        }
-        return {
-            slug: fn.slug,
-            name: fn.name,
-            source,
-            ...(devPort(fn.dev) !== undefined
-                ? { port: devPort(fn.dev) }
-                : {}),
-            env: { ...fn.env },
-        };
-    });
-    return { configPath, functions: planned };
-};
-/**
- * Read the `port` off a {@link FunctionDevConfig}. `undefined` when no `dev.port` is set
- * (the supervisor then searches for a free port).
- */
-const devPort = (dev) => dev?.port;
-/**
- * Load a `neon.ts` policy if one exists, returning the loaded config, the resolved path to
- * the config file (used by the dev server to watch it), and the directory it lives in (used
- * to resolve each function's relative `source`). Returns `null` when no config file is
- * found; surfaces real load errors (e.g. a syntax error).
- */
-const loadNeonConfig = async (cwd) => {
-    try {
-        const { config, resolvedPath } = await loadConfigFromFile({ cwd });
-        return {
-            config,
-            configDir: dirname(resolvedPath),
-            configPath: resolvedPath,
-        };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (/Could not find a Neon config file/i.test(message)) {
-            return null;
-        }
-        throw err;
-    }
-};

package/dist/dev/inputs.js

@@ -1,63 +0,0 @@
-import { resolve } from "node:path";
-const defaultDeps = {
-    isPackaged: () => process.pkg !== undefined,
-    loadEsbuild: (name) => import(name),
-};
-/**
- * Resolve the exact set of files esbuild reads to produce the bundle for
- * `source` — the entry plus every local module it imports (npm deps are left
- * external, so they never appear). These are the files the dev watcher should
- * watch, so a single edit triggers exactly one rebuild.
- *
- * Returns absolute paths, or `null` when the precise set cannot be computed —
- * either inside the packaged binary (which cannot import esbuild as a module;
- * it shells out to a binary that has no JSON-metafile equivalent here) or on a
- * platform where the esbuild module won't load. Callers fall back to a coarser
- * watch in that case.
- *
- * This performs a metafile-only pass (`write:false`, `metafile:true`) so it
- * never emits output; the actual bundle bytes still come from `bundleEntry`.
- */
-export const resolveWatchInputs = async (source, deps = defaultDeps) => {
-    if (deps.isPackaged())
-        return null;
-    // esbuild is resolved by a COMPUTED specifier, never the literal string
-    // 'esbuild', for the same reason as src/utils/esbuild.ts: rollup and
-    // @yao-pkg/pkg statically scan for literal import()/require() and would pull
-    // esbuild's native Go binary into the bundle/snapshot. Keep it invisible.
-    const name = ["es", "build"].join("");
-    let esbuild;
-    try {
-        esbuild = await deps.loadEsbuild(name);
-    }
-    catch {
-        return null;
-    }
-    let metafile;
-    try {
-        // Mirrors bundleEntry's flags so the resolved input graph matches the real
-        // bundle. metafile:true + write:false makes this a pure analysis pass.
-        const result = await esbuild.build({
-            entryPoints: [source],
-            bundle: true,
-            write: false,
-            metafile: true,
-            format: "esm",
-            platform: "node",
-            packages: "external",
-            logLevel: "silent",
-        });
-        metafile = result.metafile;
-    }
-    catch {
-        // A bundle error here is non-fatal for watching: bundleEntry surfaces the
-        // real diagnostic. Fall back to the coarser watch so edits still rebuild.
-        return null;
-    }
-    const inputs = metafile?.inputs;
-    if (!inputs)
-        return null;
-    // metafile input keys are paths relative to esbuild's cwd; resolve to absolute
-    // so they compare cleanly against chokidar's watched paths.
-    return Object.keys(inputs).map((p) => resolve(process.cwd(), p));
-};

package/dist/dev/runtime.js

@@ -1,146 +0,0 @@
-import { createServer } from "node:http";
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { getRequestListener } from "@hono/node-server";
-const isFunction = (value) => typeof value === "function";
-const hasFetchMethod = (value) => typeof value === "object" &&
-    value !== null &&
-    "fetch" in value &&
-    typeof value.fetch === "function";
-/**
- * Resolve the user's exported handler to a single fetch callback.
- *
- * Resolution order (first match wins):
- *   1. `export default { fetch }`      — Workers / Neon Functions style
- *   2. `export default function (req)` — bare (async) default function
- */
-export const resolveFetchHandler = (mod) => {
-    const defaultExport = mod.default;
-    if (hasFetchMethod(defaultExport)) {
-        const target = defaultExport;
-        return (req) => target.fetch(req);
-    }
-    if (isFunction(defaultExport)) {
-        return defaultExport;
-    }
-    throw new Error("No request handler found in the source module. Export one of:\n" +
-        "  export default { fetch(req) { /* ... */ } }\n" +
-        "  export default function (req) { /* ... */ }");
-};
-/**
- * Wrap a fetch handler so user errors become a 500 response (with the message
- * in the body during dev) instead of crashing the child process.
- */
-export const withErrorBoundary = (handler) => {
-    return async (req) => {
-        try {
-            return await handler(req);
-        }
-        catch (err) {
-            const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
-            process.stderr.write(`Request handler threw an error:\n${message}\n`);
-            return new Response(`Internal Server Error\n\n${message}`, {
-                status: 500,
-                headers: { "content-type": "text/plain; charset=utf-8" },
-            });
-        }
-    };
-};
-const isAddressInUse = (err) => typeof err === "object" &&
-    err !== null &&
-    err.code === "EADDRINUSE";
-const DEFAULT_SEARCH_BASE = 8787;
-const MAX_SEARCH_STEPS = 100;
-const bindPort = async (server, selection, hostname) => {
-    if (selection.mode === "explicit") {
-        return listen(server, selection.port, hostname);
-    }
-    for (let step = 0; step < MAX_SEARCH_STEPS; step++) {
-        try {
-            return await listen(server, selection.from + step, hostname);
-        }
-        catch (err) {
-            if (!isAddressInUse(err))
-                throw err;
-        }
-    }
-    throw new Error(`Could not find a free port in ${selection.from}-${selection.from + MAX_SEARCH_STEPS - 1}`);
-};
-const listen = (server, port, hostname) => new Promise((resolveListen, rejectListen) => {
-    const onError = (err) => {
-        server.off("listening", onListening);
-        rejectListen(err);
-    };
-    const onListening = () => {
-        server.off("error", onError);
-        resolveListen(server.address().port);
-    };
-    server.once("error", onError);
-    server.once("listening", onListening);
-    server.listen(port, hostname);
-});
-/**
- * Load the (already-bundled) user module, build the listener, and start an HTTP
- * server. Announces the bound port on stdout as `neon-dev:ready <port>` so the
- * parent can render the URL. Resolves with the bound port.
- */
-export const startRuntime = async ({ source, port, hostname, }) => {
-    const absoluteSource = resolve(process.cwd(), source);
-    const mod = (await import(pathToFileURL(absoluteSource).href));
-    const handler = withErrorBoundary(resolveFetchHandler(mod));
-    const listener = getRequestListener(handler, { hostname });
-    const server = createServer((incoming, outgoing) => {
-        void listener(incoming, outgoing);
-    });
-    const boundPort = await bindPort(server, port, hostname);
-    process.stdout.write(`neon-dev:ready ${boundPort}\n`);
-    return boundPort;
-};
-/**
- * Build a {@link PortSelection} from the environment. Precedence:
- *   1. `NEON_DEV_PORT` -> explicit bind (crash if taken). Set by `neon dev` from an
- *      explicit `--port` / `dev.port`.
- *   2. `PORT`          -> explicit bind. A bare `PORT=3000 neon dev` sets this, so the
- *      runtime binds the port chosen for it.
- *   3. otherwise        -> search upward from `NEON_DEV_PORT_BASE` (or the default base).
- */
-export const portSelectionFromEnv = (env) => {
-    const explicit = env.NEON_DEV_PORT;
-    if (explicit !== undefined && explicit !== "") {
-        return { mode: "explicit", port: parsePort(explicit, "NEON_DEV_PORT") };
-    }
-    const injected = env.PORT;
-    if (injected !== undefined && injected !== "") {
-        return { mode: "explicit", port: parsePort(injected, "PORT") };
-    }
-    const base = Number(env.NEON_DEV_PORT_BASE ?? DEFAULT_SEARCH_BASE);
-    return {
-        mode: "search",
-        from: Number.isInteger(base) ? base : DEFAULT_SEARCH_BASE,
-    };
-};
-const parsePort = (value, varName) => {
-    const port = Number(value);
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-        throw new Error(`Invalid ${varName}: "${value}"`);
-    }
-    return port;
-};
-const isDirectExecution = () => {
-    const entry = process.argv[1];
-    if (!entry)
-        return false;
-    return import.meta.url === pathToFileURL(entry).href;
-};
-if (isDirectExecution()) {
-    const source = process.env.NEON_DEV_SOURCE ?? process.argv[2];
-    if (!source) {
-        process.stderr.write("neon-dev runtime: missing source path\n");
-        process.exit(1);
-    }
-    startRuntime({ source, port: portSelectionFromEnv(process.env) }).catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`neon-dev runtime failed to start: ${msg}\n`);
-        process.exit(1);
-    });
-}

package/dist/env.js

@@ -1,36 +0,0 @@
-export const isCi = () => {
-    return process.env.CI !== "false" && Boolean(process.env.CI);
-};
-export const isDebug = () => {
-    return Boolean(process.env.DEBUG);
-};
-export const getGithubEnvVars = (env) => {
-    const vars = [
-        // github action info
-        "GITHUB_ACTION_PATH",
-        // source github repository
-        "GITHUB_REPOSITORY",
-        // environment info
-        "GITHUB_RUN_ID",
-        "GITHUB_RUN_NUMBER",
-        "GITHUB_SERVER_URL",
-        "GITHUB_WORKFLOW_REF",
-        "RUNNER_ARCH",
-        "RUNNER_ENVIRONMENT",
-        "RUNNER_OS",
-    ];
-    const map = new Map();
-    vars.forEach((v) => {
-        let value = env[v];
-        if (value === undefined || value === "") {
-            return;
-        }
-        if (v === "GITHUB_ACTION_PATH") {
-            value = value.includes("actions/")
-                ? value.replace(/^.*actions\/(.+)$/, "$1")
-                : value;
-        }
-        map.set(v, value);
-    });
-    return Object.fromEntries(map);
-};