serverless-bedrock-agentcore-plugin 0.1.0

package/src/utils/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const naming = require('./naming');
+const tags = require('./tags');
+
+module.exports = {
+  ...naming,
+  ...tags,
+};

package/src/utils/naming.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Generate a resource name following the pattern: {service}-{name}-{stage}
+ *
+ * @param {string} serviceName - The Serverless service name
+ * @param {string} name - The agent/resource name
+ * @param {string} stage - The deployment stage
+ * @returns {string} The generated resource name
+ */
+function getResourceName(serviceName, name, stage) {
+  // AgentCore names have pattern: [a-zA-Z][a-zA-Z0-9_]{0,47}
+  // Replace hyphens with underscores and ensure it starts with a letter
+  const baseName = `${serviceName}_${name}_${stage}`
+    .replace(/-/g, '_')
+    .replace(/[^a-zA-Z0-9_]/g, '');
+
+  // Ensure it starts with a letter
+  const safeName = /^[a-zA-Z]/.test(baseName) ? baseName : `A${baseName}`;
+
+  // Truncate to max 48 characters
+  return safeName.substring(0, 48);
+}
+
+/**
+ * Generate a CloudFormation logical ID from the agent name and resource type
+ *
+ * @param {string} name - The agent name
+ * @param {string} resourceType - The resource type (e.g., 'Runtime', 'Memory')
+ * @returns {string} The CloudFormation logical ID
+ */
+function getLogicalId(name, resourceType) {
+  // Convert to PascalCase and remove invalid characters
+  const pascalName = name
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+
+  return `${pascalName}${resourceType}`;
+}
+
+/**
+ * Generate a CloudFormation logical ID for nested resources
+ *
+ * @param {string} parentName - The parent resource name
+ * @param {string} childName - The child resource name
+ * @param {string} resourceType - The resource type
+ * @returns {string} The CloudFormation logical ID
+ */
+function getNestedLogicalId(parentName, childName, resourceType) {
+  const pascalParent = parentName
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+
+  const pascalChild = childName
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+
+  return `${pascalParent}${pascalChild}${resourceType}`;
+}
+
+/**
+ * Sanitize a name for use in CloudFormation
+ *
+ * @param {string} name - The name to sanitize
+ * @returns {string} The sanitized name
+ */
+function sanitizeName(name) {
+  return name.replace(/[^a-zA-Z0-9]/g, '');
+}
+
+module.exports = {
+  getResourceName,
+  getLogicalId,
+  getNestedLogicalId,
+  sanitizeName,
+};

package/src/utils/tags.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Merge tags from multiple sources with proper precedence
+ *
+ * @param {Object} defaultTags - Default tags from custom.agentCore.defaultTags
+ * @param {Object} resourceTags - Tags specific to the resource
+ * @param {string} serviceName - The Serverless service name
+ * @param {string} stage - The deployment stage
+ * @param {string} resourceName - The resource name
+ * @returns {Object} Merged tags object for CloudFormation
+ */
+function mergeTags(defaultTags = {}, resourceTags = {}, serviceName, stage, resourceName) {
+  const tags = {
+    ...defaultTags,
+    ...resourceTags,
+    'serverless:service': serviceName,
+    'serverless:stage': stage,
+    'agentcore:resource': resourceName,
+  };
+
+  return tags;
+}
+
+/**
+ * Convert tags object to CloudFormation Tags array format
+ *
+ * @param {Object} tags - Tags object with key-value pairs
+ * @returns {Array} Array of {Key, Value} objects for CloudFormation
+ */
+function tagsToCloudFormationArray(tags) {
+  return Object.entries(tags).map(([Key, Value]) => ({
+    Key,
+    Value: String(Value),
+  }));
+}
+
+/**
+ * Convert CloudFormation Tags array to object format
+ *
+ * @param {Array} tagsArray - Array of {Key, Value} objects
+ * @returns {Object} Tags object with key-value pairs
+ */
+function cloudFormationArrayToTags(tagsArray) {
+  return tagsArray.reduce((acc, { Key, Value }) => {
+    acc[Key] = Value;
+
+    return acc;
+  }, {});
+}
+
+module.exports = {
+  mergeTags,
+  tagsToCloudFormationArray,
+  cloudFormationArrayToTags,
+};

package/src/validators/schema.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * Define JSON Schema validation for the 'agents' top-level configuration
+ *
+ * @param {Object} serverless - The Serverless instance
+ */
+function defineAgentsSchema(serverless) {
+  // Define the 'agents' top-level property
+  serverless.configSchemaHandler.defineTopLevelProperty('agents', {
+    type: 'object',
+    additionalProperties: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['runtime', 'memory', 'gateway', 'browser', 'codeInterpreter', 'workloadIdentity'],
+        },
+        description: {
+          type: 'string',
+          minLength: 1,
+          maxLength: 1200,
+        },
+        tags: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+        },
+        roleArn: {
+          type: 'string',
+          pattern: '^arn:aws(-[^:]+)?:iam::([0-9]{12})?:role/.+$',
+        },
+
+        // Runtime-specific properties
+        artifact: {
+          type: 'object',
+          properties: {
+            containerImage: { type: 'string' },
+            s3: {
+              type: 'object',
+              properties: {
+                bucket: { type: 'string' },
+                key: { type: 'string' },
+              },
+              required: ['bucket', 'key'],
+            },
+          },
+        },
+        protocol: {
+          type: 'string',
+          enum: ['HTTP', 'MCP', 'A2A'],
+        },
+        environment: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+        },
+        network: {
+          type: 'object',
+          properties: {
+            networkMode: {
+              type: 'string',
+              enum: ['PUBLIC', 'VPC'],
+            },
+            vpcConfig: {
+              type: 'object',
+              properties: {
+                subnetIds: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+                securityGroupIds: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+        authorizer: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['CUSTOM_JWT', 'AWS_IAM', 'NONE'],
+            },
+            jwtConfiguration: {
+              type: 'object',
+              properties: {
+                issuer: { type: 'string' },
+                audience: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+        lifecycle: {
+          type: 'object',
+          properties: {
+            idleTimeout: { type: 'number' },
+            maxConcurrency: { type: 'number' },
+          },
+        },
+        endpoints: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              version: { type: 'string' },
+              description: { type: 'string' },
+            },
+          },
+        },
+
+        // Memory-specific properties
+        eventExpiryDuration: {
+          type: 'number',
+          minimum: 7,
+          maximum: 365,
+        },
+        encryptionKeyArn: {
+          type: 'string',
+        },
+        strategies: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['semantic', 'userPreference', 'summary', 'custom'],
+              },
+              name: { type: 'string' },
+              namespaces: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+              configuration: {
+                type: 'object',
+              },
+            },
+            required: ['type', 'name'],
+          },
+        },
+
+        // Gateway-specific properties
+        authorizerType: {
+          type: 'string',
+          enum: ['AWS_IAM', 'CUSTOM_JWT'],
+        },
+        protocolType: {
+          type: 'string',
+          enum: ['MCP'],
+        },
+        authorizerConfiguration: {
+          type: 'object',
+          properties: {
+            allowedAudiences: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+            allowedClients: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+            allowedIssuers: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+          },
+        },
+        kmsKeyArn: {
+          type: 'string',
+        },
+        targets: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              type: {
+                type: 'string',
+                enum: ['openapi', 'lambda', 'smithy'],
+              },
+              description: { type: 'string' },
+              functionArn: { type: 'string' },
+              functionName: { type: 'string' },
+              s3: {
+                type: 'object',
+                properties: {
+                  bucket: { type: 'string' },
+                  key: { type: 'string' },
+                },
+              },
+              credentialProvider: {
+                type: 'object',
+                properties: {
+                  type: {
+                    type: 'string',
+                    enum: ['GATEWAY_IAM_ROLE', 'OAUTH', 'API_KEY'],
+                  },
+                  oauthConfig: {
+                    type: 'object',
+                    properties: {
+                      secretArn: { type: 'string' },
+                      tokenUrl: { type: 'string' },
+                      scopes: {
+                        type: 'array',
+                        items: { type: 'string' },
+                      },
+                    },
+                  },
+                  apiKeyConfig: {
+                    type: 'object',
+                    properties: {
+                      secretArn: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+            required: ['name'],
+          },
+        },
+      },
+      required: ['type'],
+    },
+  });
+
+  // Define custom.agentCore configuration
+  serverless.configSchemaHandler.defineCustomProperties({
+    type: 'object',
+    properties: {
+      agentCore: {
+        type: 'object',
+        properties: {
+          defaultTags: {
+            type: 'object',
+            additionalProperties: { type: 'string' },
+          },
+        },
+      },
+    },
+  });
+}
+
+module.exports = {
+  defineAgentsSchema,
+};