ARC Visualizer

ARC Visualizer is a VS Code extension for the ARC workflow. It links the built-in arc/src source tree, a requirement directory, and the current workspace output directory, then renders results in Canvas and Traceability views.

Before You Start

• VS Code 1.134.0+
• Python 3.11+
• Node.js and npm
• Git
• A usable arc/src directory containing main.py and requirements.txt
• A requirement directory containing requirements.yaml or requirements.yml
• A workspace folder to serve as the output root
• OpenAI-compatible API settings

End-to-End Flow

1. Open the workspace folder that will receive output
2. Select the ARC source directory with ARC Visualizer: Select ARC Source Directory
3. Set the API configuration in the extension settings
4. Import the requirement directory with ARC Visualizer: Import Requirement Directory
5. Open Canvas with ARC Visualizer: Open Canvas if Canvas is not already open
6. Run ARC from the Canvas toolbar or with ARC Visualizer: Run ARC Compile
7. Open the generated application with ARC Visualizer: Open Web App Preview
8. Import validation test cases with ARC Visualizer: Import Validation Test Cases
9. Run the validation tests with ARC Visualizer: Run Validation Tests
10. Open the validation report with ARC Visualizer: Open Validation Results

Roles of the Three Directories

• arc/src: built-in ARC source tree used for initialization and compile
• Workspace folder: output root for .arc data and generated artifacts
• Requirement directory: input source for requirements.yaml and reference material

Commands

• ARC Visualizer: Select ARC Source Directory
  • Select the ARC source directory used for initialization and compilation
• ARC Visualizer: Import Requirement Directory
  • Copy a requirement directory into the current workspace .arc/requirement
• ARC Visualizer: Open Canvas
  • Open the main canvas view
• ARC Visualizer: Run ARC Compile
  • Equivalent to clicking Run in Canvas
• ARC Visualizer: Stop ARC Run
  • Stop the current compile process
• ARC Visualizer: Open Web App Preview
  • Start the workspace backend with npm run start
  • Open the application in VS Code's built-in Integrated Browser beside Canvas
• ARC Visualizer: Stop Web App Preview
  • Stop the backend process started for the Web App Preview
  • Closing the Preview tab also stops its backend automatically
• ARC Visualizer: Import Validation Test Cases
  • Copy a validation directory into the current workspace .arc/validation
• ARC Visualizer: Run Validation Tests
  • Run each .spec.ts file from .arc/validation against an isolated backend process
• ARC Visualizer: Open Validation Results
  • Open the standalone validation result page beside the Canvas
  • Read results from .arc/validation/results.json without occupying the Canvas page

Running and Output

The normal entry point is the Canvas Run button. ARC Visualizer: Run ARC Compile does the same thing.

Compile runs from arc/src and writes output into the workspace folder.

Typical output under .arc:

• .arc/requirement
• .arc/node_sessions
• .arc/traceability
• .arc/processing_queue.json

Canvas and Traceability read the latest state from there.

Platform Notes

The extension supports Windows, Linux, and macOS.

ARC compile depends on Python 3.11+. On Windows it stops processes with taskkill; on Linux/macOS it uses process signals.

Environment

The extension writes these settings into arc/src/.env before running:

• OPENAI_API_KEY
• OPENAI_BASE_URL
• MODEL
• ARC_OPENAI_API_MODE
• VISUAL_API_KEY
• VISUAL_BASE_URL
• VISUAL_MODEL
• ARC_DEBUG
• ARC_STRUCTURED_OUTPUT_RETRY_COUNT