Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@blockchain-web-services/bws-ai-coding-template) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

BWS AI Coding Template

Git worktree management and parallel testing toolkit for Node.js projects

Features

🌳 Git Worktree Management - Work on multiple features simultaneously with isolated environments
🧪 Parallel Testing - Run tests in multiple worktrees without port conflicts (LocalStack + Playwright)
☁️ AWS Infrastructure - Optional CloudFormation templates for DynamoDB, Lambda, S3, Step Functions
🚀 CI/CD Pipeline - Optional CodePipeline setup with GitHub integration
🔒 Claude Code IAM - Read-only debugging access for AI assistant
📦 Non-Destructive - Won't overwrite existing files

Quick Start

# Install and run in your project directory
npx @blockchain-web-services/bws-ai-coding-template

# Or install globally
npm install -g @blockchain-web-services/bws-ai-coding-template
worktree-init

What Gets Installed

Always Installed:

✅ Worktree management scripts (scripts/worktree/)
✅ Documentation (docs/)
✅ .gitignore patterns for worktrees
✅ NPM scripts for worktree commands

Optional (if you choose AWS deployment):

✅ Test infrastructure with LocalStack (test/)
✅ CloudFormation templates (.deploy/)
✅ CI/CD pipeline (devops.yml)

Interactive Setup

The installer will ask you:

Project name - Auto-detected from package.json
GitHub username - For repository configuration
AWS deployments - Whether to include AWS infrastructure and testing

Safety Features

❌ Won't overwrite existing .deploy/ folder
❌ Won't overwrite existing test/ or tests/ folder
⚠️ Warns before overwriting scripts/worktree/
✅ Dry run mode available (--dry-run)

Usage After Installation

Create a Worktree

npm run worktree:create feature-name

Each worktree gets:

Unique LocalStack port (4567-4596)
Unique Playwright port (8080-8109)
Isolated Docker containers
Separate DynamoDB tables

Manage Worktrees

npm run worktree:list          # List all worktrees
npm run worktree:merge <name>  # Merge to current branch
npm run worktree:remove <name> # Remove a worktree

Run Tests (if AWS enabled)

cd test
npm install
npm run docker:up    # Start LocalStack
npm run setup        # Create AWS resources
npm test             # Run all tests

Parallel Testing

Multiple worktrees can run tests simultaneously:

Main branch:    LocalStack on port 4567
feature-a:      LocalStack on port 4579
feature-b:      LocalStack on port 4580
fix-bug:        LocalStack on port 4581

Each environment is completely isolated with unique:

Ports
Docker containers
DynamoDB tables
S3 buckets

Documentation

After installation, see docs/ folder for:

WORKTREES.md - Complete worktree workflow
GIT_WORKFLOW.md - Rebase, commit, merge best practices
PARALLEL_TESTING.md - LocalStack, Docker, port isolation
AWS_INFRASTRUCTURE.md - CloudFormation templates explained
CICD_PIPELINE.md - CodePipeline and CodeBuild setup
TROUBLESHOOTING.md - Common issues and solutions
CLAUDE_INSTRUCTIONS.md - AI assistant integration

Requirements

Node.js: 18.x or later
Git: 2.5+ (for worktree support)
Docker: For LocalStack (if using AWS features)

CLI Options

# Dry run (see what would be installed)
npx @blockchain-web-services/bws-ai-coding-template --dry-run

# Skip AWS infrastructure
npx @blockchain-web-services/bws-ai-coding-template --skip-aws

# Skip test folder
npx @blockchain-web-services/bws-ai-coding-template --skip-test

Development Status

⚠️ Currently in development - Core functionality is complete but CLI implementation is pending.

See IMPLEMENTATION_PLAN.md for details on remaining work.

Contributing

Contributions welcome! Please see the contribution guidelines.

JSPM

@blockchain-web-services/bws-ai-coding-template