neonctl 2.37.0 → 2.38.0

package/dist/commands/functions.js

@@ -1,373 +0,0 @@
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { isNeonApiError, retryOnLock } from "../api.js";
-import { createDeployment, deleteFunction, getFunction, listFunctions, } from "../functions_api.js";
-import { log } from "../log.js";
-import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
-import { bundleEntry } from "../utils/esbuild.js";
-import { zipBundle } from "../utils/zip.js";
-import { writer } from "../writer.js";
-const FUNCTION_FIELDS = [
-    "slug",
-    "name",
-    "invocation_url",
-    "created_at",
-];
-const FUNCTIONS_LIST_LIMIT = 100;
-// Table columns for `functions list`. `status` is a derived field (the
-// table writer reads flat fields only): the current deployment's status.
-const LIST_TABLE_FIELDS = [
-    "slug",
-    "name",
-    "status",
-    "invocation_url",
-    "created_at",
-];
-const DEPLOYMENT_FIELDS = [
-    "id",
-    "status",
-    "runtime",
-    "memory_mib",
-    "created_at",
-];
-// Deploy emits the resolved deployment plus the function's invocation_url, so a
-// successful `functions deploy` tells the user exactly where to call the function.
-const DEPLOY_RESULT_FIELDS = [
-    "id",
-    "status",
-    "invocation_url",
-    "runtime",
-    "memory_mib",
-    "created_at",
-];
-// In table mode a failed build's reason gets its own "deployment error"
-// section after the deployment table; json/yaml carry the raw `error` field.
-const writeDeploymentErrorSection = (out, dep) => {
-    if (dep.status === "failed" && dep.error) {
-        out.write({ reason: dep.error }, { fields: ["reason"], title: "deployment error" });
-    }
-};
-const SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
-const SLUG_HELP = "Use 1-20 lowercase letters and digits (no hyphens or other characters).";
-// Entry-point discovery order inside --src.
-const ENTRY_CANDIDATES = ["index.ts", "index.mjs", "index.js"];
-// Overridable so tests can poll fast; defaults to 2s in real use.
-const POLL_INTERVAL_MS = Number(process.env.NEON_FUNCTIONS_POLL_INTERVAL_MS) || 2000;
-// Upper bound on --wait polling so the CLI never hangs (e.g. if our deployment
-// never shows up as current_deployment). Overridable so tests can time out fast;
-// defaults to 10 minutes in real use.
-const POLL_TIMEOUT_MS = Number(process.env.NEON_FUNCTIONS_POLL_TIMEOUT_MS) || 600000;
-export const command = "functions";
-export const describe = "Manage Neon Functions";
-export const aliases = ["function"];
-export const builder = (argv) => argv
-    .usage("$0 function <sub-command> [options]")
-    .options({
-    "project-id": {
-        describe: "Project ID",
-        type: "string",
-    },
-    branch: {
-        describe: "Branch ID or name",
-        type: "string",
-    },
-})
-    .middleware(fillSingleProject)
-    .command("deploy <slug>", "Deploy a function from a local directory", (yargs) => yargs
-    .positional("slug", {
-    describe: "Function slug (1-20 lowercase letters and digits)",
-    type: "string",
-    demandOption: true,
-})
-    .options({
-    src: {
-        describe: "Function source: a directory containing index.ts, index.mjs, or index.js, or a path to the entry file",
-        type: "string",
-    },
-    // Removed flags, kept hidden so old invocations fail loudly instead
-    // of being silently ignored (the CLI has no .strictOptions()).
-    path: {
-        type: "string",
-        hidden: true,
-    },
-    entry: {
-        type: "string",
-        hidden: true,
-    },
-    runtime: {
-        describe: "Function runtime",
-        type: "string",
-        choices: ["nodejs24"],
-    },
-    env: {
-        describe: "Environment variable as KEY=VALUE (repeatable)",
-        type: "string",
-        array: true,
-    },
-    wait: {
-        describe: "Wait for the deployment to finish building",
-        type: "boolean",
-        default: true,
-    },
-}), (args) => deploy(args))
-    .command("list", "List functions on the branch", (yargs) => yargs, (args) => list(args))
-    .command("get <slug>", "Show a function's details", (yargs) => yargs
-    .positional("slug", {
-    describe: "Function slug",
-    type: "string",
-    demandOption: true,
-})
-    .options({
-    "list-env-variables": {
-        describe: "List the environment variable names of the active deployment",
-        type: "boolean",
-        alias: "E",
-        default: false,
-    },
-}), (args) => get(args))
-    .command("delete <slug>", "Delete a function on the branch", (yargs) => yargs.positional("slug", {
-    describe: "Function slug",
-    type: "string",
-    demandOption: true,
-}), (args) => deleteFn(args));
-export const handler = (args) => {
-    return args;
-};
-const parseEnv = (entries) => {
-    if (!entries || entries.length === 0)
-        return undefined;
-    const map = {};
-    for (const entry of entries) {
-        const eq = entry.indexOf("=");
-        if (eq <= 0) {
-            throw new Error(`Invalid --env value "${entry}". Expected KEY=VALUE.`);
-        }
-        map[entry.slice(0, eq)] = entry.slice(eq + 1);
-    }
-    return JSON.stringify(map);
-};
-const statusHint = (slug, projectId, branchId) => `Check status with: neonctl function get ${slug} --project-id ${projectId} --branch ${branchId}`;
-// Emit the resolved deployment together with the function's invocation_url, so the
-// deploy output shows where the function is reachable (not just the deployment id).
-const emitDeployResult = (props, deployment, fn) => {
-    const out = writer(props).write({ ...deployment, invocation_url: fn?.invocation_url }, { fields: DEPLOY_RESULT_FIELDS });
-    if (props.output !== "json" && props.output !== "yaml") {
-        writeDeploymentErrorSection(out, deployment);
-    }
-    out.end();
-};
-// A poll error worth retrying: a network error (no HTTP response), a 5xx, or a
-// 404 from eventual consistency. Anything else (e.g. 401/403) is surfaced.
-const isTransient = (err) => isNeonApiError(err) &&
-    (err.status === undefined || err.status === 404 || err.status >= 500);
-const deploy = async (props) => {
-    if (props.path !== undefined || props.entry !== undefined) {
-        throw new Error("--path and --entry were removed. Use --src <dir>; the entry point " +
-            "is discovered as index.ts, index.mjs, or index.js in that directory.");
-    }
-    // At least one deploy option must be passed (--wait is excluded: it controls
-    // output, not what gets deployed).
-    const hasOption = props.src !== undefined ||
-        props.env !== undefined ||
-        props.runtime !== undefined;
-    if (!hasOption) {
-        throw new Error("Provide at least one option to deploy, e.g. --src or --env. " +
-            "See: neonctl function deploy --help.");
-    }
-    // Cheap, offline validation first - fail before any network round-trip.
-    if (!SLUG_PATTERN.test(props.slug)) {
-        throw new Error(`Invalid function slug "${props.slug}". ${SLUG_HELP}`);
-    }
-    const src = props.src ?? ".";
-    const runtime = props.runtime ?? "nodejs24";
-    const environment = parseEnv(props.env);
-    const srcStat = statSync(src, { throwIfNoEntry: false });
-    if (srcStat === undefined) {
-        throw new Error(`--src path not found: ${src}.`);
-    }
-    // A file is used as the entry point directly; a directory triggers discovery.
-    const source = srcStat.isFile()
-        ? src
-        : ENTRY_CANDIDATES.map((name) => join(src, name)).find((p) => existsSync(p));
-    if (source === undefined) {
-        throw new Error(`No entry file found in ${src}. Expected one of: ${ENTRY_CANDIDATES.join(", ")}.`);
-    }
-    // Bundle before any network round-trip so a bundling failure fails fast.
-    const zip = zipBundle(await bundleEntry(source));
-    const branchId = await branchIdFromProps(props);
-    // Snapshot the current version before deploy so we can detect the new one
-    // afterward. A missing function (404) or no deployment yet → undefined.
-    let before;
-    try {
-        const fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
-        before = fn.current_deployment?.id;
-    }
-    catch (err) {
-        if (!(isNeonApiError(err) && err.status === 404))
-            throw err;
-    }
-    await retryOnLock(() => createDeployment(props.apiClient, props.projectId, branchId, props.slug, {
-        zip,
-        runtime,
-        environment,
-    }));
-    log.info(`Function deployment triggered for function ${props.slug}.`);
-    // Best-effort interrupt: a Ctrl-C lands at the next poll boundary. (No
-    // automated test; mirrors the resolution branches below, verified manually.)
-    let interrupted = false;
-    const onSignal = () => {
-        interrupted = true;
-    };
-    process.once("SIGINT", onSignal);
-    process.once("SIGTERM", onSignal);
-    // Poll until a NEW version appears (id greater than the snapshot, or
-    // any version if there was none). --no-wait stops there; --wait stops at a
-    // terminal status. Bounded by POLL_TIMEOUT_MS so it never hangs.
-    let resolved;
-    // The function carries the invocation_url; keep the whole record (not just its
-    // current_deployment) so we can surface that URL on success.
-    let resolvedFn;
-    const deadline = Date.now() + POLL_TIMEOUT_MS;
-    try {
-        while (!interrupted && Date.now() < deadline) {
-            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-            if (interrupted)
-                break;
-            // The deploy already succeeded server-side; tolerate transient poll
-            // failures and retry on the next interval. Surface anything else.
-            let fn;
-            try {
-                fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
-            }
-            catch (err) {
-                if (isTransient(err))
-                    continue;
-                throw err;
-            }
-            const dep = fn.current_deployment;
-            const isNew = dep !== undefined && (before === undefined || dep.id > before);
-            if (isNew && dep) {
-                resolved = dep;
-                resolvedFn = fn;
-                if (!props.wait)
-                    break;
-                if (dep.status === "completed" || dep.status === "failed")
-                    break;
-            }
-        }
-    }
-    finally {
-        process.removeListener("SIGINT", onSignal);
-        process.removeListener("SIGTERM", onSignal);
-    }
-    if (interrupted) {
-        log.info(statusHint(props.slug, props.projectId, branchId));
-        if (resolved)
-            emitDeployResult(props, resolved, resolvedFn);
-        return;
-    }
-    if (resolved === undefined) {
-        log.info(statusHint(props.slug, props.projectId, branchId));
-        throw new Error(`Timed out waiting for the deployment of ${props.slug} to start. It may still be in progress.`);
-    }
-    emitDeployResult(props, resolved, resolvedFn);
-    if (!props.wait) {
-        log.info(statusHint(props.slug, props.projectId, branchId));
-        return;
-    }
-    if (resolved.status === "completed") {
-        log.info(`Function deployment ${props.slug}/${resolved.id} completed.`);
-        return;
-    }
-    if (resolved.status === "failed") {
-        throw new Error(`Function deployment ${props.slug}/${resolved.id} failed.`);
-    }
-    // --wait, new version appeared but the deadline hit before it finished.
-    log.info(statusHint(props.slug, props.projectId, branchId));
-    throw new Error(`Timed out waiting for function deployment ${props.slug}/${resolved.id} to finish. It may still be building.`);
-};
-const get = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
-    if (props.output === "json" || props.output === "yaml") {
-        writer(props).end(fn, { fields: FUNCTION_FIELDS });
-        return;
-    }
-    const out = writer(props).write(fn, {
-        fields: FUNCTION_FIELDS,
-        title: "function",
-    });
-    const current = fn.current_deployment;
-    const active = fn.active_deployment;
-    if (current && active && current.id === active.id) {
-        out.write(current, {
-            fields: DEPLOYMENT_FIELDS,
-            title: "deployment (current, active)",
-        });
-        writeDeploymentErrorSection(out, current);
-    }
-    else {
-        if (current) {
-            out.write(current, {
-                fields: DEPLOYMENT_FIELDS,
-                title: "current deployment",
-            });
-            // The failure reason is shown only for the current deployment;
-            // the active one completed successfully by definition.
-            writeDeploymentErrorSection(out, current);
-        }
-        if (active) {
-            out.write(active, {
-                fields: DEPLOYMENT_FIELDS,
-                title: "active deployment",
-            });
-        }
-    }
-    if (props.listEnvVariables) {
-        out.write((fn.active_deployment?.environment ?? []).map((name) => ({ name })), {
-            fields: ["name"],
-            title: "environment",
-            emptyMessage: "No environment variables on the active deployment.",
-        });
-    }
-    out.end();
-};
-const deleteFn = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    try {
-        await retryOnLock(() => deleteFunction(props.apiClient, props.projectId, branchId, props.slug));
-    }
-    catch (err) {
-        if (isNeonApiError(err) && err.status === 404) {
-            throw new Error(`Function "${props.slug}" not found on branch ${branchId}.`);
-        }
-        throw err;
-    }
-    log.info(`Function ${props.slug} deleted from branch ${branchId}`);
-};
-const list = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const functions = [];
-    let cursor;
-    for (;;) {
-        const page = await listFunctions(props.apiClient, props.projectId, branchId, { cursor, limit: FUNCTIONS_LIST_LIMIT });
-        functions.push(...page.functions);
-        log.debug("Got %d functions, next cursor: %s", page.functions.length, page.next);
-        // A server echoing the same cursor would loop forever; treat it as
-        // the end of the list.
-        if (!page.next || page.next === cursor)
-            break;
-        cursor = page.next;
-    }
-    if (props.output === "json" || props.output === "yaml") {
-        writer(props).end(functions, { fields: FUNCTION_FIELDS });
-        return;
-    }
-    writer(props).end(functions.map((fn) => ({
-        ...fn,
-        status: fn.current_deployment?.status ?? "",
-    })), {
-        fields: LIST_TABLE_FIELDS,
-        emptyMessage: "No functions found on this branch.",
-    });
-};

package/dist/commands/index.js

@@ -1,62 +0,0 @@
-import * as api from "./api.js";
-import * as auth from "./auth.js";
-import * as bootstrap from "./bootstrap.js";
-import * as branches from "./branches.js";
-import * as bucket from "./bucket.js";
-import * as checkout from "./checkout.js";
-import * as config from "./config.js";
-import * as cs from "./connection_string.js";
-import * as dataApi from "./data_api.js";
-import * as databases from "./databases.js";
-import * as deploy from "./deploy.js";
-import * as dev from "./dev.js";
-import * as diff from "./diff.js";
-import * as env from "./env.js";
-import * as functions from "./functions.js";
-import * as init from "./init.js";
-import * as inspect from "./inspect.js";
-import * as ipAllow from "./ip_allow.js";
-import * as link from "./link.js";
-import * as neonAuth from "./neon_auth.js";
-import * as operations from "./operations.js";
-import * as orgs from "./orgs.js";
-import * as projects from "./projects.js";
-import * as psql from "./psql.js";
-import * as roles from "./roles.js";
-import * as setContext from "./set_context.js";
-import * as snapshots from "./snapshots.js";
-import * as status from "./status.js";
-import * as users from "./user.js";
-import * as vpcEndpoints from "./vpc_endpoints.js";
-export default [
-    auth,
-    api,
-    users,
-    orgs,
-    projects,
-    ipAllow,
-    vpcEndpoints,
-    neonAuth,
-    branches,
-    databases,
-    roles,
-    operations,
-    snapshots,
-    inspect,
-    cs,
-    psql,
-    setContext,
-    checkout,
-    link,
-    init,
-    dataApi,
-    functions,
-    dev,
-    diff,
-    config,
-    status,
-    deploy,
-    env,
-    bucket,
-    bootstrap,
-];

package/dist/commands/init.js

@@ -1,73 +0,0 @@
-import { detectAgent, enrichResponse, interactiveInit, orchestrate, routeDataStep, } from "neon-init";
-import { sendError } from "../analytics.js";
-import { log } from "../log.js";
-export const command = "init";
-export const describe = "Initialize a project with Neon using your AI coding assistant";
-export const builder = (yargs) => yargs
-    .option("context-file", {
-    hidden: true,
-})
-    .option("agent", {
-    alias: "a",
-    type: "boolean",
-    default: false,
-    describe: "Enable agent/JSON mode (agent type is auto-detected).",
-})
-    .option("data", {
-    type: "string",
-    describe: 'JSON object with a "step" field to route to a specific phase and phase-specific options.',
-})
-    .option("skip-migrations", {
-    type: "boolean",
-    default: false,
-    describe: "Skip the migrations phase.",
-})
-    .option("preview", {
-    type: "boolean",
-    default: false,
-    describe: "Enable preview features (e.g. project bootstrapping from templates).",
-})
-    .strict(false);
-export const handler = async (argv) => {
-    try {
-        // Auto-detect agent from environment. When --agent is explicitly passed,
-        // always detect (the user asked for agent mode). Otherwise, require
-        // non-TTY stdin to distinguish agent from human in terminal.
-        const agent = (argv.agent || !process.stdin.isTTY ? detectAgent() : null) ||
-            undefined;
-        const isAgentMode = argv.agent || agent !== undefined;
-        // --data with a "step" field routes to the appropriate phase
-        if (argv.data && isAgentMode) {
-            let data;
-            try {
-                data = JSON.parse(argv.data);
-            }
-            catch {
-                log.error("Invalid JSON in --data flag. Expected a JSON object.");
-                process.exit(1);
-                return;
-            }
-            if (typeof data.step === "string") {
-                const result = await routeDataStep(data, agent);
-                log.info(JSON.stringify(enrichResponse(result), null, 2));
-                return;
-            }
-        }
-        if (isAgentMode) {
-            const result = await orchestrate({
-                agent,
-                skipMigrations: argv.skipMigrations,
-                preview: argv.preview,
-            });
-            log.info(JSON.stringify(enrichResponse(result), null, 2));
-        }
-        else {
-            await interactiveInit({ preview: argv.preview });
-        }
-    }
-    catch {
-        const exitError = new Error(`failed to run neon-init`);
-        sendError(exitError, "NEON_INIT_FAILED");
-        process.exit(1);
-    }
-};

package/dist/commands/inspect.js

@@ -1,65 +0,0 @@
-import { fillSingleProject } from "../utils/enrichers.js";
-import { resolveConnectionUri, runInspectQuery } from "../utils/inspect_db.js";
-import { INSPECT_QUERIES, } from "../utils/inspect_queries.js";
-import { writer } from "../writer.js";
-export const command = "inspect";
-export const describe = "Inspect a database's health and configuration";
-export const aliases = ["inspection"];
-/**
- * `fillSingleProject` hits the API to auto-resolve a project. When the user
- * passes `--db-url` we bypass the Neon API entirely, so skip it.
- */
-const fillSingleProjectUnlessDbUrl = async (props) => {
-    if (props.dbUrl) {
-        return props;
-    }
-    return fillSingleProject(props);
-};
-const runSubcommand = async (name, props) => {
-    const query = INSPECT_QUERIES[name];
-    const connectionUri = props.dbUrl ?? (await resolveConnectionUri(props)).connectionUri;
-    const rows = await runInspectQuery(connectionUri, query.sql, {
-        requiresExtension: query.requiresExtension,
-    });
-    writer(props).end(rows, {
-        fields: query.fields,
-        emptyMessage: query.emptyMessage,
-    });
-};
-const dbBuilder = (argv) => {
-    let builder = argv
-        .usage("$0 inspect db <sub-command> [options]")
-        .options({
-        "project-id": {
-            describe: "Project ID",
-            type: "string",
-        },
-        branch: {
-            describe: "Branch ID or name",
-            type: "string",
-        },
-        "database-name": {
-            describe: "Database name",
-            type: "string",
-        },
-        "role-name": {
-            describe: "Role name",
-            type: "string",
-        },
-        "db-url": {
-            describe: "Inspect any Postgres via a connection string, bypassing the Neon API (project/branch resolution is skipped)",
-            type: "string",
-        },
-    })
-        .middleware(fillSingleProjectUnlessDbUrl);
-    for (const name of Object.keys(INSPECT_QUERIES)) {
-        builder = builder.command(name, INSPECT_QUERIES[name].describe, (yargs) => yargs, (args) => runSubcommand(name, args));
-    }
-    return builder;
-};
-export const builder = (argv) => argv
-    .usage("$0 inspect <sub-command> [options]")
-    .command("db", "Run a diagnostic query against a branch's Postgres", dbBuilder);
-export const handler = (args) => {
-    return args;
-};