@bmx_senta/migrate-uri v1.0.1

Image Service V2 to V3 Migration CLI (migrate-uri)

A command-line tool to automate the migration of V2 image URLs to V3 in your codebase.

What It Does

• Resolves System Info: Looks up your application's repository using its systemCode in BizOps.
• Checks Registration: Verifies if your system is already registered with the central image-service.
• Automates Registration: If not registered, it creates a pull request to add your system to the image-service.
• Migrates URLs: Scans your repository for V2 image URLs and creates a pull request with the V3 replacements.

Getting Started

1. Prerequisites

• Node.js: Version 22.0.0 or higher. Check with node -v.

• Environment Variables: This tool requires secrets like GitHub and BizOps API keys, which should be injected using Doppler.

  Using Doppler (Recommended)

  Doppler is a secure way to manage environment variables. It injects secrets directly into the environment for a single execution without writing them to a file.

  To run the tool, prefix your command with doppler run:

  doppler run --project cli-tool-project --config dev -- migrate-uri <your-system-code>

2. Installation

# Clone this repository if you haven't already
# git clone <repository_url_of_this_tool>
# cd image-service-v2-to-v3

# Install dependencies
npm install

# Make the CLI command available in your terminal
npm link

3. Usage

Run the tool with your application's system code:

migrate-uri <your-system-code>

Example: migrate-uri my-frontend-service

Workflow Overview

The tool operates in two main stages and will guide you through each step.

1. Stage 1: System Registration

   • The tool first checks if your system is registered in the image-service.
   • If not, it will help you create a pull request to register it.
   • Action Required: You must get this registration PR merged. Afterwards, re-run migrate-uri <your-system-code>.

2. Stage 2: URL Migration

   • Once your system is registered, the tool scans your repository for V2 image URLs.
   • It will show you what it found and ask for confirmation to create a migration pull request with the V3 URL updates.
   • Action Required: Review and merge the migration PR.

For a more detailed visual breakdown, see the Workflow Diagram below.

Configuration

You can customize the migration behavior by modifying migration-config.json. This file lets you define:

• Regex patterns for URL discovery (urlPatterns).
• V2 to V3 mapping logic (urlMappings).
• File extensions to scan (fileExtensions).

Troubleshooting

• Authentication Errors:
  • Double-check your GITHUB_* variables in the .env file.
  • Ensure GITHUB_PRIVATE_KEY is correctly base64-encoded.
  • Verify the GitHub App has the required repository permissions.
• System Not Found: Make sure the <systemCode> is correct and the system is properly defined in BizOps with a linked repository.
• Merge Conflicts: If a created PR has conflicts, you will need to resolve them manually.

Workflow Diagram

Below is a Mermaid diagram representing the CLI's workflow. You can copy this code into a Mermaid-compatible viewer (e.g., Mermaid Live Editor, or IDE extensions) to see the visual flowchart.

graph TD
    A[Start: migrate-uri systemCode] --> AA{"Repo Name Determined from BizOps?"};
    AA -- No --> AB[Error: Repo Undetermined from BizOps. Advise User & End];
    AA -- Yes --> B{"System Registered in image-service Config?"};

    B -- Yes --> C[Stage 2: URL Migration];
    B -- No --> D[Stage 1: System Registration Needed];

    D --> E{"Open Registration PR Exists in image-service?"};
    E -- Yes --> F[Inform User of Existing PR & Stop. User Action Needed on PR.];
    E -- No --> G[Scan BizOps-Determined Repo for Hosts];
    G --> H{"Create Registration PR in image-service? (User Prompt)"};
    H -- Yes --> I[Create PR in image-service. Inform User & Stop. User Action: Merge PR & Re-run Tool];
    H -- No --> J[Inform User Registration Cancelled & Stop];

    C --> K[Scan BizOps-Determined Repo for V2 URLs];
    K --> L{"Display Detailed URL List? (User Prompt)"};
    L -- Yes --> M[Display Full Migratable & Invalid URL Lists];
    L -- No --> N[Display Brief Numerical Summary of URLs];

    M --> O;
    N --> O{"Open Migration PR Exists in BizOps-Determined Repo?"};

    O -- Yes --> P[Inform User of Existing Migration PR & Stop.];
    O -- No --> Q{"Create Migration PR in BizOps-Determined Repo? (User Prompt)"};
    Q -- Yes --> R[Create Migration PR with URL Updates. Inform User & End.];
    Q -- No --> S[Inform User Migration Cancelled & End.];

    subgraph Initial Validation
        A
        AA
        AB
    end

    subgraph Config Check
        B
    end
    
    subgraph "Stage 1: System Registration"
        D
        E
        F
        G
        H
        I
        J
    end

    subgraph "Stage 2: URL Migration"
        C
        K
        L
        M
        N
        O
        P
        Q
        R
        S
    end