serverless-plugin-module-registry 1.0.4 → 1.0.8

package/README.md

@@ -120,6 +120,10 @@ The plugin creates an **intermodular** `ModuleRegistry` table using **AWS SDK v3
 - **GSI1PK**: `MODULES` (for listing all modules)
 - **GSI1SK**: `MODULE#{moduleName}` (for grouping by module)
 
+### Global Secondary Index (GSI2)
+- **GSI2PK**: `FEATURES` (for listing all features)
+- **GSI2SK**: `FEATURE#{featureId}` (for direct feature lookup by ID)
+
 ### Data Structure
 ```json
 {
@@ -188,6 +192,19 @@ const feature = await dynamoClient.getItem({
 })
 ```
 
+### Get Feature by ID (GSI2)
+```javascript
+// Query GSI2 with featureId
+const feature = await dynamoClient.query({
+  IndexName: 'GSI2',
+  KeyConditionExpression: 'GSI2PK = :pk AND GSI2SK = :sk',
+  ExpressionAttributeValues: {
+    ':pk': 'FEATURES',
+    ':sk': `FEATURE#${featureId}`
+  }
+})
+```
+
 ## ⚙️ Configuration Options
 
 | Option | Type | Default | Description |
@@ -262,15 +279,15 @@ Example output:
 
 ### TypeScript/ES6 Imports
 ```typescript
-// In your handlers
-import { 
-  listAllModules, 
-  getModuleFeatures, 
+// In your handlers - import from the generated service package
+import {
+  listAllModules,
+  getModuleFeatures,
   getFeatureDetails,
   createModuleRegistryLogger,
   type ModuleInfo,
   type FeatureInfo
-} from 'serverless-plugin-module-registry'
+} from 'module-registry'
 
 const logger = createModuleRegistryLogger('my-handler')
 
@@ -279,16 +296,28 @@ export const myHandler = async (event: any) => {
   logger.info(`Found ${modules.length} modules`)
   return { modules }
 }
+
+// Example: Get feature by ID without knowing module
+export const getFeatureHandler = async (event: any) => {
+  const { featureId } = event.pathParameters
+  const feature = await getFeatureById(featureId)
+  
+  if (!feature) {
+    return { statusCode: 404, body: { error: 'Feature not found' } }
+  }
+  
+  return { statusCode: 200, body: feature }
+}
 ```
 
 ### CommonJS/Node.js Require
 ```javascript
-// In your handlers
-const { 
-  listAllModules, 
-  getModuleFeatures, 
-  createModuleRegistryLogger 
-} = require('serverless-plugin-module-registry')
+// In your handlers - require from the generated service package
+const {
+  listAllModules,
+  getModuleFeatures,
+  createModuleRegistryLogger
+} = require('module-registry')
 
 const logger = createModuleRegistryLogger('my-handler')
 
@@ -306,6 +335,7 @@ exports.myHandler = async (event) => {
 | `listAllModules()` | List all deployed modules | `Promise<ModuleInfo[]>` |
 | `getModuleFeatures(moduleName)` | Get features for a module | `Promise<FeatureInfo[]>` |
 | `getFeatureDetails(moduleName, featureName)` | Get feature details | `Promise<FeatureDetails \| null>` |
+| `getFeatureById(featureId)` | Get feature by ID only (uses GSI2) | `Promise<FeatureDetails \| null>` |
 | `getModuleMetadata(moduleName)` | Get module metadata only | `Promise<ModuleInfo \| null>` |
 | `getAllEndpoints()` | Get all endpoints across modules | `Promise<EndpointInfo[]>` |
 | `createModuleRegistryLogger(context)` | Create logger for service functions | `Logger` |
@@ -351,6 +381,222 @@ export const listModules = http(async (event) => {
 })
 ```
 
+## 🚀 CLI Commands
+
+The plugin provides powerful CLI commands for managing module registries:
+
+### Generate Registry with AI (`registryGenerate`)
+
+Automatically generate registry files for a module using AI analysis:
+
+```bash
+# Generate registry for a specific module
+serverless registryGenerate --module workforce
+
+# Force overwrite existing registry files
+serverless registryGenerate --module workforce --force
+```
+
+**Prerequisites:**
+- Set `OPENROUTER_API_KEY` environment variable for AI generation
+- Module must have function descriptions in serverless function definitions
+- Only functions with `aws_iam` authorizer are included in registry
+
+**What it does:**
+1. Analyzes module structure (functions, resources, endpoints)
+2. Uses AI (Claude 3.5 Sonnet) to generate AWS-style feature groupings
+3. Creates `registry/module.yml` and `registry/features/*.yml` files
+4. Follows AWS IAM naming conventions (e.g., `EmployeeReadAccess`, `UserSelfService`)
+
+### Generate Service Package (`registryGeneratePackage`)
+
+Generate the virtual service package for importing registry functions:
+
+```bash
+# Generate service package
+serverless registryGeneratePackage
+
+# Force regeneration
+serverless registryGeneratePackage --force --verbose
+```
+
+**What it creates:**
+- `node_modules/module-registry/service.js` - Service functions
+- `node_modules/module-registry/service.d.ts` - TypeScript definitions
+- `node_modules/module-registry/env.js` - Environment configuration
+- `node_modules/module-registry/package.json` - Package manifest
+
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js ≥14.0.0
+- TypeScript ≥5.0
+- Serverless Framework ≥2.0.0
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+
+# Watch for changes during development
+npm run watch
+
+# Run type checking
+npm run typecheck
+
+# Run linting
+npm run lint
+```
+
+### Build Configuration
+
+The project uses [tsup](https://tsup.egoist.dev/) for building:
+
+- **Entry**: `src/index.ts` (main plugin), `src/service.ts` (service functions)
+- **Output**: `dist/` directory with CommonJS and TypeScript definitions
+- **Target**: Node.js 14+ compatibility
+- **External**: Serverless Framework excluded from bundle
+
+### Testing
+
+Tests are currently disabled but the framework is set up with Jest:
+
+```bash
+# Tests are disabled - would run with:
+npm test  # Currently outputs: "Tests disabled"
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Plugin not found**
+```
+Error: Plugin "serverless-plugin-module-registry" not found
+```
+Solution: Ensure plugin is installed and listed in `serverless.yml` plugins section
+
+**Variable resolution errors**
+```
+Module Registry: Unresolved variables in configuration
+```
+Solution: Check that all variables in `custom.moduleRegistry` section can be resolved
+
+**DynamoDB table creation fails**
+```
+Failed to create table: AccessDenied
+```
+Solution: Ensure AWS credentials have DynamoDB permissions:
+- `dynamodb:CreateTable`
+- `dynamodb:DescribeTable`
+- `dynamodb:UpdateContinuousBackups`
+- `dynamodb:TagResource`
+
+**AI generation fails**
+```
+OPENROUTER_API_KEY environment variable is required
+```
+Solution: Set OpenRouter API key: `export OPENROUTER_API_KEY=your_key_here`
+
+**Registry generation requires function descriptions**
+```
+Function 'myFunction' is missing required 'description' field
+```
+Solution: Add descriptions to all functions in your serverless function definitions
+
+### Debug Mode
+
+Enable detailed logging:
+
+```bash
+serverless deploy --verbose
+```
+
+Look for `[module-registry]` prefixed logs for plugin-specific information.
+
+## 📊 Performance Considerations
+
+### DynamoDB Costs
+
+- Plugin creates one table per service/stage combination
+- Uses **Pay-Per-Request** billing mode
+- Table persists across deployments (not recreated)
+- Point-in-time recovery enabled by default
+
+### Batch Operations
+
+- Registry updates use batch writes (25 items per batch)
+- Automatic cleanup of stale entries during deployment
+- Optimized for sparse access patterns
+
+### CloudFormation Policies
+
+- IAM policies generated as CloudFormation resources
+- Policy ARNs resolved at deployment time
+- No runtime AWS API calls for policy management
+
+## 🔒 Security Considerations
+
+### IAM Policies
+
+- Generated policies follow **least privilege** principle
+- Endpoint-specific resource ARNs (not wildcards)
+- Custom policies allow fine-grained permission control
+
+### Access Control
+
+- Registry table access requires DynamoDB permissions
+- Cross-module access controlled via IAM policy ARNs
+- Service functions inherit Lambda execution role permissions
+
+### Best Practices
+
+1. **Review generated policies** before deployment
+2. **Use strict mode** (`strict: true`) in production
+3. **Regularly audit** endpoint permissions
+4. **Implement proper** IAM role boundaries
+
+## 🤝 Contributing
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes and test thoroughly
+4. Update documentation if needed
+5. Submit a pull request
+
+### Code Standards
+
+- Follow TypeScript best practices
+- Use provided ESLint configuration
+- Add JSDoc comments for public APIs
+- Maintain backward compatibility
+
+### Testing
+
+When contributing:
+- Add test cases for new features
+- Ensure existing functionality isn't broken
+- Test with multiple Serverless Framework versions
+
+## 📋 Version Compatibility
+
+| Plugin Version | Serverless Framework | Node.js |
+|----------------|---------------------|---------|
+| 1.0.x         | 2.x, 3.x, 4.x      | ≥14.0   |
+
+### Serverless Framework Features
+
+- **v2**: Basic hook support, CloudFormation resources
+- **v3**: Enhanced variable resolution, improved logging
+- **v4**: Full ESM support, performance optimizations
+
 ## 📄 License
 
 MIT License - see the [LICENSE](LICENSE) file for details.