neonctl 1.28.0 → 1.29.1

package/src/test_utils/test_cli_command.ts

@@ -0,0 +1,117 @@
+import { test, expect, describe, beforeAll, afterAll } from '@jest/globals';
+import { fork } from 'node:child_process';
+import { Server } from 'node:http';
+import { AddressInfo } from 'node:net';
+import { join } from 'node:path';
+import { log } from '../log.js';
+import strip from 'strip-ansi';
+
+import { runMockServer } from './mock_server.js';
+
+export type TestCliCommandOptions = {
+  name: string;
+  args: string[];
+  before?: () => Promise<void>;
+  after?: () => Promise<void>;
+  mockDir?: string;
+  expected?: {
+    snapshot?: true;
+    stdout?: string | ReturnType<typeof expect.stringMatching>;
+    stderr?: string | ReturnType<typeof expect.stringMatching>;
+    code?: number;
+  };
+};
+
+export const testCliCommand = ({
+  args,
+  name,
+  expected,
+  before,
+  after,
+  mockDir = 'main',
+}: TestCliCommandOptions) => {
+  let server: Server;
+  describe(name, () => {
+    beforeAll(async () => {
+      if (before) {
+        await before();
+      }
+      server = await runMockServer(mockDir);
+    });
+
+    afterAll(async () => {
+      if (after) {
+        await after();
+      }
+      return new Promise<void>((resolve) => {
+        server.close(() => {
+          resolve();
+        });
+      });
+    });
+
+    test('test', async () => {
+      let output = '';
+      let error = '';
+
+      const cp = fork(
+        join(process.cwd(), './dist/index.js'),
+        [
+          '--api-host',
+          `http://localhost:${(server.address() as AddressInfo).port}`,
+          '--output',
+          'yaml',
+          '--api-key',
+          'test-key',
+          '--no-analytics',
+          ...args,
+        ],
+        {
+          stdio: 'pipe',
+          env: {
+            PATH: `mocks/bin:${process.env.PATH}`,
+          },
+        },
+      );
+
+      return new Promise<void>((resolve, reject) => {
+        cp.stdout?.on('data', (data) => {
+          output += data.toString();
+        });
+
+        cp.stderr?.on('data', (data) => {
+          error += data.toString();
+          log.error(data.toString());
+        });
+
+        cp.on('error', (err) => {
+          throw err;
+        });
+
+        cp.on('close', (code) => {
+          try {
+            expect(code).toBe(expected?.code ?? 0);
+            if (expected) {
+              if (expected.snapshot) {
+                expect(output).toMatchSnapshot();
+              }
+              if (expected.stdout !== undefined) {
+                expect(strip(output)).toEqual(expected.stdout);
+              }
+              if (expected.stderr !== undefined) {
+                expect(strip(error).replace(/\s+/g, ' ').trim()).toEqual(
+                  typeof expected.stderr === 'string'
+                    ? expected.stderr.toString().replace(/\s+/g, ' ')
+                    : expected.stderr,
+                );
+              }
+            }
+            resolve();
+          } catch (err) {
+            reject(err);
+          }
+        });
+      });
+    });
+  });
+};

package/src/types.ts

@@ -0,0 +1,25 @@
+import { Api } from '@neondatabase/api-client';
+
+export type CommonProps = {
+  apiClient: Api<unknown>;
+  apiKey: string;
+  apiHost: string;
+  output: 'yaml' | 'json' | 'table';
+  contextFile: string;
+};
+
+export type ProjectScopeProps = CommonProps & {
+  projectId: string;
+};
+
+export type IdOrNameProps = {
+  id: string;
+};
+
+export type BranchScopeProps = ProjectScopeProps &
+  (
+    | {
+        branch: string;
+      }
+    | IdOrNameProps
+  );

package/src/utils/enrichers.ts

@@ -0,0 +1,73 @@
+import { BranchScopeProps, CommonProps, ProjectScopeProps } from '../types.js';
+import { looksLikeBranchId } from './formats.js';
+
+export const branchIdResolve = async ({
+  branch,
+  apiClient,
+  projectId,
+}: {
+  branch: string | number;
+  apiClient: CommonProps['apiClient'];
+  projectId: string;
+}) => {
+  branch = branch.toString();
+  if (looksLikeBranchId(branch)) {
+    return branch;
+  }
+
+  const { data } = await apiClient.listProjectBranches(projectId);
+  const branchData = data.branches.find((b) => b.name === branch);
+  if (!branchData) {
+    throw new Error(
+      `Branch ${branch} not found.\nAvailable branches: ${data.branches
+        .map((b) => b.name)
+        .join(', ')}`,
+    );
+  }
+  return branchData.id;
+};
+
+export const branchIdFromProps = async (props: BranchScopeProps) => {
+  const branch =
+    'branch' in props && typeof props.branch === 'string'
+      ? props.branch
+      : (props as any).id;
+
+  if (branch) {
+    return await branchIdResolve({
+      branch,
+      apiClient: props.apiClient,
+      projectId: props.projectId,
+    });
+  }
+
+  const { data } = await props.apiClient.listProjectBranches(props.projectId);
+  const primaryBranch = data.branches.find((b) => b.primary);
+
+  if (primaryBranch) {
+    return primaryBranch.id;
+  }
+
+  throw new Error('No primary branch found');
+};
+
+export const fillSingleProject = async (
+  props: CommonProps & Partial<Pick<ProjectScopeProps, 'projectId'>>,
+) => {
+  if (props.projectId) {
+    return props;
+  }
+  const { data } = await props.apiClient.listProjects({});
+  if (data.projects.length === 0) {
+    throw new Error('No projects found');
+  }
+  if (data.projects.length > 1) {
+    throw new Error(
+      `Multiple projects found, please provide one with the --project-id option`,
+    );
+  }
+  return {
+    ...props,
+    projectId: data.projects[0].id,
+  };
+};

package/src/utils/formats.test.ts

@@ -0,0 +1,41 @@
+import { test, describe, expect } from '@jest/globals';
+
+import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp } from './formats';
+
+describe('branch formats', () => {
+  test('branch name', () => {
+    expect(looksLikeBranchId('master')).toBe(false);
+  });
+
+  test('initial short', () => {
+    expect(looksLikeBranchId('br-flower-sunshine-123456')).toBe(true);
+  });
+
+  test('update 1, longer version', () => {
+    expect(looksLikeBranchId('br-flower-sunshine-12345678')).toBe(true);
+  });
+
+  test('update 2, includes region', () => {
+    expect(looksLikeBranchId('br-bold-recipe-a13oexw7')).toBe(true);
+  });
+});
+
+describe('timestamp formats', () => {
+  test('valid', () => {
+    expect(looksLikeTimestamp('2021-03-13T19:47:33.000Z')).toBe(true);
+  });
+
+  test('invalid', () => {
+    expect(looksLikeTimestamp('branch_name')).toBe(false);
+  });
+});
+
+describe('LSN formats', () => {
+  test('valid', () => {
+    expect(looksLikeLSN('0/1F56000')).toBe(true);
+  });
+
+  test('invalid', () => {
+    expect(looksLikeLSN('branch_name')).toBe(false);
+  });
+});

package/src/utils/formats.ts

@@ -0,0 +1,11 @@
+const HAIKU_REGEX = /^[a-z]+-[a-z]+-[a-z0-9]+$/;
+
+export const looksLikeBranchId = (branch: string) =>
+  branch.startsWith('br-') && HAIKU_REGEX.test(branch.substring(3));
+
+const LSN_REGEX = /^[a-fA-F0-9]{1,8}\/[a-fA-F0-9]{1,8}$/;
+
+export const looksLikeLSN = (lsn: string) => LSN_REGEX.test(lsn);
+
+export const looksLikeTimestamp = (timestamp: string) =>
+  !isNaN(Date.parse(timestamp));

package/src/utils/middlewares.ts

@@ -0,0 +1,23 @@
+/**
+ * This middleware is needed to fill in the args for nested objects,
+ * so that required arguments would work
+ * otherwise yargs just throws an error
+ */
+export const fillInArgs = (
+  args: Record<string, unknown>,
+  currentArgs: Record<string, unknown> = args,
+  acc: string[] = [],
+) => {
+  Object.entries(currentArgs).forEach(([k, v]) => {
+    if (k === '_') {
+      return;
+    }
+    // check if the value is an Object
+    if (typeof v === 'object' && v !== null) {
+      fillInArgs(args, v as any, [...acc, k]);
+    } else if (acc.length > 0) {
+      // if it's not an object, and we have a path, fill it in
+      args[acc.join('.') + '.' + k] = v;
+    }
+  });
+};

package/src/utils/point_in_time.ts

@@ -0,0 +1,86 @@
+import { Api } from '@neondatabase/api-client';
+import { looksLikeLSN, looksLikeTimestamp } from './formats.js';
+import { branchIdResolve } from './enrichers.js';
+
+export type PointInTime =
+  | {
+      tag: 'head';
+    }
+  | {
+      tag: 'lsn';
+      lsn: string;
+    }
+  | {
+      tag: 'timestamp';
+      timestamp: string;
+    };
+export type PointInTimeBranchId = {
+  branchId: string;
+} & PointInTime;
+
+export type PointInTimeBranch = {
+  branch: string;
+} & PointInTime;
+
+export interface PointInTimeProps {
+  targetBranchId: string;
+  pointInTime: string;
+  projectId: string;
+  api: Api<unknown>;
+}
+
+export class PointInTimeParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PointInTimeParseError';
+  }
+}
+
+export const parsePITBranch = (input: string) => {
+  const splitIndex = input.lastIndexOf('@');
+  const sourceBranch = splitIndex === -1 ? input : input.slice(0, splitIndex);
+  const exactPIT = splitIndex === -1 ? null : input.slice(splitIndex + 1);
+  const result = {
+    branch: sourceBranch,
+    ...(exactPIT === null
+      ? { tag: 'head' }
+      : looksLikeLSN(exactPIT)
+        ? { tag: 'lsn', lsn: exactPIT }
+        : { tag: 'timestamp', timestamp: exactPIT }),
+  } satisfies PointInTimeBranch;
+  if (result.tag === 'timestamp' && !looksLikeTimestamp(result.timestamp)) {
+    throw new PointInTimeParseError('Invalid source branch format');
+  }
+  return result;
+};
+
+export const parsePointInTime = async ({
+  pointInTime,
+  targetBranchId,
+  projectId,
+  api,
+}: PointInTimeProps) => {
+  const parsedPIT = parsePITBranch(pointInTime);
+
+  let branchId = '';
+  if (parsedPIT.branch === '^self') {
+    branchId = targetBranchId;
+  } else if (parsedPIT.branch === '^parent') {
+    const { data } = await api.getProjectBranch(projectId, targetBranchId);
+    const { parent_id: parentId } = data.branch;
+    if (parentId == null) {
+      throw new PointInTimeParseError('Branch has no parent');
+    }
+    branchId = parentId;
+  } else {
+    branchId = await branchIdResolve({
+      branch: parsedPIT.branch,
+      projectId,
+      apiClient: api,
+    });
+  }
+
+  // @ts-expect-error extracting pit from parsedPIT
+  delete parsedPIT.branch;
+  return { ...parsedPIT, branchId };
+};

package/src/utils/psql.ts

@@ -0,0 +1,29 @@
+import { log } from '../log.js';
+import { spawn } from 'child_process';
+import which from 'which';
+
+export const psql = async (connection_uri: string, args: string[] = []) => {
+  const psqlPathOrNull = await which('psql', { nothrow: true });
+
+  if (psqlPathOrNull === null) {
+    log.error(`psql is not available in the PATH`);
+    process.exit(1);
+  }
+
+  log.info('Connecting to the database using psql...');
+  const psql = spawn(psqlPathOrNull, [connection_uri, ...args], {
+    stdio: 'inherit',
+  });
+
+  for (const signame of ['SIGINT', 'SIGTERM']) {
+    process.on(signame, (code) => {
+      if (!psql.killed && code !== null) {
+        psql.kill(code);
+      }
+    });
+  }
+
+  psql.on('exit', (code: number | null) => {
+    process.exit(code === null ? 1 : code);
+  });
+};

package/src/utils/string.ts

@@ -0,0 +1,8 @@
+export const toSnakeCase = (str: string) =>
+  str
+    .split(' ')
+    .map((word) => word.toLowerCase())
+    .join('_');
+
+export const isObject = (value: any) =>
+  value != null && value === Object(value);

package/src/utils/ui.ts

@@ -0,0 +1,64 @@
+// returns the next string if matches the given matcher,
+// otherwise returns null
+// consumes the line from the lines array
+export const consumeNextMatching = (lines: string[], matcher: RegExp) => {
+  while (lines.length > 0) {
+    const line = (lines.shift() as string).trim();
+    if (line === '') {
+      continue;
+    }
+    if (matcher.test(line)) {
+      return line;
+    }
+    return null;
+  }
+  return null;
+};
+
+// returns strings if next non-empty line matches the given matcher,
+// otherwise returns empty array
+// consumes the lines from the lines array
+export const consumeBlockIfMatches = (lines: string[], matcher: RegExp) => {
+  const result = [] as string[];
+  if (lines.length === 0) {
+    return result;
+  }
+
+  let line = lines.shift() as string;
+
+  while (line.trim() === '') {
+    line = lines.shift() as string;
+  }
+  if (!matcher.test(line)) {
+    lines.unshift(line);
+    return result;
+  }
+  result.push(line);
+  while (lines.length > 0) {
+    line = lines.shift() as string;
+    if (line.trim() === '') {
+      break;
+    }
+    result.push(line);
+  }
+  return result;
+};
+
+export const splitColumns = (line: string) => {
+  const result = line.trim().split(/\s{2,}/);
+  result[1] = result[1] ?? '';
+  if (result.length > 2) {
+    result[1] = result.slice(1).join(' ');
+  }
+  return result;
+};
+
+export const drawPointer = (width: number) => {
+  const result = [] as string[];
+  result.push('└');
+  for (let i = 0; i < width - 4; i++) {
+    result.push('─');
+  }
+  result.push('>');
+  return result.join('');
+};

package/src/writer.test.ts

@@ -0,0 +1,98 @@
+import { Writable } from 'node:stream';
+import { describe, it, expect } from '@jest/globals';
+import { writer } from './writer.js';
+
+class MockWritable extends Writable {
+  _data: Buffer[] = [];
+
+  get data() {
+    return this._data.map((chunk) => chunk.toString()).join('');
+  }
+
+  _write(chunk: Buffer) {
+    this._data.push(chunk);
+  }
+}
+
+describe('writer', () => {
+  describe('outputs yaml', () => {
+    it('outputs single data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'yaml', out: stream });
+      out.end({ foo: 'bar' }, { fields: ['foo'] });
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs single data with title', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'yaml', out: stream });
+      out.end({ foo: 'bar' }, { fields: ['foo'], title: 'baz' });
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs multiple data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'yaml', out: stream });
+      out
+        .write({ foo: 'bar' }, { fields: ['foo'], title: 'T1' })
+        .write({ baz: 'xyz' }, { fields: ['baz'], title: 'T2' })
+        .end();
+      expect(stream.data).toMatchSnapshot();
+    });
+  });
+
+  describe('outputs json', () => {
+    it('outputs single data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'json', out: stream });
+      out.end({ foo: 'bar' }, { fields: ['foo'] });
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs single data with title', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'json', out: stream });
+      out.end({ foo: 'bar' }, { fields: ['foo'], title: 'baz' });
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs multiple data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'json', out: stream });
+      out
+        .write({ foo: 'bar' }, { fields: ['foo'], title: 'T1' })
+        .write({ baz: 'xyz' }, { fields: ['baz'], title: 'T2' })
+        .end();
+      expect(stream.data).toMatchSnapshot();
+    });
+  });
+
+  describe('outputs table', () => {
+    it('outputs single data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'table', out: stream });
+      out.end({ foo: 'bar', extra: 'extra' }, { fields: ['foo'] });
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs single data with title', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'table', out: stream });
+      out.end(
+        { foo: 'bar', extra: 'extra' },
+        { fields: ['foo'], title: 'baz' },
+      );
+      expect(stream.data).toMatchSnapshot();
+    });
+
+    it('outputs multiple data', () => {
+      const stream = new MockWritable();
+      const out = writer({ output: 'table', out: stream });
+      out
+        .write({ foo: 'bar', extra: 'extra' }, { fields: ['foo'], title: 'T1' })
+        .write({ baz: 'xyz', extra: 'extra' }, { fields: ['baz'], title: 'T2' })
+        .end();
+      expect(stream.data).toMatchSnapshot();
+    });
+  });
+});