neonctl 2.22.0 → 2.22.2

package/commands/link.test.js

@@ -0,0 +1,381 @@
+import { fork } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { beforeAll, describe, expect } from 'vitest';
+import { test as originalTest } from '../test_utils/fixtures';
+// All tests in this file share a single temporary directory whose path is
+// normalized in snapshots to `<TMP>` so that absolute paths in command output
+// (both human summaries and agent JSON) remain stable across runs and machines.
+const TEST_TMP = mkdtempSync(join(tmpdir(), 'neonctl-link-'));
+const TMP_TOKEN = '<TMP>';
+beforeAll(() => {
+    // Replace any reference to the per-run tmp directory with a stable token so
+    // snapshots only carry the deterministic suffix portion of paths.
+    expect.addSnapshotSerializer({
+        test: (val) => typeof val === 'string' && val.includes(TEST_TMP),
+        serialize: (val, config, indentation, depth, refs, printer) => printer(val.split(TEST_TMP).join(TMP_TOKEN), config, indentation, depth, refs),
+    });
+});
+const test = originalTest.extend({
+    // eslint-disable-next-line no-empty-pattern
+    cleanupFile: async ({}, use) => {
+        let writtenFilename;
+        await use((name) => (writtenFilename = name));
+        if (writtenFilename) {
+            try {
+                rmSync(writtenFilename);
+            }
+            catch {
+                // ignore
+            }
+        }
+    },
+    readFile: async ({ cleanupFile }, use) => {
+        await use((name) => {
+            const content = readFileSync(name, 'utf-8');
+            cleanupFile(name);
+            return content;
+        });
+    },
+    // eslint-disable-next-line no-empty-pattern
+    removeFile: async ({}, use) => {
+        await use((name) => {
+            try {
+                rmSync(name);
+            }
+            catch {
+                // ignore
+            }
+        });
+    },
+    // Each test gets its OWN sub-directory under TEST_TMP so the
+    // `.gitignore` scaffolded next to the `.neon` written by one test doesn't
+    // affect another test in the same file.
+    // eslint-disable-next-line no-empty-pattern
+    tmpContext: async ({}, use) => {
+        await use((label) => {
+            const dir = join(TEST_TMP, label);
+            mkdirSync(dir, { recursive: true });
+            return join(dir, '.neon');
+        });
+    },
+    runLinkInCi: async ({ runMockServer }, use) => {
+        await use(async (args) => {
+            const server = await runMockServer('main');
+            const port = server.address().port;
+            return new Promise((resolve, reject) => {
+                const cp = fork(join(process.cwd(), './dist/index.js'), [
+                    '--api-host',
+                    `http://localhost:${port}`,
+                    '--output',
+                    'yaml',
+                    '--api-key',
+                    'test-key',
+                    '--no-analytics',
+                    ...args,
+                ], {
+                    stdio: 'pipe',
+                    env: {
+                        PATH: `mocks/bin:${process.env.PATH}`,
+                        CI: 'true',
+                    },
+                });
+                let stdout = '';
+                let stderr = '';
+                cp.stdout?.on('data', (data) => {
+                    stdout += data.toString();
+                });
+                cp.stderr?.on('data', (data) => {
+                    stderr += data.toString();
+                });
+                cp.on('error', reject);
+                cp.on('close', (code) => {
+                    resolve({ code: code ?? -1, stdout, stderr });
+                });
+            });
+        });
+    },
+});
+describe('link', () => {
+    describe('non-interactive flag mode', () => {
+        test('link to existing project writes .neon with default branch id', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('flag_existing');
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+        test('link with --params JSON behaves like flags', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('flag_params');
+            await testCliCommand([
+                'link',
+                '--params',
+                JSON.stringify({ orgId: 'org-2', projectId: 'test' }),
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+        test('link creates a new project and writes .neon', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('flag_create');
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-name',
+                'test_project',
+                '--region-id',
+                'aws-us-east-2',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+        test('conflicting inputs (--project-id with --project-name) fails', async ({ testCliCommand, tmpContext, }) => {
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--project-name',
+                'test_project',
+                '--context-file',
+                tmpContext('flag_conflict'),
+            ], {
+                code: 1,
+                stderr: 'ERROR: Conflicting inputs: --project-id selects an existing project; --project-name and --region-id describe a new one. Pass only one set.',
+            });
+        });
+    });
+    describe('--agent mode', () => {
+        test('with no flags emits needs_org JSON', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('agent_needs_org');
+            await testCliCommand(['link', '--agent', '--context-file', ctx]);
+            removeFile(ctx);
+        });
+        test('with only --org-id emits needs_project JSON', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('agent_needs_project');
+            await testCliCommand([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-2',
+                '--context-file',
+                ctx,
+            ]);
+            removeFile(ctx);
+        });
+        test('with org+project emits linked JSON and writes .neon', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('agent_linked_existing');
+            await testCliCommand([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+        test('with org+projectName but no region emits needs_project_details JSON', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('agent_needs_region');
+            await testCliCommand([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-2',
+                '--project-name',
+                'demo',
+                '--context-file',
+                ctx,
+            ]);
+            removeFile(ctx);
+        });
+        test('with full project details creates project and emits linked JSON', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('agent_linked_create');
+            await testCliCommand([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-2',
+                '--project-name',
+                'test_project',
+                '--region-id',
+                'aws-us-east-2',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+    });
+    describe('org-scoped API key behavior', () => {
+        test('agent mode with no orgs available and no projects emits orgKeyLimited needs_org', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('orgkey_empty');
+            await testCliCommand(['link', '--agent', '--context-file', ctx], {
+                mockDir: 'org-key-empty',
+            });
+            removeFile(ctx);
+        });
+        test('agent mode auto-detects org from existing projects when org listing is forbidden', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('orgkey_autodetect');
+            await testCliCommand(['link', '--agent', '--context-file', ctx], {
+                mockDir: 'org-key',
+            });
+            removeFile(ctx);
+        });
+        test('agent mode falls back to static regions when getActiveRegions is forbidden', async ({ testCliCommand, removeFile, tmpContext, }) => {
+            const ctx = tmpContext('orgkey_regions_fallback');
+            await testCliCommand([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-detected-99887766',
+                '--project-name',
+                'whatever',
+                '--context-file',
+                ctx,
+            ], { mockDir: 'org-key' });
+            removeFile(ctx);
+        });
+    });
+    describe('agent error responses', () => {
+        test('invalid --params JSON yields error JSON, exit 1', async ({ runLinkInCi, tmpContext, }) => {
+            const result = await runLinkInCi([
+                'link',
+                '--agent',
+                '--params',
+                'not-valid-json',
+                '--context-file',
+                tmpContext('agent_bad_params'),
+            ]);
+            expect(result.code).toBe(1);
+            const parsed = JSON.parse(result.stdout);
+            expect(parsed.status).toBe('error');
+            expect(parsed.code).toBe('INTERNAL_ERROR');
+            expect(parsed.message).toContain('Failed to parse --params JSON');
+        });
+        test('conflicting flags in agent mode yields error JSON, exit 1', async ({ runLinkInCi, tmpContext, }) => {
+            const result = await runLinkInCi([
+                'link',
+                '--agent',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--project-name',
+                'x',
+                '--context-file',
+                tmpContext('agent_conflict'),
+            ]);
+            expect(result.code).toBe(1);
+            const parsed = JSON.parse(result.stdout);
+            expect(parsed.status).toBe('error');
+            expect(parsed.message).toContain('Conflicting inputs');
+        });
+    });
+    describe('CI guard', () => {
+        test('errors out with helpful message when no inputs provided in CI', async ({ runLinkInCi, tmpContext, }) => {
+            const result = await runLinkInCi([
+                'link',
+                '--context-file',
+                tmpContext('ci_guard'),
+            ]);
+            expect(result.code).toBe(1);
+            expect(result.stderr).toContain('CI environment detected');
+            expect(result.stderr).toContain('neonctl link --agent');
+        });
+    });
+    describe('set-context regression', () => {
+        test('set-context --branch-id writes branchId to .neon', async ({ testCliCommand, readFile, tmpContext, }) => {
+            const ctx = tmpContext('sc_branch');
+            await testCliCommand([
+                'set-context',
+                '--project-id',
+                'test_project',
+                '--branch-id',
+                'br-main-branch-123456',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFile(ctx)).toMatchSnapshot();
+        });
+    });
+    test('overwrites an existing .neon when re-linking non-interactively', async ({ testCliCommand, readFile, tmpContext, }) => {
+        const ctx = tmpContext('overwrite');
+        writeFileSync(ctx, JSON.stringify({ orgId: 'old', projectId: 'old', branchId: 'old' }));
+        await testCliCommand([
+            'link',
+            '--org-id',
+            'org-2',
+            '--project-id',
+            'test',
+            '--context-file',
+            ctx,
+        ]);
+        expect(readFile(ctx)).toMatchSnapshot();
+    });
+    describe('gitignore scaffolding', () => {
+        test('creates a .gitignore listing .neon next to the context file', async ({ testCliCommand, tmpContext, }) => {
+            const ctx = tmpContext('gi_creates');
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            const giPath = join(ctx, '..', '.gitignore');
+            expect(readFileSync(giPath, 'utf-8')).toBe('.neon\n');
+        });
+        test('appends .neon to an existing .gitignore without duplicating', async ({ testCliCommand, tmpContext, }) => {
+            const ctx = tmpContext('gi_appends');
+            const giPath = join(ctx, '..', '.gitignore');
+            writeFileSync(giPath, 'node_modules\ndist\n');
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFileSync(giPath, 'utf-8')).toBe('node_modules\ndist\n.neon\n');
+            // Re-link in the same dir must not produce a duplicate entry.
+            await testCliCommand([
+                'link',
+                '--org-id',
+                'org-2',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            expect(readFileSync(giPath, 'utf-8')).toBe('node_modules\ndist\n.neon\n');
+        });
+        test('set-context also scaffolds .gitignore via the shared applyContext', async ({ testCliCommand, tmpContext, }) => {
+            const ctx = tmpContext('gi_set_context');
+            await testCliCommand([
+                'set-context',
+                '--project-id',
+                'test',
+                '--context-file',
+                ctx,
+            ]);
+            const giPath = join(ctx, '..', '.gitignore');
+            expect(readFileSync(giPath, 'utf-8')).toBe('.neon\n');
+        });
+    });
+});

package/commands/psql.js

@@ -0,0 +1,57 @@
+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',
+        },
+    })
+        .strict()
+        .middleware(fillSingleProject);
+};
+export const handler = async (props) => {
+    await connectionStringHandler({
+        ...props,
+        psql: true,
+        prisma: false,
+        extended: false,
+    });
+};

package/commands/psql.test.js

@@ -0,0 +1,49 @@
+import { describe } from 'vitest';
+import { test } from '../test_utils/fixtures';
+describe('psql', () => {
+    test('psql connects to a branch', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'psql',
+            'test_branch',
+            '--project-id',
+            'test',
+            '--database-name',
+            'test_db',
+            '--role-name',
+            'test_role',
+        ]);
+    });
+    test('psql forwards args after --', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'psql',
+            'test_branch',
+            '--project-id',
+            'test',
+            '--database-name',
+            'test_db',
+            '--role-name',
+            'test_role',
+            '--',
+            '-c',
+            'SELECT 1',
+        ]);
+    });
+    test('psql pooled', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'psql',
+            'test_branch',
+            '--project-id',
+            'test',
+            '--database-name',
+            'test_db',
+            '--role-name',
+            'test_role',
+            '--pooled',
+        ]);
+    });
+    test('psql without any args should pass', async ({ testCliCommand }) => {
+        await testCliCommand(['psql'], {
+            mockDir: 'single_project',
+        });
+    });
+});

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);
+};