neonctl 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,126 @@
+Neon offers several methods for working with your projects. Utilizing the Neon Command Line Interface (CLI), you can operate Neon directly from a terminal or via automation. The Neon CLI facilitates numerous functions, such as Neon authentication, project creation and management, and more.
+
+## Synopsis
+
+The `neonctl` command can be called from command line. Without any arguments, it displays command usage and help:
+
+```bash
+usage: neonctl <cmd> [args]
+
+Commands:
+  neonctl auth                Authenticate
+  neonctl projects [command]  Manage projects
+  neonctl me                  Show current user
+  neonctl branches            Manage branches
+
+Options:
+      --version     Show version number                                [boolean]
+      --help        Show help                                          [boolean]
+  -o, --output      Set output format
+                  [string] [choices: "json", "yaml", "table"] [default: "table"]
+      --api-host    The API host   [default: "https://console.neon.tech/api/v2"]
+      --config-dir  Path to config directory
+                              [string] [default: "/home/eduard/.config/neonctl"]
+      --oauth-host  URL to Neon OAUTH host [default: "https://oauth2.neon.tech"]
+      --client-id   OAuth client id                [string] [default: "neonctl"]
+      --api-key     API key                               [string] [default: ""]
+```
+
+## Install the Neon CLI
+
+This topic describes how to install the `neonctl` command-line interface tool and connect to Neon.
+
+### Prerequisites
+
+- Node.js 16.0 or higher. To check if you already have Node.js, run the following command:
+
+    ```shell
+    node -v
+    ```
+
+- The `npm` package manager.  To check if you already have `npm`, run the following command:
+
+   ```shell
+   npm -v
+   ```
+
+If you need to install either `Node.js` or `npm`, refer to instructions on [official nodejs page](https://nodejs.org) or you can use [Node version manager](https://github.com/nvm-sh/nvm).
+
+### Install
+
+To download and install Neon CLI, run the following command:
+
+```shell
+npm i -g neonctl
+```
+
+### Connect
+
+To authenticate to Neon, run the following command:
+
+```shell
+neonctl auth
+```
+
+The command launches a browser window where you can authorize the Neon CLI to access your Neon account. After granting permission, your credentials are saved locally to a credentials file.
+
+## Commands
+
+### neonctl auth
+
+Authenticates the user or caller to Neon. See [Connect](#connect).
+
+### neonctl me
+
+Returns information about the authenticated user.
+
+```bash
+$> neonctl me
+┌────────────────┬──────────────────────────┬────────────┬────────────────┐
+│ Login          │ Email                    │ Name       │ Projects Limit │
+├────────────────┼──────────────────────────┼────────────┼────────────────┤
+│ user1          │ user1@example.com        │ User1      │ 1              │
+└────────────────┴──────────────────────────┴────────────┴────────────────┘
+```
+
+
+### neonctl projects
+
+For creating and managing Neon projects.
+
+## neonctl branches
+For creating and managing Neon branches.
+
+## Options
+
+### version
+
+Shows the neonctl version number
+
+### help
+
+Shows the neonctl command-line help
+
+### output, o
+
+Sets the output format.
+
+### api-host
+
+Shows the API host
+
+### config-dir
+
+Sets the path to the `neonctl` configuration directory
+
+### oauth-host
+
+Sets the URL of Neon OAuth host
+
+### client-id
+
+Sets the OAuth client id
+
+### api-key
+
+Sets the API key

package/commands/auth.js

@@ -4,6 +4,7 @@ import { TokenSet } from 'openid-client';
 import { auth, refreshToken } from '../auth.js';
 import { log } from '../log.js';
 import { getApiClient } from '../api.js';
+import { isCi } from '../env.js';
 const CREDENTIALS_FILE = 'credentials.json';
 export const command = 'auth';
 export const describe = 'Authenticate';
@@ -12,6 +13,9 @@ export const handler = async (args) => {
     await authFlow(args);
 };
 export const authFlow = async ({ configDir, oauthHost, clientId, }) => {
+    if (isCi()) {
+        throw new Error('Cannot run interactive auth in CI');
+    }
     if (!clientId) {
         throw new Error('Missing client id');
     }

package/commands/branches.js

@@ -1,18 +1,12 @@
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { writeOut } from '../writer.js';
+import { writer } from '../writer.js';
 import { branchCreateRequest, branchCreateRequestEndpointOptions, branchUpdateRequest, } from '../parameters.gen.js';
+import { commandFailHandler } from '../utils.js';
+const BRANCH_FIELDS = ['id', 'name', 'created_at'];
 export const command = 'branches';
 export const describe = 'Manage branches';
 export const builder = (argv) => argv
     .demandCommand(1, '')
-    .fail(async (_msg, _err, argv) => {
-    const y = yargs(hideBin(process.argv));
-    if (y.argv._.length === 1) {
-        argv.showHelp();
-        process.exit(1);
-    }
-})
+    .fail(commandFailHandler)
     .usage('usage: $0 branches <cmd> [args]')
     .options({
     'project.id': {
@@ -24,7 +18,7 @@ export const builder = (argv) => argv
     .command('list', 'List branches', (yargs) => yargs, async (args) => await list(args))
     .command('create', 'Create a branch', (yargs) => yargs.options({
     ...branchCreateRequest,
-    ...Object.fromEntries(Object.entries(branchCreateRequestEndpointOptions).map(([key, value]) => [`endpoint.${key}`, value])),
+    ...Object.fromEntries(Object.entries(branchCreateRequestEndpointOptions).map(([key, value]) => [`endpoint.${key}`, { ...value, demandOption: false }])),
 }), async (args) => await create(args))
     .command('update', 'Update a branch', (yargs) => yargs.options(branchUpdateRequest).option('branch.id', {
     describe: 'Branch ID',
@@ -35,14 +29,19 @@ export const builder = (argv) => argv
     describe: 'Branch ID',
     type: 'string',
     demandOption: true,
-}), async (args) => await deleteBranch(args));
+}), async (args) => await deleteBranch(args))
+    .command('get', 'Get a branch', (yargs) => yargs.option('branch.id', {
+    describe: 'Branch ID',
+    type: 'string',
+    demandOption: true,
+}), async (args) => await get(args));
 export const handler = (args) => {
     return args;
 };
 const list = async (props) => {
     const { data } = await props.apiClient.listProjectBranches(props.project.id);
-    writeOut(props)(data.branches, {
-        fields: ['id', 'name', 'created_at'],
+    writer(props).end(data.branches, {
+        fields: BRANCH_FIELDS,
     });
 };
 const create = async (props) => {
@@ -50,42 +49,42 @@ const create = async (props) => {
         branch: props.branch,
         endpoints: props.endpoint ? [props.endpoint] : undefined,
     });
-    writeOut(props)({
-        branch: {
-            data: data.branch,
-            config: { fields: ['id', 'name', 'created_at'] },
-        },
-        ...(data.endpoints?.length > 0
-            ? {
-                endpoints: {
-                    data: data.endpoints,
-                    config: { fields: ['id', 'created_at'] },
-                },
-            }
-            : {}),
-        ...(data.connection_uris
-            ? {
-                connection_uri: {
-                    data: data.connection_uris[0],
-                    config: {
-                        fields: ['connection_uri'],
-                    },
-                },
-            }
-            : {}),
+    const out = writer(props);
+    out.write(data.branch, {
+        fields: BRANCH_FIELDS,
+        title: 'branch',
     });
+    if (data.endpoints?.length > 0) {
+        out.write(data.endpoints, {
+            fields: ['id', 'created_at'],
+            title: 'endpoints',
+        });
+    }
+    if (data.connection_uris && data.connection_uris?.length > 0) {
+        out.write(data.connection_uris, {
+            fields: ['connection_uri'],
+            title: 'connection_uris',
+        });
+    }
+    out.end();
 };
 const update = async (props) => {
     const { data } = await props.apiClient.updateProjectBranch(props.project.id, props.branch.id, {
         branch: props.branch,
     });
-    writeOut(props)(data.branch, {
-        fields: ['id', 'name', 'created_at'],
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
     });
 };
 const deleteBranch = async (props) => {
     const { data } = await props.apiClient.deleteProjectBranch(props.project.id, props.branch.id);
-    writeOut(props)(data.branch, {
-        fields: ['id', 'name', 'created_at'],
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const get = async (props) => {
+    const { data } = await props.apiClient.getProjectBranch(props.project.id, props.branch.id);
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
     });
 };

package/commands/branches.test.js

@@ -0,0 +1,85 @@
+import { describe } from '@jest/globals';
+import { testCliCommand } from '../test_utils.js';
+describe('branches', () => {
+    testCliCommand({
+        name: 'list',
+        args: ['branches', 'list', '--project.id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create with endpoint',
+        args: [
+            'branches',
+            'create',
+            '--project.id',
+            'test',
+            '--branch.name',
+            'test_branch',
+            '--endpoint.type',
+            'read_only',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create without endpoint',
+        args: [
+            'branches',
+            'create',
+            '--project.id',
+            'test',
+            '--branch.name',
+            'test_branch',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'delete',
+        args: [
+            'branches',
+            'delete',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'update',
+        args: [
+            'branches',
+            'update',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+            '--branch.name',
+            'new_test_branch',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'get',
+        args: [
+            'branches',
+            'get',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+});

package/commands/databases.js

@@ -0,0 +1,54 @@
+import { databaseCreateRequest } from '../parameters.gen.js';
+import { commandFailHandler } from '../utils.js';
+import { writer } from '../writer.js';
+const DATABASE_FIELDS = ['name', 'owner_name'];
+export const command = 'databases';
+export const describe = 'Manage databases';
+export const builder = (argv) => argv
+    .demandCommand(1, '')
+    .fail(commandFailHandler)
+    .usage('usage: $0 databases <cmd> [args]')
+    .options({
+    'project.id': {
+        describe: 'Project ID',
+        type: 'string',
+        demandOption: true,
+    },
+    'branch.id': {
+        describe: 'Branch ID',
+        type: 'string',
+        demandOption: true,
+    },
+})
+    .command('list', 'List databases', (yargs) => yargs, async (args) => await list(args))
+    .command('create', 'Create a database', (yargs) => yargs.options(databaseCreateRequest), async (args) => await create(args))
+    .command('delete', 'Delete a database', (yargs) => yargs.options({
+    'database.name': {
+        describe: 'Database name',
+        type: 'string',
+        demandOption: true,
+    },
+}), async (args) => await deleteDb(args));
+export const handler = (args) => {
+    return args;
+};
+export const list = async (props) => {
+    const { data } = await props.apiClient.listProjectBranchDatabases(props.project.id, props.branch.id);
+    writer(props).end(data.databases, {
+        fields: DATABASE_FIELDS,
+    });
+};
+export const create = async (props) => {
+    const { data } = await props.apiClient.createProjectBranchDatabase(props.project.id, props.branch.id, {
+        database: props.database,
+    });
+    writer(props).end(data.database, {
+        fields: DATABASE_FIELDS,
+    });
+};
+export const deleteDb = async (props) => {
+    const { data } = await props.apiClient.deleteProjectBranchDatabase(props.project.id, props.branch.id, props.database.name);
+    writer(props).end(data.database, {
+        fields: DATABASE_FIELDS,
+    });
+};

package/commands/databases.test.js

@@ -0,0 +1,52 @@
+import { describe } from '@jest/globals';
+import { testCliCommand } from '../test_utils.js';
+describe('databases', () => {
+    testCliCommand({
+        name: 'list',
+        args: [
+            'databases',
+            'list',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create',
+        args: [
+            'databases',
+            'create',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+            '--database.name',
+            'test_db',
+            '--database.owner_name',
+            'test_owner',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'delete',
+        args: [
+            'databases',
+            'delete',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+            '--database.name',
+            'test_db',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+});

package/commands/endpoints.js

@@ -0,0 +1,86 @@
+import { endpointCreateRequest, endpointUpdateRequest, } from '../parameters.gen.js';
+import { commandFailHandler } from '../utils.js';
+import { writer } from '../writer.js';
+const ENDPOINT_FIELDS = [
+    'id',
+    'created_at',
+    'branch_id',
+    'type',
+    'current_state',
+];
+export const command = 'endpoints';
+export const describe = 'Manage endpoints';
+export const builder = (argv) => argv
+    .demandCommand(1, '')
+    .fail(commandFailHandler)
+    .usage('usage: $0 endpoints <cmd> [args]')
+    .options({
+    'project.id': {
+        describe: 'Project ID',
+        type: 'string',
+        demandOption: true,
+    },
+})
+    .command('list', 'List endpoints', (yargs) => yargs.options({
+    'branch.id': {
+        describe: 'Branch ID',
+        type: 'string',
+        demandOption: false,
+    },
+}), async (args) => await list(args))
+    .command('create', 'Create an endpoint', (yargs) => yargs.options(endpointCreateRequest), async (args) => await create(args))
+    .command('update', 'Update an endpoint', (yargs) => yargs.options({
+    'endpoint.id': {
+        describe: 'Endpoint ID',
+        type: 'string',
+        demandOption: true,
+    },
+    ...endpointUpdateRequest,
+}), async (args) => await update(args))
+    .command('delete', 'Delete an endpoint', (yargs) => yargs.options({
+    'endpoint.id': {
+        describe: 'Endpoint ID',
+        type: 'string',
+        demandOption: true,
+    },
+}), async (args) => await deleteEndpoint(args))
+    .command('get', 'Get an endpoint', (yargs) => yargs.options({
+    'endpoint.id': {
+        describe: 'Endpoint ID',
+        type: 'string',
+        demandOption: true,
+    },
+}), async (args) => await getEndpoint(args));
+export const handler = async (args) => args;
+const list = async (props) => {
+    const { data } = props.branch?.id
+        ? await props.apiClient.listProjectBranchEndpoints(props.project.id, props.branch.id)
+        : await props.apiClient.listProjectEndpoints(props.project.id);
+    writer(props).end(data.endpoints, {
+        fields: ENDPOINT_FIELDS,
+    });
+};
+const create = async (props) => {
+    const { data } = await props.apiClient.createProjectEndpoint(props.project.id, { endpoint: props.endpoint });
+    writer(props).end(data.endpoint, {
+        fields: ENDPOINT_FIELDS,
+    });
+};
+const update = async (props) => {
+    const { data } = await props.apiClient.updateProjectEndpoint(props.project.id, props.endpoint.id, { endpoint: props.endpoint });
+    writer(props).end(data.endpoint, {
+        fields: ENDPOINT_FIELDS,
+    });
+};
+const deleteEndpoint = async (props) => {
+    const { data } = await props.apiClient.deleteProjectEndpoint(props.project.id, props.endpoint.id);
+    writer(props).end(data.endpoint, {
+        fields: ENDPOINT_FIELDS,
+    });
+};
+const getEndpoint = async (props) => {
+    const { data } = await props.apiClient.getProjectEndpoint(props.project.id, props.endpoint.id);
+    writer(props).end(data.endpoint, {
+        fields: ENDPOINT_FIELDS,
+    });
+};

package/commands/endpoints.test.js

@@ -0,0 +1,85 @@
+import { describe } from '@jest/globals';
+import { testCliCommand } from '../test_utils.js';
+describe('endpoints', () => {
+    testCliCommand({
+        name: 'list',
+        args: ['endpoints', 'list', '--project.id', 'test'],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'list with branch filter',
+        args: [
+            'endpoints',
+            'list',
+            '--project.id',
+            'test',
+            '--branch.id',
+            'test_branch_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'create',
+        args: [
+            'endpoints',
+            'create',
+            '--project.id',
+            'test',
+            '--endpoint.branch_id',
+            'test_branch_id',
+            '--endpoint.type',
+            'read_only',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'delete',
+        args: [
+            'endpoints',
+            'delete',
+            '--project.id',
+            'test',
+            '--endpoint.id',
+            'test_endpoint_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'update',
+        args: [
+            'endpoints',
+            'update',
+            '--project.id',
+            'test',
+            '--endpoint.id',
+            'test_endpoint_id',
+            '--endpoint.branch_id',
+            'test_branch_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'get',
+        args: [
+            'endpoints',
+            'get',
+            '--project.id',
+            'test',
+            '--endpoint.id',
+            'test_endpoint_id',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
+});

package/commands/index.js

@@ -2,4 +2,6 @@ import * as auth from './auth.js';
 import * as projects from './projects.js';
 import * as users from './users.js';
 import * as branches from './branches.js';
-export default [auth, projects, users, branches];
+import * as endpoints from './endpoints.js';
+import * as databases from './databases.js';
+export default [auth, projects, users, branches, endpoints, databases];