neonctl 2.22.0 → 2.23.0

package/commands/projects.js

@@ -77,6 +77,12 @@ export const builder = (argv) => {
             describe: 'Connect to a new project via psql',
             default: false,
         },
+        fallback: {
+            type: 'boolean',
+            describe: 'Force the embedded TypeScript psql fallback (for testing)',
+            default: false,
+            hidden: true,
+        },
         database: {
             describe: projectCreateRequest['project.branch.database_name'].description,
             type: 'string',
@@ -242,7 +248,9 @@ const create = async (props) => {
     if (props.psql) {
         const connection_uri = data.connection_uris[0].connection_uri;
         const psqlArgs = props['--'];
-        await psql(connection_uri, psqlArgs);
+        await psql(connection_uri, psqlArgs, {
+            mode: props.fallback ? 'ts' : 'auto',
+        });
     }
 };
 const deleteProject = async (props) => {

package/commands/psql.js

@@ -0,0 +1,62 @@
+import { EndpointType } from '@neondatabase/api-client';
+import { fillSingleProject } from '../utils/enrichers.js';
+import { handler as connectionStringHandler, SSL_MODES, } from './connection_string.js';
+export const command = 'psql [branch]';
+export const describe = 'Connect to a database via psql';
+export const builder = (argv) => {
+    return argv
+        .usage('$0 psql [branch] [options] [-- psql-args]')
+        .example('$0 psql', 'Connect to the default branch via psql')
+        .example('$0 psql main', 'Connect to the main branch via psql')
+        .example('$0 psql main -- -c "SELECT 1"', 'Run a single query against the main branch')
+        .example('$0 psql main@2024-01-01T00:00:00Z', 'Connect to the main branch at a specific point in time')
+        .positional('branch', {
+        describe: `Branch name or id. Defaults to the default branch if omitted. Can be written in the point-in-time format: "branch@timestamp" or "branch@lsn"`,
+        type: 'string',
+    })
+        .options({
+        'project-id': {
+            type: 'string',
+            describe: 'Project ID',
+        },
+        'role-name': {
+            type: 'string',
+            describe: 'Role name',
+        },
+        'database-name': {
+            type: 'string',
+            describe: 'Database name',
+        },
+        pooled: {
+            type: 'boolean',
+            describe: 'Use pooled connection',
+            default: false,
+        },
+        'endpoint-type': {
+            type: 'string',
+            choices: Object.values(EndpointType),
+            describe: 'Endpoint type',
+        },
+        ssl: {
+            type: 'string',
+            choices: SSL_MODES,
+            default: 'require',
+            describe: 'SSL mode',
+        },
+        fallback: {
+            type: 'boolean',
+            describe: 'Force the embedded TypeScript psql fallback (for testing)',
+            default: false,
+            hidden: true,
+        },
+    })
+        .middleware(fillSingleProject);
+};
+export const handler = async (props) => {
+    await connectionStringHandler({
+        ...props,
+        psql: true,
+        prisma: false,
+        extended: false,
+    });
+};

package/commands/set_context.js

@@ -1,4 +1,4 @@
-import { updateContextFile } from '../context.js';
+import { applyContext } from '../context.js';
 export const command = 'set-context';
 export const describe = 'Set the current context';
 export const builder = (argv) => argv.usage('$0 set-context [options]').options({
@@ -10,11 +10,16 @@ export const builder = (argv) => argv.usage('$0 set-context [options]').options(
         describe: 'Organization ID',
         type: 'string',
     },
+    'branch-id': {
+        describe: 'Branch ID',
+        type: 'string',
+    },
 });
 export const handler = (props) => {
     const context = {
         projectId: props.projectId,
         orgId: props.orgId,
+        branchId: props.branchId,
     };
-    updateContextFile(props.contextFile, context);
+    applyContext(props.contextFile, context);
 };

package/context.js

@@ -1,23 +1,39 @@
-import { accessSync, readFileSync, writeFileSync } from 'node:fs';
+import { accessSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { normalize, resolve } from 'node:path';
+import { dirname, normalize, resolve } from 'node:path';
+import { log } from './log.js';
 const CONTEXT_FILE = '.neon';
-const CHECK_FILES = [CONTEXT_FILE, 'package.json', '.git'];
+const GITIGNORE_FILE = '.gitignore';
 const wrapWithContextFile = (dir) => resolve(dir, CONTEXT_FILE);
-export const currentContextFile = () => {
-    const cwd = process.cwd();
+/**
+ * Resolve the default `.neon` path for the current working directory.
+ *
+ * Walks UP from `cwd` looking ONLY for an already-existing `.neon` file so
+ * commands run from a sub-directory of a linked project still pick up the
+ * project's context. If no `.neon` is found, the path defaults to
+ * `<cwd>/.neon`, which makes `neonctl link` and `neonctl set-context`
+ * predictable: they always write the context file into the directory they
+ * were invoked from.
+ *
+ * Historically the walk also considered `package.json` and `.git` as project
+ * markers, but that led to surprising behaviour when running `link` from a
+ * fresh sub-directory inside an unrelated repo (the new link would land in
+ * the parent repo's root instead of the cwd).
+ *
+ * `cwd` is overridable so tests can exercise the walk-up without mutating
+ * `process.cwd()` (which would race with other tests running in parallel).
+ */
+export const currentContextFile = (cwd = process.cwd()) => {
     let currentDir = cwd;
     const root = normalize('/');
     const home = homedir();
     while (currentDir !== root && currentDir !== home) {
-        for (const file of CHECK_FILES) {
-            try {
-                accessSync(resolve(currentDir, file));
-                return wrapWithContextFile(currentDir);
-            }
-            catch {
-                // ignore
-            }
+        try {
+            accessSync(resolve(currentDir, CONTEXT_FILE));
+            return wrapWithContextFile(currentDir);
+        }
+        catch {
+            // ignore
         }
         currentDir = resolve(currentDir, '..');
     }
@@ -32,7 +48,7 @@ export const readContextFile = (file) => {
     }
 };
 export const enrichFromContext = (args) => {
-    if (args._[0] === 'set-context') {
+    if (args._[0] === 'set-context' || args._[0] === 'link') {
         return;
     }
     const context = readContextFile(args.contextFile);
@@ -52,3 +68,59 @@ export const enrichFromContext = (args) => {
 export const updateContextFile = (file, context) => {
     writeFileSync(file, JSON.stringify(context, null, 2));
 };
+/**
+ * Shared primitive used by `set-context`, `link`, and `checkout` to persist
+ * context. Mirrors the destructive write semantics of `updateContextFile` —
+ * any field not present in `context` is dropped from the file.
+ *
+ * `.gitignore` scaffolding only happens when the context file is being
+ * *created* (it didn't exist before this write). On updates to an existing
+ * `.neon` we never touch `.gitignore`, so a user who deliberately un-ignored
+ * the file (e.g. to commit shared context) won't have the entry re-added on
+ * every subsequent command.
+ */
+export const applyContext = (file, context) => {
+    const isNewFile = !existsSync(file);
+    updateContextFile(file, context);
+    if (isNewFile) {
+        ensureGitignored(file);
+    }
+};
+/**
+ * Make sure the `.gitignore` next to `file` lists the file's basename
+ * (currently always `.neon`). Creates the `.gitignore` if it doesn't exist,
+ * or appends `.neon` if it's missing — never duplicates an existing entry.
+ *
+ * Best-effort: a failure here (e.g. read-only filesystem) is logged at debug
+ * level and swallowed; persisting the context file is the primary goal and
+ * must not be blocked by a `.gitignore` write error.
+ */
+export const ensureGitignored = (file) => {
+    try {
+        const dir = dirname(file);
+        const entry = basenameOf(file);
+        const gitignorePath = resolve(dir, GITIGNORE_FILE);
+        if (!existsSync(gitignorePath)) {
+            writeFileSync(gitignorePath, `${entry}\n`);
+            return;
+        }
+        const current = readFileSync(gitignorePath, 'utf-8');
+        if (hasGitignoreEntry(current, entry)) {
+            return;
+        }
+        const needsLeadingNewline = current.length > 0 && !current.endsWith('\n');
+        const addition = `${needsLeadingNewline ? '\n' : ''}${entry}\n`;
+        writeFileSync(gitignorePath, current + addition);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.debug('Failed to update .gitignore next to %s: %s', file, message);
+    }
+};
+const basenameOf = (file) => {
+    const parts = file.split(/[\\/]/);
+    return parts[parts.length - 1] || CONTEXT_FILE;
+};
+const hasGitignoreEntry = (content, entry) => {
+    return content.split(/\r?\n/).some((line) => line.trim() === entry);
+};

package/functions_api.js

@@ -0,0 +1,44 @@
+import { ContentType } from '@neondatabase/api-client';
+const functionsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/functions`;
+export const listFunctions = async (apiClient, projectId, branchId) => {
+    const { data } = await apiClient.request({
+        path: functionsPath(projectId, branchId),
+        method: 'GET',
+        secure: true,
+        format: 'json',
+    });
+    return data.functions;
+};
+export const getFunction = async (apiClient, projectId, branchId, slug) => {
+    const { data } = await apiClient.request({
+        path: `${functionsPath(projectId, branchId)}/${encodeURIComponent(slug)}`,
+        method: 'GET',
+        secure: true,
+        format: 'json',
+    });
+    return data.function;
+};
+export const deleteFunction = async (apiClient, projectId, branchId, slug) => {
+    await apiClient.request({
+        path: `${functionsPath(projectId, branchId)}/${encodeURIComponent(slug)}`,
+        method: 'DELETE',
+        secure: true,
+    });
+};
+export const createDeployment = async (apiClient, projectId, branchId, slug, params) => {
+    const form = new FormData();
+    form.append('zip', new Blob([params.zip]), 'bundle.zip');
+    form.append('memory_mib', String(params.memoryMib));
+    form.append('runtime', params.runtime);
+    if (params.environment)
+        form.append('environment', params.environment);
+    // The deploy POST returns an operation the CLI cannot poll; the body is
+    // ignored. We only need the request to succeed.
+    await apiClient.request({
+        path: `${functionsPath(projectId, branchId)}/${encodeURIComponent(slug)}/deployments`,
+        method: 'POST',
+        type: ContentType.FormData,
+        body: form,
+        secure: true,
+    });
+};

package/index.js

@@ -33,7 +33,10 @@ const NO_SUBCOMMANDS_VERBS = [
     // aliases
     'cs',
     'connection-string',
+    'psql',
     'set-context',
+    'checkout',
+    'link',
     'init',
     // aliases
 ];

package/package.json

@@ -5,68 +5,75 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "private": false,
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "pnpm@9.15.9",
   "bin": {
     "neonctl": "cli.js",
     "neon": "cli.js"
   },
   "devDependencies": {
-    "@apidevtools/swagger-parser": "^10.1.0",
-    "@commitlint/cli": "^17.6.5",
-    "@commitlint/config-conventional": "^17.6.5",
-    "@eslint/js": "^9.23.0",
-    "@rollup/plugin-commonjs": "^25.0.2",
-    "@rollup/plugin-json": "^6.0.0",
-    "@rollup/plugin-node-resolve": "^15.1.0",
-    "@semantic-release/exec": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@types/bun": "^1.1.4",
-    "@yao-pkg/pkg": "^6.10.0",
-    "@types/cli-table": "^0.3.0",
-    "@types/diff": "^5.2.1",
-    "@types/eslint__js": "^8.42.3",
-    "@types/express": "^4.17.17",
-    "@types/node": "^18.7.13",
+    "@apidevtools/swagger-parser": "12.1.0",
+    "@commitlint/cli": "17.8.1",
+    "@commitlint/config-conventional": "17.8.1",
+    "@eslint/js": "9.29.0",
+    "@rollup/plugin-commonjs": "25.0.8",
+    "@rollup/plugin-json": "6.1.0",
+    "@rollup/plugin-node-resolve": "15.2.3",
+    "@testcontainers/postgresql": "^11.14.0",
+    "@types/cli-table": "0.3.4",
+    "@types/diff": "5.2.1",
+    "@types/eslint__js": "8.42.3",
+    "@types/express": "4.17.21",
+    "@types/node": "18.19.41",
     "@types/prompts": "2.4.9",
-    "@types/which": "^3.0.0",
-    "@types/yargs": "^17.0.24",
-    "emocks": "^3.0.1",
-    "eslint": "^9.23.0",
-    "express": "^4.18.2",
-    "husky": "^8.0.3",
-    "lint-staged": "^13.0.3",
-    "oauth2-mock-server": "^8.1.0",
-    "prettier": "^3.1.0",
-    "rollup": "^3.26.2",
-    "semantic-release": "^23.0.8",
-    "strip-ansi": "^7.1.0",
-    "typescript": "^4.7.4",
+    "@types/which": "3.0.4",
+    "@types/yargs": "17.0.32",
+    "@yao-pkg/pkg": "6.10.0",
+    "emocks": "3.0.4",
+    "esbuild": "0.28.0",
+    "eslint": "9.29.0",
+    "express": "4.19.2",
+    "husky": "8.0.3",
+    "lint-staged": "13.3.0",
+    "node-pty": "1.1.0",
+    "oauth2-mock-server": "8.1.0",
+    "prettier": "3.3.3",
+    "rollup": "3.29.4",
+    "strip-ansi": "7.1.0",
+    "tsx": "4.22.3",
+    "typescript": "4.9.5",
     "typescript-eslint": "8.28.0",
-    "vitest": "^1.6.0"
+    "vitest": "1.6.1"
+  },
+  "optionalDependencies": {
+    "esbuild": "0.28.0"
   },
   "dependencies": {
-    "@neondatabase/api-client": "2.6.0",
-    "@segment/analytics-node": "^1.0.0-beta.26",
-    "axios": "^1.4.0",
-    "axios-debug-log": "^1.0.0",
-    "chalk": "^5.2.0",
-    "cli-table": "^0.3.11",
-    "diff": "^5.2.0",
-    "neon-init": "^0.14.0",
-    "open": "^10.1.0",
-    "openid-client": "^6.8.1",
+    "@neondatabase/api-client": "2.7.1",
+    "@segment/analytics-node": "1.3.0",
+    "axios": "1.7.2",
+    "axios-debug-log": "1.0.0",
+    "chalk": "5.3.0",
+    "cli-table": "0.3.11",
+    "cliui": "8.0.1",
+    "diff": "5.2.0",
+    "fflate": "^0.8.3",
+    "neon-init": "0.14.0",
+    "open": "10.1.0",
+    "openid-client": "6.8.1",
+    "pg-protocol": "^1.14.0",
     "prompts": "2.4.2",
-    "which": "^3.0.1",
-    "yaml": "^2.1.1",
-    "yargs": "^17.7.2"
+    "which": "3.0.1",
+    "yaml": "2.4.5",
+    "yargs": "17.7.2"
   },
   "publishConfig": {
     "access": "public",
@@ -90,14 +97,16 @@
   "scripts": {
     "watch": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "lint": "npm run typecheck && eslint src && prettier --check .",
-    "lint:fix": "npm run typecheck && eslint src --fix && prettier --w .",
-    "build": "bun generateParams && bun clean && tsc && cp src/*.html package*.json README.md ./dist",
+    "lint": "pnpm typecheck && eslint src && prettier --check .",
+    "lint:fix": "pnpm typecheck && eslint src --fix && prettier --w .",
+    "build": "pnpm generateParams && pnpm clean && tsc -p tsconfig.build.json && cp src/*.html package*.json README.md ./dist",
     "clean": "rm -rf dist",
-    "generateParams": "bun generateOptionsFromSpec.ts",
-    "start": "bun dist/index.js",
-    "pretest": "bun run build",
+    "generateParams": "tsx generateOptionsFromSpec.ts",
+    "start": "node dist/index.js",
+    "pretest": "pnpm build",
     "test": "vitest run",
+    "test:conformance": "vitest run --config tests/psql-conformance/vitest.config.ts",
+    "test:conformance:matrix": "tsx tests/psql-conformance/scripts/run-local-matrix.ts",
     "prepare": "test -d .git && husky install || true"
   },
   "lint-staged": {

package/psql/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Standalone psql shim.
+ *
+ * Thin wrapper around `runPsql` that lets the conformance harness — and any
+ * caller that wants a psql-compatible CLI — invoke our embedded TypeScript
+ * psql directly via `node dist/psql/cli.js`, without going through the
+ * neonctl yargs entrypoint.
+ *
+ * Why this exists: `dist/cli.js` is the neonctl entrypoint; yargs eats
+ * libpq-style flags (e.g. `-v ON_ERROR_STOP=0` collides with yargs'
+ * built-in `--version`). The conformance suite needs to spawn a binary
+ * that accepts the upstream psql flag grammar (`-h`/`-p`/`-U`/`-d`/`-X`/
+ * `-v VAR=VALUE`/`--no-psqlrc`/`--echo-all`/`--quiet`/etc.) and reads SQL
+ * from stdin. This shim wires `process.argv.slice(2)` straight into
+ * `runPsql`, which already speaks that grammar via `parseStartupArgs`.
+ *
+ * Argv shape:
+ *   - If the first positional looks like a connection URI / conninfo
+ *     (per `looksLikeConnectionString`), it stays at argv[0] — same shape
+ *     as the legacy native-psql call site in `src/utils/psql.ts` and the
+ *     existing `runPsql` API.
+ *   - Otherwise (the regress harness case: bare libpq flags), we prepend
+ *     an empty placeholder URI so `runPsql([''] + flags)` falls through to
+ *     `parseStartupArgs` and resolves the connection from `-h`/`-p`/`-U`/
+ *     `-d` plus PG* env / pgpass / service via the layered resolver.
+ *
+ * Exit code: forwarded straight from `runPsql` (matches upstream psql's
+ * EXIT_SUCCESS / EXIT_FAILURE / EXIT_USER / EXIT_BADCONN values; see
+ * `core/mainloop.ts`).
+ */
+import { runPsql, looksLikeConnectionString } from './index.js';
+const main = async () => {
+    const raw = process.argv.slice(2);
+    // Detect whether the first arg is a connection URI/conninfo string.
+    // libpq's `recognized_connection_string()` covers both `postgres[ql]://…`
+    // URIs and bare `key=value` conninfo strings — `looksLikeConnectionString`
+    // mirrors that test.
+    const argv = raw.length > 0 && looksLikeConnectionString(raw[0]) ? raw : ['', ...raw];
+    const code = await runPsql(argv, {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+    });
+    process.exit(code);
+};
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`psql: fatal: ${msg}\n`);
+    process.exit(1);
+});