v4.0.0

=====================================================================

Big day! V4 is finally live. This INCLUDES some BREAKING CHANGES to ZSH
TYPE scwrypts! Please refer to the readme for upgrade details
                     (more specifically docs/upgrade/v3-to-v4.md)

Upgrade is SUPER EASY, so please take the time to do so.

--- New Features ----------------------------------------------------

- zsh type scwrypts have an upgraded runstring to improve context setup
  and simplicity to the scwrypt-writer

- scwrypts now publishes the package (scwrypts) to PyPi; this provides a
  simple way to invoke scwrypts from python-based environments as well
  as the entire scwrypts python library suite

  pip install scwrypts

- scwrypts now publishes the package (scwrypts) to npm; this provides a
  simple way to invoke scwrypts from nodesjs environments

  npm install scwrypts

--- Bug Fixes -------------------------------------------------------

- scwrypts runner prompts which use the zshbuiltin "read" now
  appropriately read input from tty, pipe, files, and user input

- virtualenv refresh now loads and prepares the scwrypts virtual
  environments correctly

--- Changes ---------------------------------------------------------

- created the (-v, --log-level) scwrypts arguments as improvements of
  and replacements to the --verbose and --no-log flags
     - (-n) is now an alias for (--log-level 0)
     - (--no-log) is the same as (-n) for compatibility, but will be removed in 4.2

- zsh/lib/utils/io print functions now *interact with log-level* various
  log levels will now only display the appropriate console prints for
  the specified log level

- zsh/lib/utils/io:INFO has been renamed to DEBUG to align with
  log-level output; please use DEBUG for debug messages and REMINDER for
  important user messages

- created zsh/lib/utils/io:FZF_USER_INPUT as a *drop-in replacement* for
  the confusing FZF_HEAD and FZF_TAIL commands. Update by literally
  changing any instances of FZF_HEAD or FZF_TAIL with FZF_USER_INPUT
     - FZF_HEAD and FZF_TAIL will be removed in 4.2

- zsh/lib/utils/io:READ (and other zshbuiltin/read-based prompts) now
  accept a --force-user-input flag in case important checks should
  require an admin's approval. This flag will ensure that piped input
  and the `scwrypts -y` flag are ignored for the single prompt.

- zsh/lib/utils/color has been updated to use color names which match
  the ANSI color names

- zsh/hello-world has been reduced to a minimal example; this is to
  emphasize ease-of-use with v4

- zsh/sanity-check is a scwrypts/run testing helper and detailed
  starting reference (helpful since hello-world is now minimal)

- various refactor, updates, and improvements to the scwrypts runner

- migrated all zsh scwrypts and plugins to use v4 runner syntax
     - zsh
     - plugins/kubectl
     - plugins/ci

- refactored py/lib into py/lib/scwrypts (PyPi)

zx/lib/src/index.ts

@@ -0,0 +1,5 @@
+export * from './scwrypts/scwrypts.js';
+
+export { ScwryptsLogLevel } from './scwrypts/types.js';
+
+export type { ScwryptsOptions } from './scwrypts/types.js';

zx/lib/src/scwrypts/get-scwrypts-lookup.test.ts

@@ -0,0 +1,116 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { describe, expect, test, beforeEach, jest } from '@jest/globals';
+import { v4 as uuid } from 'uuid';
+
+import * as parseCLIArgs from './parse-cli-args.js';
+
+import { getScwryptsLookup, Errors } from './get-scwrypts-lookup.js';
+
+import type { ScwryptsOptions } from './types.js';
+
+let sample: any;
+beforeEach(() => {
+  sample = {
+    parsedCLIArgs: [uuid(), uuid(), uuid()],
+    spy: {},
+  };
+
+  sample.spy.parseCLIArgs = jest.spyOn(parseCLIArgs, 'parseCLIArgs');
+  sample.spy.parseCLIArgs.mockReturnValue(sample.parsedCLIArgs);
+});
+
+describe('exact', () => {
+  beforeEach(() => {
+    sample.exact = {
+      name: uuid(),
+      group: uuid(),
+      type: uuid(),
+    };
+  });
+
+  test('provides correct lookup', () => {
+    const lookup = getScwryptsLookup(sample.exact as ScwryptsOptions);
+
+    expect(lookup).toEqual({
+      method: 'exact',
+      ...sample.exact,
+    });
+  });
+
+  describe('throws error', () => {
+    test('when missing group', () => {
+      delete sample.exact.group;
+      try {
+        getScwryptsLookup(sample.exact as ScwryptsOptions);
+        expect(true).toBeFalsy();
+      } catch (error) {
+        expect(error).toEqual(Errors.MissingScwryptsExactLookupParametersError);
+      }
+    });
+
+    test('when missing type', () => {
+      delete sample.exact.type;
+      try {
+        getScwryptsLookup(sample.exact as ScwryptsOptions);
+        expect(true).toBeFalsy();
+      } catch (error) {
+        expect(error).toEqual(Errors.MissingScwryptsExactLookupParametersError);
+      }
+    });
+  });
+});
+
+describe('patterns', () => {
+  describe('list', () => {
+    let lookup: any;
+    beforeEach(() => {
+      sample.patterns = {
+        patterns: [uuid(), uuid(), uuid()],
+      };
+
+      lookup = getScwryptsLookup(sample.patterns as ScwryptsOptions);
+    });
+
+    test('provides correct lookup', () => {
+      expect(lookup).toEqual({
+        method: 'patterns',
+        patterns: sample.parsedCLIArgs,
+      });
+    });
+
+    test('parses patterns', () => {
+      expect(sample.spy.parseCLIArgs).toHaveBeenCalledWith(sample.patterns.patterns);
+    });
+  });
+
+  describe('string', () => {
+    let lookup: any;
+    beforeEach(() => {
+      sample.patterns = {
+        patterns: uuid(),
+      };
+
+      lookup = getScwryptsLookup(sample.patterns as ScwryptsOptions);
+    });
+
+    test('provides correct lookup', () => {
+      expect(lookup).toEqual({
+        method: 'patterns',
+        patterns: sample.parsedCLIArgs,
+      });
+    });
+
+    test('parses patterns', () => {
+      expect(sample.spy.parseCLIArgs).toHaveBeenCalledWith(sample.patterns.patterns);
+    });
+  });
+});
+
+test('throws error when missing name and patterns', () => {
+  try {
+    getScwryptsLookup({} as ScwryptsOptions);
+    expect(true).toBeFalsy();
+  } catch (error) {
+    expect(error).toEqual(Errors.NoScwryptsLookupError);
+  }
+});

zx/lib/src/scwrypts/get-scwrypts-lookup.ts

@@ -0,0 +1,49 @@
+import { parseCLIArgs } from './parse-cli-args.js';
+
+import type { ScwryptsOptions } from './types.js';
+
+export type ScwryptsLookupOptions =
+  | {
+      method: 'exact';
+      name: string;
+      group: string;
+      type: string;
+    }
+  | {
+      method: 'patterns';
+      patterns: string[];
+    };
+
+export const Errors = {
+  NoScwryptsLookupError: {
+    name: 'NoScwryptsLookupError',
+    message: 'no scwrypts lookup parameters provided',
+  },
+  MissingScwryptsExactLookupParametersError: {
+    name: 'MissingScwryptsExactLookupParametersError',
+    message: '"name" option requires "group" and "type" options',
+  },
+};
+
+export const getScwryptsLookup = (options: ScwryptsOptions): ScwryptsLookupOptions => {
+  if (options.name === undefined) {
+    if (options.patterns === undefined || options.patterns.length === 0) {
+      throw Errors.NoScwryptsLookupError;
+    }
+    return {
+      method: 'patterns',
+      patterns: parseCLIArgs(options.patterns),
+    };
+  }
+
+  if (options.group === undefined || options.type === undefined) {
+    throw Errors.MissingScwryptsExactLookupParametersError;
+  }
+
+  return {
+    method: 'exact',
+    name: options.name,
+    group: options.group,
+    type: options.type,
+  };
+};

zx/lib/src/scwrypts/parse-cli-args.test.ts

@@ -0,0 +1,32 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { describe, expect, test, beforeEach } from '@jest/globals';
+import { v4 as uuid } from 'uuid';
+
+import { parseCLIArgs } from './parse-cli-args.js';
+
+let sample: any;
+beforeEach(() => {
+  sample = {
+    args: [uuid(), uuid(), uuid()],
+  };
+
+  sample.argstring = sample.args.join(' ');
+});
+
+describe('undefined input', () => {
+  test('produces a string[]', () => {
+    expect(parseCLIArgs(undefined)).toEqual([]);
+  });
+});
+
+describe('string input', () => {
+  test('produces a string[]', () => {
+    expect(parseCLIArgs(sample.argstring)).toEqual(sample.args);
+  });
+});
+
+describe('string[] input', () => {
+  test('produces a string[]', () => {
+    expect(parseCLIArgs(sample.args)).toEqual(sample.args);
+  });
+});

zx/lib/src/scwrypts/parse-cli-args.ts

@@ -0,0 +1,12 @@
+export type CLIArgs = string | string[] | undefined;
+
+export const parseCLIArgs = (args: CLIArgs): string[] => {
+  switch (typeof args) {
+    case 'undefined':
+      return [];
+    case 'string':
+      return args.split(' ');
+    default:
+      return args;
+  }
+};

zx/lib/src/scwrypts/scwrypts.test.ts

@@ -0,0 +1,155 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { describe, expect, test, beforeEach, jest } from '@jest/globals';
+import { v4 as uuid } from 'uuid';
+
+import { execa } from 'execa';
+import * as Module_getScwryptsLookup from './get-scwrypts-lookup.js';
+import * as Module_parseCLIArgs from './parse-cli-args.js';
+import { ScwryptsLogLevel } from './types.js';
+
+import { scwrypts } from './scwrypts.js';
+
+jest.mock('execa', () => ({
+  execa: jest.fn(() => Promise.resolve()),
+}));
+
+const env = process.env;
+beforeEach(() => {});
+
+let sample: any;
+beforeEach(() => {
+  sample = {
+    options: {
+      name: uuid(),
+      group: uuid(),
+      type: uuid(),
+      patterns: [uuid(), uuid(), uuid()],
+      log_level: Math.floor(Math.random() * Object.keys(ScwryptsLogLevel).length),
+      args: uuid(),
+    },
+    lookup: {
+      exact: {
+        method: 'exact',
+        name: uuid(),
+        group: uuid(),
+        type: uuid(),
+      },
+      patterns: {
+        method: 'patterns',
+        patterns: [uuid(), uuid(), uuid()],
+      },
+    },
+    env: {
+      SCWRYPTS_EXECUTABLE: uuid(),
+    },
+    parsedCLIArgs: [uuid(), uuid(), uuid()],
+    spy: {},
+  };
+
+  sample.spy.getScwryptsLookup = jest.spyOn(Module_getScwryptsLookup, 'getScwryptsLookup');
+  sample.spy.getScwryptsLookup.mockReturnValue(sample.lookup.exact);
+
+  sample.spy.parseCLIArgs = jest.spyOn(Module_parseCLIArgs, 'parseCLIArgs');
+  sample.spy.parseCLIArgs.mockReturnValue(sample.parsedCLIArgs);
+
+  jest.resetModules();
+  process.env = {
+    ...env,
+    ...sample.env,
+  };
+});
+
+afterEach(() => {
+  process.env = { ...env };
+});
+
+describe('exact lookup', () => {
+  beforeEach(async () => {
+    sample.spy.getScwryptsLookup.mockReturnValue(sample.lookup.exact);
+    await scwrypts(sample.options);
+  });
+
+  test('gets the correct lookup', () => {
+    expect(sample.spy.getScwryptsLookup).toHaveBeenCalledWith(sample.options);
+  });
+
+  test('parses arguments correctly', () => {
+    expect(sample.spy.parseCLIArgs).toHaveBeenCalledWith(sample.options.args);
+  });
+
+  test('calls the correct scwrypt', () => {
+    expect(execa).toHaveBeenCalledWith(sample.env.SCWRYPTS_EXECUTABLE, [
+      '--name',
+      sample.lookup.exact.name,
+      '--group',
+      sample.lookup.exact.group,
+      '--type',
+      sample.lookup.exact.type,
+      '--log-level',
+      sample.options.log_level.toString(),
+      '--',
+      ...sample.parsedCLIArgs,
+    ]);
+  });
+});
+
+describe('patterns lookup', () => {
+  beforeEach(async () => {
+    sample.spy.getScwryptsLookup.mockReturnValue(sample.lookup.patterns);
+    await scwrypts(sample.options);
+  });
+
+  test('gets the correct lookup', () => {
+    expect(sample.spy.getScwryptsLookup).toHaveBeenCalledWith(sample.options);
+  });
+
+  test('parses arguments correctly', () => {
+    expect(sample.spy.parseCLIArgs).toHaveBeenCalledWith(sample.options.args);
+  });
+
+  test('calls the correct scwrypt', () => {
+    expect(execa).toHaveBeenCalledWith(sample.env.SCWRYPTS_EXECUTABLE, [
+      ...sample.lookup.patterns.patterns,
+      '--log-level',
+      sample.options.log_level.toString(),
+      '--',
+      ...sample.parsedCLIArgs,
+    ]);
+  });
+});
+
+test('omits --log-level arguments if not provided', async () => {
+  delete sample.options.log_level;
+
+  await scwrypts(sample.options);
+
+  expect(execa).toHaveBeenCalledWith(sample.env.SCWRYPTS_EXECUTABLE, [
+    '--name',
+    sample.lookup.exact.name,
+    '--group',
+    sample.lookup.exact.group,
+    '--type',
+    sample.lookup.exact.type,
+    '--',
+    ...sample.parsedCLIArgs,
+  ]);
+});
+
+test('uses default scwrypts executable SCWRYPTS_EXECUTABLE is not provided', async () => {
+  delete process.env.SCWRYPTS_EXECUTABLE;
+
+  await scwrypts(sample.options);
+
+  expect(execa).toHaveBeenCalledWith('scwrypts', [
+    '--name',
+    sample.lookup.exact.name,
+    '--group',
+    sample.lookup.exact.group,
+    '--type',
+    sample.lookup.exact.type,
+    '--log-level',
+    sample.options.log_level.toString(),
+    '--',
+    ...sample.parsedCLIArgs,
+  ]);
+});

zx/lib/src/scwrypts/scwrypts.ts

@@ -0,0 +1,31 @@
+import { execa } from 'execa';
+
+import { getScwryptsLookup } from './get-scwrypts-lookup.js';
+import { parseCLIArgs } from './parse-cli-args.js';
+
+import type { ScwryptsOptions } from './types.js';
+
+export const scwrypts = async (options: ScwryptsOptions) => {
+  const lookup = getScwryptsLookup(options);
+
+  const scwryptsExecutableArgs: string[] = [];
+
+  switch (lookup.method) {
+    case 'exact':
+      scwryptsExecutableArgs.push('--name', lookup.name, '--group', lookup.group, '--type', lookup.type);
+      break;
+    case 'patterns':
+      scwryptsExecutableArgs.push(...lookup.patterns);
+      break;
+  }
+
+  if (options.log_level !== undefined) {
+    scwryptsExecutableArgs.push('--log-level', options.log_level.toString());
+  }
+
+  return await execa(process.env.SCWRYPTS_EXECUTABLE || 'scwrypts', [
+    ...scwryptsExecutableArgs,
+    '--',
+    ...parseCLIArgs(options.args),
+  ]);
+};

zx/lib/src/scwrypts/types.ts

@@ -0,0 +1,16 @@
+export type ScwryptsOptions = {
+  name: string | undefined;
+  group: string | undefined;
+  type: string | undefined;
+  patterns: string[] | undefined;
+  log_level: ScwryptsLogLevel | undefined;
+  args: string | string[] | undefined;
+};
+
+export enum ScwryptsLogLevel {
+  SILENT = 0,
+  QUIET = 1,
+  NORMAL = 2,
+  WARNING = 3,
+  DEBUG = 4,
+}