@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/iac/index.js

@@ -0,0 +1,258 @@
+import YAML from 'yaml';
+
+// src/iac/utils/patch-utils.ts
+var DEFAULT_MERGE_STRATEGY = "transpose";
+var getValuePathString = (valuePathArray = []) => valuePathArray.map((p) => encodeURIComponent(p)).join("/");
+var getValuePathArray = (valuePathString = "") => valuePathString.split("/").map((p) => decodeURIComponent(p));
+var isConstructedFrom = (value, constructorReference) => value !== null && typeof value === "object" && "constructor" in value && value.constructor === constructorReference;
+var mergeValues = (valuePathArray = [], existingValue, newValue, mergeStrategyMap = {}) => {
+  const valuePathString = getValuePathString(valuePathArray);
+  const arrayIndexWildcardValuePathString = getValuePathString(
+    valuePathArray.map((p) => typeof p === "number" ? "#" : p)
+  );
+  const {
+    [valuePathString]: {
+      strategy: specificKeyMergeStrategy = DEFAULT_MERGE_STRATEGY,
+      data: specificKeyMergeStrategyData = void 0
+    } = {},
+    [arrayIndexWildcardValuePathString]: {
+      strategy: arrayIndexWildcardMergeStrategy = DEFAULT_MERGE_STRATEGY,
+      data: arrayIndexWildcardMergeStrategyData = void 0
+    } = {}
+  } = mergeStrategyMap;
+  const mergeStrategy = valuePathString in mergeStrategyMap ? specificKeyMergeStrategy : arrayIndexWildcardMergeStrategy;
+  const mergeStrategyData = valuePathString in mergeStrategyMap ? specificKeyMergeStrategyData : arrayIndexWildcardMergeStrategyData;
+  let mergedValue = typeof newValue !== "undefined" ? newValue : existingValue;
+  if (mergeStrategy !== "replace") {
+    if (isConstructedFrom(existingValue, Array) && isConstructedFrom(newValue, Array)) {
+      if (mergeStrategy === "accumulate") {
+        mergedValue = [...existingValue, ...newValue];
+      } else if (mergeStrategy === "accumulate-unique") {
+        mergedValue = [
+          ...existingValue,
+          ...newValue.filter((item) => existingValue.indexOf(item) === -1)
+        ];
+      } else if (mergeStrategy === "accumulate-unique-by") {
+        const existingItemMap = {};
+        const newItemMap = {};
+        for (let i = 0; i < existingValue.length; i++) {
+          const existingItem = existingValue[i];
+          if (existingItem && typeof existingItem === "object") {
+            const identifier = mergeStrategyData instanceof Function ? mergeStrategyData(existingItem) : existingItem[mergeStrategyData];
+            existingItemMap[identifier] = existingItem;
+          }
+        }
+        for (let j = 0; j < newValue.length; j++) {
+          const newItem = newValue[j];
+          if (newItem && typeof newItem === "object") {
+            const identifier = mergeStrategyData instanceof Function ? mergeStrategyData(newItem) : newItem[mergeStrategyData];
+            newItemMap[identifier] = newItem;
+          }
+        }
+        mergedValue = Object.keys({
+          ...existingItemMap,
+          ...newItemMap
+        }).map(
+          (id, index) => mergeValues(
+            [...valuePathArray, index],
+            existingItemMap[id],
+            newItemMap[id],
+            mergeStrategyMap
+          )
+        );
+      } else if (mergeStrategy === "transpose") {
+        const fullLength = Math.max(existingValue.length, newValue.length);
+        mergedValue = [...new Array(fullLength)].map(
+          (_empty, index) => mergeValues(
+            [...valuePathArray, index],
+            existingValue[index],
+            newValue[index],
+            mergeStrategyMap
+          )
+        );
+      }
+    } else if (isConstructedFrom(existingValue, Object) && isConstructedFrom(newValue, Object)) {
+      mergedValue = Object.keys({ ...existingValue, ...newValue }).reduce(
+        (acc, k) => ({
+          ...acc,
+          [k]: mergeValues(
+            [...valuePathArray, k],
+            existingValue[k],
+            newValue[k],
+            mergeStrategyMap
+          )
+        }),
+        {}
+      );
+    }
+  }
+  return mergedValue;
+};
+
+// src/iac/utils/index.ts
+var addParameter = (parameterInfo, template) => {
+  const { ParameterId, Parameter, Label, Group } = parameterInfo;
+  const {
+    Parameters,
+    Metadata: {
+      "AWS::CloudFormation::Interface": {
+        ParameterGroups = [],
+        ParameterLabels = {}
+      } = {}
+    } = {}
+  } = template;
+  let NewParameterGroups = ParameterGroups;
+  if (Group) {
+    const GroupObject = ParameterGroups.filter(
+      (g) => g.Label?.default === Group
+    )[0];
+    NewParameterGroups = GroupObject ? ParameterGroups.map(
+      (g) => g.Label?.default === Group ? {
+        ...g,
+        Parameters: [...g.Parameters || [], ParameterId]
+      } : g
+    ) : [
+      ...ParameterGroups,
+      {
+        Label: {
+          default: Group
+        },
+        Parameters: [ParameterId]
+      }
+    ];
+  }
+  return {
+    ...template,
+    Parameters: {
+      ...Parameters,
+      [ParameterId]: Parameter
+    },
+    Metadata: {
+      ...template.Metadata,
+      "AWS::CloudFormation::Interface": {
+        ...template?.Metadata?.["AWS::CloudFormation::Interface"],
+        ParameterGroups: NewParameterGroups,
+        ParameterLabels: {
+          ...ParameterLabels,
+          [ParameterId]: {
+            default: Label
+          }
+        }
+      }
+    }
+  };
+};
+var addParameters = (parameters, template) => parameters.reduce((acc, p) => addParameter(p, acc), template);
+var patchTemplate = (patch, template) => mergeValues([], template, patch, {
+  [getValuePathString([
+    // Parameter Groups
+    "Metadata",
+    "AWS::CloudFormation::Interface",
+    "ParameterGroups"
+  ])]: {
+    strategy: "accumulate-unique-by",
+    data: (pG) => pG?.Label?.default
+  },
+  [getValuePathString([
+    // Parameter Group Parameter Ids
+    "Metadata",
+    "AWS::CloudFormation::Interface",
+    "ParameterGroups",
+    "#",
+    "Parameters"
+  ])]: {
+    strategy: "accumulate-unique"
+  }
+});
+var createResourcePack = (creator) => (params, template) => {
+  const patch = creator(params);
+  return patchTemplate(patch, template);
+};
+var SimpleCFT = class {
+  /**
+   * Create a SimpleCFT template wrapper.
+   *
+   * @param template - Initial CloudFormation template.
+   */
+  constructor(template = {
+    AWSTemplateFormatVersion: "2010-09-09"
+  }) {
+    this.template = template;
+  }
+  /**
+   * Apply a pack with configuration to the stack template.
+   * @see `@resistdesign/voltra/iac` and `@resistdesign/voltra/iac/packs` for examples.
+   * */
+  applyPack = (pack, params) => {
+    this.template = pack(params, this.template);
+    return this;
+  };
+  /**
+   * Apply a patch to the stack template.
+   *
+   * @param patch - Template patch to merge.
+   * */
+  patch = (patch) => {
+    this.template = patchTemplate(patch, this.template);
+    return this;
+  };
+  /**
+   * Add a stack parameter including its descriptive info and an optional parameter group.
+   *
+   * @param parameter - Parameter definition and metadata.
+   * */
+  addParameter = (parameter) => {
+    this.template = addParameter(parameter, this.template);
+    return this;
+  };
+  /**
+   * Add a group of stack parameters including their descriptive info and an optional parameter group.
+   *
+   * @param group - Parameter group definition.
+   * */
+  addParameterGroup = ({ Label: Group, Parameters }) => {
+    const parameterIds = Object.keys(Parameters);
+    const parameterList = parameterIds.map((ParameterId) => {
+      const { Label, ...Parameter } = Parameters[ParameterId];
+      return {
+        Group,
+        ParameterId,
+        Label,
+        Parameter
+      };
+    });
+    this.template = addParameters(parameterList, this.template);
+    return this;
+  };
+  /**
+   * Use a modification to dynamically apply various changes at once.
+   *
+   * @param modification - Modification callback to apply.
+   * */
+  modify = (modification) => {
+    modification(this);
+    return this;
+  };
+  /**
+   * Convert the stack template to a string.
+   *
+   * @returns JSON string representation of the template.
+   * */
+  toString = () => JSON.stringify(this.template, null, 2);
+  /**
+   * Convert the stack template to a JSON object.
+   *
+   * @returns Template JSON object.
+   * */
+  toJSON = () => this.template;
+  /**
+   * Convert the stack template to a YAML string.
+   *
+   * @returns YAML string representation of the template.
+   * */
+  toYAML = () => YAML.stringify(this.template, {
+    aliasDuplicateObjects: false
+  });
+};
+
+export { DEFAULT_MERGE_STRATEGY, SimpleCFT, addParameter, addParameters, createResourcePack, getValuePathArray, getValuePathString, isConstructedFrom, mergeValues, patchTemplate };

package/iac/packs/auth/user-management.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Configuration for adding Cognito user management resources.
+ */
+type AddUserManagementConfigBase = {
+    /**
+     * Base id for Cognito resources.
+     */
+    id: string;
+    /**
+     * IAM role name for authenticated users.
+     */
+    authRoleName: string;
+    /**
+     * IAM role name for unauthenticated users.
+     */
+    unauthRoleName: string;
+    /**
+     * OAuth callback URLs.
+     */
+    callbackUrls?: any[];
+    /**
+     * OAuth logout URLs.
+     */
+    logoutUrls?: any[];
+    /**
+     * Alias target DNS name for the base domain record.
+     */
+    baseDomainRecordAliasTargetDNSName?: any;
+    /**
+     * API Gateway REST API id for authenticated access.
+     */
+    apiGatewayRESTAPIId?: any;
+    /**
+     * API Gateway stage name for authenticated access.
+     */
+    apiStageName?: any;
+};
+type AddUserManagementConfigWithDomain = AddUserManagementConfigBase & {
+    /**
+     * Enable a custom Cognito user pool domain and associated Route53 records.
+     *
+     * Defaults to `true`.
+     */
+    enableUserPoolDomain?: true;
+    /**
+     * Base domain name for the user pool.
+     */
+    domainName: any;
+    /**
+     * Hosted zone id for DNS records.
+     */
+    hostedZoneId: any;
+    /**
+     * SSL certificate ARN for the user pool domain.
+     */
+    sslCertificateArn: any;
+};
+type AddUserManagementConfigWithoutDomain = AddUserManagementConfigBase & {
+    /**
+     * Disable custom Cognito user pool domain resources.
+     */
+    enableUserPoolDomain: false;
+    domainName?: never;
+    hostedZoneId?: never;
+    sslCertificateArn?: never;
+    baseDomainRecordAliasTargetDNSName?: never;
+};
+/**
+ * Configuration for {@link addUserManagement}.
+ */
+export type AddUserManagementConfig = AddUserManagementConfigWithDomain | AddUserManagementConfigWithoutDomain;
+/**
+ * Add Cognito user management resources to a template.
+ *
+ * @param config - User management configuration.
+ * @returns CloudFormation template fragment.
+ * @group Resource Packs
+ */
+export declare const addUserManagement: import("../..").ResourcePackApplier<AddUserManagementConfig>;
+export {};

package/iac/packs/auth.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Configuration for the auth pack.
+ */
+type AddAuthConfigBase = {
+    /**
+     * Cognito user pool resource id.
+     */
+    userManagementId: string;
+    /**
+     * IAM role name for authenticated users.
+     */
+    authRoleName: string;
+    /**
+     * IAM role name for unauthenticated users.
+     */
+    unauthRoleName: string;
+    /**
+     * API Gateway REST API id for the backend.
+     */
+    apiCloudFunctionGatewayId: string;
+    /**
+     * API Gateway stage name for the backend.
+     */
+    apiStageName: string;
+    /**
+     * Resource id for the admin group.
+     */
+    adminGroupId: string;
+    /**
+     * Cognito group name for admins.
+     */
+    userManagementAdminGroupName: string;
+    /**
+     * OAuth callback URLs.
+     */
+    callbackUrls: any[];
+    /**
+     * OAuth logout URLs.
+     */
+    logoutUrls: any[];
+};
+type AddAuthConfigWithUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Enable a custom Cognito user pool domain and associated Route53 records.
+     *
+     * Defaults to `true`.
+     */
+    enableUserPoolDomain?: true;
+    /**
+     * Parameter name for Route53 hosted zone id.
+     */
+    hostedZoneIdParameterName: string;
+    /**
+     * Parameter name for base domain.
+     */
+    domainNameParameterName: string;
+    /**
+     * SSL certificate resource id for the user pool domain.
+     */
+    sslCertificateId: string;
+    /**
+     * CloudFront distribution id for the main CDN.
+     */
+    mainCDNCloudFrontId: string;
+};
+type AddAuthConfigWithoutUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Disable custom Cognito user pool domain resources.
+     */
+    enableUserPoolDomain: false;
+    hostedZoneIdParameterName?: never;
+    domainNameParameterName?: never;
+    sslCertificateId?: never;
+    mainCDNCloudFrontId?: never;
+};
+/**
+ * Configuration for {@link addAuth}.
+ */
+export type AddAuthConfig = AddAuthConfigWithUserPoolDomain | AddAuthConfigWithoutUserPoolDomain;
+/**
+ * Add auth resources including user management and an admin group.
+ *
+ * @group Resource Packs
+ */
+export declare const addAuth: import("..").ResourcePackApplier<AddAuthConfig>;
+export {};

package/iac/packs/build/utils.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Require at least one key from the provided type.
+ *
+ * @typeParam T - Base object type.
+ * @typeParam U - Helper mapped type.
+ */
+export type AtLeastOne<T, U = {
+    [K in keyof T]: Pick<T, K>;
+}> = Partial<T> & U[keyof U];
+/**
+ * Helper functions for generating CLI commands in build specs.
+ */
+export declare const COMMAND_HELPERS: {
+    updateFunction: ({ cloudFunctionArn, codeZipFilePath, }: {
+        cloudFunctionArn: string;
+        codeZipFilePath: string;
+    }) => string;
+    copyDirectoryToS3: ({ s3Domain, directoryPath, }: {
+        s3Domain: string;
+        directoryPath: string;
+    }) => string;
+    cloudFrontInvalidation: ({ cloudFrontDistributionId, pathsToInvalidate, }: {
+        cloudFrontDistributionId: string;
+        pathsToInvalidate?: string[];
+    }) => string;
+    addNPMTokenWithNPMRC: ({ npmToken }: {
+        npmToken: string;
+    }) => string;
+};
+/**
+ * Linux user name string.
+ */
+export type LinuxUserNameString = string;
+/**
+ * Flag value for yes/no configuration fields.
+ */
+export type YesOrNo = "yes" | "no";
+/**
+ * BuildSpec environment configuration.
+ */
+export interface Env {
+    /**
+     * Shell to use for command execution.
+     */
+    shell?: "bash" | "/bin/sh" | "powershell.exe" | "cmd.exe" | string;
+    /**
+     * Environment variables to expose.
+     */
+    variables?: Record<string, string>;
+    /**
+     * SSM parameter store references.
+     */
+    "parameter-store"?: Record<string, string>;
+    /**
+     * Exported variable names.
+     */
+    "exported-variables"?: string[];
+    /**
+     * Secrets Manager references.
+     */
+    "secrets-manager"?: Record<string, `${string}:${string}:${string}:${string}`>;
+    /**
+     * Whether to enable git credential helper.
+     */
+    "git-credential-helper"?: YesOrNo;
+}
+/**
+ * BuildSpec proxy configuration.
+ */
+export interface Proxy {
+    /**
+     * Whether to upload build artifacts via proxy.
+     */
+    "upload-artifacts"?: YesOrNo;
+    /**
+     * Whether to proxy logs.
+     */
+    logs?: YesOrNo;
+}
+/**
+ * BuildSpec batch build configuration.
+ */
+export interface Batch {
+    /**
+     * Whether to fail fast for batch builds.
+     */
+    "fast-fail"?: boolean;
+    /**
+     * Batch build list config.
+     */
+    "build-list"?: any;
+    /**
+     * Batch build matrix config.
+     */
+    "build-matrix"?: any;
+    /**
+     * Batch build graph config.
+     */
+    "build-graph"?: any;
+    [key: string]: any;
+}
+/**
+ * BuildSpec phase configuration.
+ */
+export interface Phase {
+    /**
+     * Runtime versions for this phase.
+     */
+    "runtime-versions"?: Record<string, any>;
+    /**
+     * User to run commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Behavior when a command fails.
+     */
+    "on-failure"?: "ABORT" | "CONTINUE";
+    /**
+     * Commands to run during the phase.
+     */
+    commands: string[];
+    /**
+     * Commands to always run at the end of the phase.
+     */
+    finally?: string[];
+}
+/**
+ * BuildSpec phase collection (at least one phase required).
+ */
+export type PhaseConfig = AtLeastOne<{
+    install: Phase;
+    pre_build: Phase;
+    build: Phase;
+    post_build: Phase;
+}>;
+/**
+ * Report group configuration for build reports.
+ */
+export interface ReportGroupNameOrArn {
+    /**
+     * Report files to include.
+     */
+    files?: string[];
+    /**
+     * Base directory for report files.
+     */
+    "base-directory"?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Report file format.
+     */
+    "file-format"?: string;
+}
+/**
+ * Reports configuration for BuildSpec.
+ */
+export interface Reports {
+    /**
+     * Report group name or ARN.
+     */
+    "report-group-name-or-arn"?: ReportGroupNameOrArn;
+}
+/**
+ * Artifact identifier configuration.
+ */
+export interface ArtifactIdentifier {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+}
+/**
+ * Secondary artifacts configuration.
+ */
+export interface SecondaryArtifacts {
+    /**
+     * Artifact identifier for secondary artifacts.
+     */
+    artifactIdentifier?: ArtifactIdentifier;
+}
+/**
+ * Artifacts configuration for BuildSpec.
+ */
+export interface Artifacts {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+    /**
+     * Paths to exclude from artifacts.
+     */
+    "exclude-paths"?: string;
+    /**
+     * Whether to enable symlinks in artifacts.
+     */
+    "enable-symlinks"?: string;
+    /**
+     * S3 prefix for artifact upload.
+     */
+    "s3-prefix"?: string;
+    /**
+     * Secondary artifacts configuration.
+     */
+    "secondary-artifacts"?: SecondaryArtifacts;
+}
+/**
+ * Cache configuration for BuildSpec.
+ */
+export interface Cache {
+    /**
+     * Cache paths to persist between builds.
+     */
+    paths?: string[];
+}
+/**
+ * BuildSpec configuration object.
+ */
+export interface BuildSpec {
+    /**
+     * Build spec version.
+     */
+    version?: number;
+    /**
+     * User to run build commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Environment configuration.
+     */
+    env?: Env;
+    /**
+     * Proxy configuration.
+     */
+    proxy?: Proxy;
+    /**
+     * Batch build configuration.
+     */
+    batch?: Batch;
+    /**
+     * Build phases configuration.
+     */
+    phases: PhaseConfig;
+    /**
+     * Reports configuration.
+     */
+    reports?: Reports;
+    /**
+     * Artifacts configuration.
+     */
+    artifacts?: Artifacts;
+    /**
+     * Cache configuration.
+     */
+    cache?: Cache;
+}
+/**
+ * Create a build spec YAML string for a build pipeline (CI/CD).
+ *
+ * @param config - Build spec configuration.
+ * @returns YAML string for the build spec.
+ */
+export declare const createBuildSpec: ({ version, phases }: BuildSpec) => string;