Project Copy Utility

Overview

The copy-project-between-envs.sh script copies architectural plan projects between different GCP environments (dev, test, demo, prod) with full RBAC permission setup.

Script Location: cli/sdlc/utils/copy-project-between-envs.sh

Use Cases

1. Integration Testing Setup

Copy legacy projects from production environments to test environments for automated testing:

# Copy legacy project from dev to test for integration tests
./copy-project-between-envs.sh LEGACY-BASELINE-PROJECT \
  --source dev \
  --target test \
  --share ai-swe-agent@codetricks.org

2. Environment Seeding

Populate new environments with sample projects:

# Copy sample project to demo environment
./copy-project-between-envs.sh SAMPLE-PROJECT-001 \
  --source dev \
  --target demo \
  --share demo-user@example.com

3. Project Migration

Move projects between environments during deployment:

# Promote project from test to prod
./copy-project-between-envs.sh VERIFIED-PROJECT \
  --source test \
  --target prod \
  --share team@example.com \
  --role EDITOR

Features

• ✅ GCS rsync - Efficient file copying with gsutil rsync
• ✅ RBAC integration - Automatic permission setup via gRPC
• ✅ Conflict detection - Validates source exists and target doesn't
• ✅ Dry-run mode - Preview changes before executing
• ✅ Force overwrite - Option to replace existing projects
• ✅ Multi-user sharing - Share with multiple users at once
• ✅ Flexible roles - Support for READER, PROMPTER, EDITOR, OWNER

Usage

Basic Copy

./copy-project-between-envs.sh <project-id> --source <env> --target <env>

With User Sharing

./copy-project-between-envs.sh <project-id> \
  --source dev \
  --target test \
  --share user1@example.com,user2@example.com \
  --role EDITOR

Preview Mode

./copy-project-between-envs.sh <project-id> \
  --source dev \
  --target test \
  --dry-run

Force Overwrite

./copy-project-between-envs.sh <project-id> \
  --source dev \
  --target test \
  --force

Arguments

Argument	Required	Description
project-id	Yes	Architectural plan ID to copy
--source <env>	Yes	Source environment (dev, test, demo, prod)
--target <env>	Yes	Target environment (dev, test, demo, prod)
--share <emails>	No	Comma-separated list of emails to share with
--role <role>	No	Role for shared users (default: EDITOR)
--dry-run	No	Preview without executing
--force	No	Overwrite existing project in target
--skip-rbac	No	Skip RBAC setup (files only)
--grpc-host <host>	No	Custom gRPC host for RBAC calls

Roles

Role	Permissions
READER	View project and pages
PROMPTER	View and run AI prompts
EDITOR	View, edit, and run prompts
OWNER	Full control including sharing and deletion

Default Permissions

• sanchos101@gmail.com is always added as OWNER
• Additional users specified with --share get the role from --role (default: EDITOR)

Prerequisites

1. Google Cloud SDK - gsutil and gcloud must be installed
2. grpcurl - For RBAC setup (optional with --skip-rbac)
3. jq - For JSON parsing
4. Authentication - Must be authenticated to both source and target GCP projects
5. Proto files - Must run from project root directory

Integration with Testing

The script is designed to work with the integration test workflow:

1. Human admin copies baseline legacy project from dev to test:

   ./copy-project-between-envs.sh LEGACY-BASELINE-PROJECT \
     --source dev \
     --target test \
     --share ai-swe-agent@codetricks.org

2. Integration tests clone the baseline within test environment using gRPC:

   # Tests use CopyArchitecturalPlan gRPC to create disposable clones
   grpcurl ... CopyArchitecturalPlan

3. Tests run on disposable clones and clean up after completion

Error Handling

The script validates:

• ✅ Source project exists
• ✅ Target project doesn't exist (unless --force)
• ✅ Valid environment names
• ✅ Source and target are different
• ✅ Required tools are installed (gsutil, grpcurl, jq)

Examples

Copy Legacy Project for Testing

# Step 1: Human admin copies from dev to test
./copy-project-between-envs.sh A.0155.01-2025-06-12 \
  --source dev \
  --target test \
  --share ai-swe-agent@codetricks.org

# Step 2: Verify baseline is legacy
gsutil ls gs://construction-code-expert-test/inputs/architectural-plans/A.0155.01-2025-06-12/plan-metadata.json
gsutil ls gs://construction-code-expert-test/inputs/architectural-plans/A.0155.01-2025-06-12/project-metadata.json
# (project-metadata.json should NOT exist)

# Step 3: Set environment variable for tests
export BASELINE_LEGACY_PROJECT="A.0155.01-2025-06-12"

# Step 4: Run integration tests
./tests/integration/test-legacy-project-upgrade.sh

Copy Project with Multiple Users

./copy-project-between-envs.sh TEAM-PROJECT \
  --source dev \
  --target demo \
  --share alice@example.com,bob@example.com,charlie@example.com \
  --role EDITOR

Preview Copy Before Executing

# Preview what would be copied
./copy-project-between-envs.sh LARGE-PROJECT \
  --source dev \
  --target test \
  --dry-run

# If preview looks good, execute
./copy-project-between-envs.sh LARGE-PROJECT \
  --source dev \
  --target test

Related Scripts

• tests/integration/helpers/copy-legacy-project.sh - Test-specific wrapper with defaults for integration testing
• src/main/bash/rsync-icc-book.sh - Similar utility for copying ICC book data

Troubleshooting

"Project already exists in target"

Use --force to overwrite:

./copy-project-between-envs.sh PROJECT-ID --source dev --target test --force

"grpcurl not found"

Either install grpcurl or skip RBAC setup:

# Install grpcurl
brew install grpcurl  # macOS
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest  # Go

# Or skip RBAC
./copy-project-between-envs.sh PROJECT-ID --source dev --target test --skip-rbac

"Proto files not found"

Run the script from the project root directory:

cd /path/to/construction-code-expert
./cli/sdlc/utils/copy-project-between-envs.sh PROJECT-ID --source dev --target test

Authentication Issues

Ensure you're authenticated to both GCP projects:

# Authenticate
gcloud auth login
gcloud auth application-default login

# Verify access to both buckets
gsutil ls gs://construction-code-expert-dev/
gsutil ls gs://construction-code-expert-test/

See Also

• Integration Testing Documentation
• Developer Playbook
• Protocol Buffers & gRPC Best Practices
• RBAC Documentation