Modernization Studio

Modernization Studio is a VS Code extension that integrates Flow's modernization orchestration platform directly into your development environment. It enables:

• Exploration of modernization "studios" defined in JSON files within a directory specified by you (see "Configuration").
• Automated installation and management of Python dependencies using uv in an isolated virtual environment.
• Interactive Command Studio webview for executing modernization commands step-by-step.
• Visualization and live refresh of command outputs in a dedicated tree view.

Table of Contents

• Modernization Studio
  • Table of Contents
  • Requirements
  • Getting Started
  • Development Workflow & React Webviews
    • Key Concepts
    • Typical Development Workflow
    • Adding or Migrating Webviews to React
    • Tips
  • Features & Extension Views
  • Configuration
  • Extension Views
  • Commands
  • Scripts
  • Run Confirmation
  • Packaging the Extension
  • Metrics
  • Release Notes
  • Contributing

Requirements

• VS Code ^1.98.0
• Python 3.12.x (automatically installed within venv via uv)
• Internet connection for downloading dependencies

Getting Started

1. Clone the repository and install dependencies:

   git clone https://github.com/CI-T-HyperX/modernization-studio-extension.git
   cd modernization-studio-extension
   npm install
   

2. Build the extension and webviews:

   npm run compile
   npm run build:webview
   

3. (Development) To work on the React webviews with hot-reload and mock data:

   npm run dev:command-studio
   # or
   npm run dev:workflow-tab
   

   Access the local Vite server in your browser for rapid UI development. The webviews use mock data and a mock VS Code API for fast iteration.

4. Open the project in VS Code and press F5 to launch the extension in a new Extension Development Host window.

5. Configure your Studio and Output directories:

   • Use the VS Code settings or the provided commands to set modernizationStudio.localStudioDirectory and modernizationStudio.outputDirectory.

6. Use the extension as normal:

   • Explore studios, run commands, and view outputs in the dedicated views.

Development Workflow & React Webviews

See codex.md for a comprehensive architecture overview and a quick-start guide to create a new well-structured webview.

Modernization Studio's webviews are fully built with React, Zustand, and Vite, enabling a modern, fast, and decoupled development workflow for UI features.

Key Concepts

• Isolated Webview Development:

  • Each webview (e.g., Command Studio, Workflow Tab) is a standalone React app under src/webviews/.
  • You can run each webview in isolation using the provided npm scripts:
    • npm run dev:command-studio – Starts a Vite dev server for Command Studio.
    • npm run dev:workflow-tab – Starts a Vite dev server for Workflow Tab.
    • npm run dev:create-studio – Starts a Vite dev server for Create Studio.
  • Access the local Vite server in your browser for hot-reload and rapid UI iteration. The UI will use mock data and a mock VS Code API.

• Mocked VS Code API and Data:

  • In dev mode, the webviews use a mock implementation of the VS Code API (acquireVsCodeApi) and mock data for steps, outputs, and file selection. This allows you to develop and test UI features without running the full extension or needing a backend.

• Message-Driven Architecture:

  • All communication between the React UI and the extension backend is done via structured messages (postMessage). UI and backend are fully decoupled; all state updates and actions flow through message events.

• State Management:

  • Zustand is used for state management in each webview, with session persistence and message-driven updates.

• Styling:

  • SCSS Modules are used for component-level styling. Codicons are available for consistent iconography.

Typical Development Workflow

1. Run npm install to install dependencies.
2. Start the dev server for the webview you want to work on:
   • npm run dev:command-studio or npm run dev:workflow-tab
3. Open the local Vite server URL in your browser. The UI will use mock data and a mock VS Code API.
4. Make changes to React components, Zustand stores, or styles. The UI will hot-reload automatically.
5. When ready, build the webviews and the extension:
   • npm run compile
   • npm run build:webview
6. Launch the extension in VS Code (F5) to test integration with the real backend.

Adding or Migrating Webviews to React

• Create a new folder under src/webviews/ for your webview.
• Use the existing webviews as templates (see command-studio and workflow-tab).
• Implement your UI as a React app, using Zustand for state and message-driven communication.
• Add a Vite config for your webview and update the npm scripts if needed.

Tips

• Use the mock API and data to iterate quickly on UI/UX.
• Keep all communication with the backend message-based for maximum decoupling.
• Use SCSS Modules for maintainable, isolated styles.
• Add logs and diagnostics as needed; they will appear in the browser console in dev mode.

Features & Extension Views

• Folder Explorer: Browse studios stored as JSON files in a user-configured directory. (folderExplorer)
  • Double-click a file to open it in the main editor. Single-click only selects and does not open.
• Command Studio (Sidebar): Install dependencies, select targets, and run individual commands. (commandStudio)
• Workflow Tabs: Open interactive panels to view and execute step-by-step commands.
• Output Directory: Tree view of generated files, with live refresh and preview. (outputDirectory)
• Virtual Environment Management: Automatic setup and activation of a Python venv using uv.
• Markdown Rendering: Preview .md outputs rendered as HTML.
• Syntax Highlighting (Markdown): Language-tagged code blocks in Markdown are highlighted via rehype-highlight/highlight.js.
  • Current theme: github-dark-dimmed.

Configuration

This extension contributes the following setting:

• modernizationStudio.localStudioDirectory (string): Path to your local studio directory, where your studio .json files are located. Defaults to an empty string.
• modernizationStudio.outputDirectory (string): Path to the studio output directory. Defaults to an empty string.

Alternatively, you can set these values using VS Code commands:

• Modernization Studio: Select Local Studio Directory (modernizationStudio.selectLocalStudioDirectory): Opens a folder picker to update modernizationStudio.localStudioDirectory.
• Modernization Studio: Select Output Directory (modernizationStudio.selectOutputDirectory): Opens a folder picker to update modernizationStudio.outputDirectory.

Example (settings.json):

"modernizationStudio.localStudioDirectory": "/path/to/studios",
"modernizationStudio.outputDirectory": "/path/to/output"

Extension Views

• Folder Explorer (folderExplorer): Tree view of files and folders.
• Command Studio (commandStudio): Webview in the sidebar for managing and running commands.
• Command Outputs (outputDirectory): Tree view of generated output files.

Commands

• Modernization Studio: Open Settings (modernizationStudio.openSettings)
• Modernization Studio: Select Local Studio Directory (modernizationStudio.selectLocalStudioDirectory)
• Modernization Studio: Select Output Directory (modernizationStudio.selectOutputDirectory)
• Modernization Studio: Refresh Output Directory (modernizationStudio.refreshOutputDirectory) — Refreshes the Command Outputs view to reflect new or changed files. Icon: $(refresh).
• Modernization Studio: Create New Studio (modernizationStudio.createNewStudio) — Opens the Create Studio webview for scaffolding a new studio JSON. Icon: $(add).

Run Confirmation

To prevent accidental executions, when clicking the play button (run step) within the Workflow tab, the extension displays a native VS Code confirmation modal.

• Text: "Do you want to start executing this step?"
• Options: "Ok" and "Cancel"
• Behavior:
  • Ok: Starts the step execution and, upon completion, updates the outputs normally.
  • Cancel: The execution does not start and the UI (spinner) state is restored immediately.

Note: This confirmation is part of the default workflow and ensures that the run only starts after explicit user confirmation.

Scripts

• npm run vscode:prepublish – Run the prepublish hook (compile before publishing).
• npm run compile – Compile the extension and build webviews.
• npm run watch – Recompile on source changes (watch mode).
• npm run pretest – Run compile and lint before tests.
• npm run lint – Lint source files.
• npm run lint:fix – Lint and auto-fix warnings.
• npm run integration-test – Run end-to-end integration tests (VS Code).
• npm test – Run unit tests.
• npm run build:webview – Build all React webviews (Vite).
• npm run dev:command-studio – Start dev server for Command Studio webview (hot-reload, mock API).
• npm run dev:workflow-tab – Start dev server for Workflow Tab webview (hot-reload, mock API).
• npm run dev:create-studio – Start dev server for Create Studio webview (hot-reload, mock API).

MCP Tools

The following MCP (Model Context Protocol) tools can be used via the MCP CLI to manage and inspect Modernization Studios and their commands.

list-studios

Description: Retrieves all studio definitions (JSON files) from a given directory and outputs an array of objects containing each studio’s title, description, and file path.

Usage:

mcp list-studios --path /path/to/studios

Arguments:

• --path <directory>: Path to the folder containing studio JSON files.

Example output:

[
  {
    "title": "MyStudio",
    "description": "A sample modernization studio",
    "path": "/path/to/studios/MyStudio.json"
  }
]

create-studio

Description: Generates a new studio schema file (<name>.json) in the specified directory, initialized with a basic template containing metadata, targets, commands, and parameters.

Usage:

mcp create-studio --name MyStudio --purpose "Description of my studio" --directory /path/to/studios

Arguments:

• --name <string>: Identifier and title for the new studio.
• --purpose <string>: Brief description of the studio’s intended purpose.
• --directory <path>: Target directory where the studio schema will be created.

Example output:

Studio schema created at /path/to/studios/MyStudio.json

detail-command

Description: Parses a Python file that uses Click and lists all defined CLI options, including flags, types, requirement status, and help text.

Usage:

mcp detail-command --filePath /path/to/cli.py

Arguments:

• --filePath <path>: Full path to the Python script implementing the Click-based CLI.

Example output:

--name, -n (str, required): User name
--count (int): Number of times

Packaging the Extension

To create a ".vsix" package for distribution or local testing, follow these steps:

1. Compile your extension and build the React:

   npm run compile
   npm run build:webview
   

2. Install the VS Code Extension Manager (vsce) if not already installed:

   npm install -g vsce
   # or via npx:
   npx vsce --version
   

3. (Optional) If you see a repository detection warning, add these fields to package.json:

   "repository": { "type": "git", "url": "https://github.com/CI-T-HyperX/modernization-studio-extension.git" },
   "bugs":       { "url": "https://github.com/CI-T-HyperX/modernization-studio-extension/issues" },
   "homepage":   "https://github.com/CI-T-HyperX/modernization-studio-extension#readme"
   

4. Package the extension:

   vsce package
   

   This will generate a file like ciant-global.flow-modernization-studio-0.0.1.vsix.
5. Install or share the generated .vsix:

   code --install-extension ciandt-global.flow-modernization-studio-0.0.1.vsix
   

Alternate approach:

vsce package \
  --baseContentUrl https://raw.githubusercontent.com/CI-T-HyperX/modernization-studio-extension/main \
  --baseImagesUrl https://raw.githubusercontent.com/CI-T-HyperX/modernization-studio-extension/main/assets

Metrics

Currently, this extension does not collect any metrics. However, the Modernization Studio core does gather certain metrics, which are outlined below:

1. In the prompter-modernization/prompter/constants.py file, the Flow Agent is identified as modernizationstudio. Metrics are collected when utilizing the prompter library.

2. In the modernization-studio/.../AuthenticationAdapter.ts file, the Flow Agent is designated as modernization-studio. Metrics are captured when the legacy MoS client is in use.

It is important to note that the metrics collected vary depending on the library utilized in the commands. Additionally, some metrics are exclusively gathered from the legacy client. While we have plans to enhance the metrics collection process in the future, the current data is limited and should not be regarded as fully reliable.

Release Notes

See CHANGELOG.md for details on each release.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Commit your changes: git commit -m "Add my feature".
4. Push to your branch: git push origin feature/my-feature.
5. Open a Pull Request against the main branch.

Ensure tests pass and adhere to the project's coding guidelines.

Enjoy using Modernization Studio!