Imported from KaotoIO/vscode-kaoto (AGENTS.md). Install upstream with npx skills add KaotoIO/vscode-kaoto. Copyright stays with the author.

Kaoto AGENTS.md

This file provides guidance to agents when working with code in this repository.

Project Overview

This is a VS Code extension for Kaoto, a visual low-code editor for Apache Camel integrations. The extension integrates the Kaoto UI into VS Code and provides tooling for creating, editing, and managing Camel routes, pipes, and kamelets.

AI Agent Contribution Guidelines

Claude Code users and other AI-assisted contributors are welcome to Kaoto. When contributing code with AI assistance:

Human Oversight Required

• AI agents cannot submit PRs independently
• A human must review, approve, and sign all AI-generated code
• The human reviewer is responsible for:
  • Code quality and correctness
  • Responding to maintainer feedback
  • Following up on PR comments

Git Workflow

When contributing to vscode-kaoto:

• Never push to branches you didn't create without explicit permission from the branch owner
• Use forks to avoid cluttering the main repository
• Branch naming conventions:
  • Bug fixes: fix/issue-123-description (e.g., fix/issue-456-webview-crash)
  • Features: feature/description (e.g., feature/citrus-support)
  • Refactors: refactor/description (e.g., refactor/command-structure)
• Delete branches after PR merge or rejection

Volume and Quality Limits

• Maximum 10 PRs per day per contributor (human or AI-assisted)
• Fewer well-tested PRs are better than many shallow ones
• Focus on quality over quantity

Disclosure and Documentation

• Disclosing AI tool usage is optional but recommended
• Mentioning your AI tool helps us improve AGENTS.md and CLAUDE.md
• If you discover gaps in our agent documentation, please suggest improvements

PR Lifecycle

• PRs require active follow-up from the human contributor
• PRs without response after 2 weeks will be closed
• If you need more time, communicate with maintainers

Quality Standards

Before submitting AI-generated PRs, ensure:

1. Build the extension:

   yarn run build:dev

2. Run linting:

   yarn run lint

3. Run unit tests:

   yarn run test:unit

4. Build and test the VSIX (for significant changes):

   yarn run build:vsix
   yarn run test:ui:with-prebuilt-vsix

Additional Requirements:

• Ensure all tests pass
• Fix any linter errors
• Verify changes work as expected in a VS Code instance
• For UI changes, test the webview editor functionality
• Avoid introducing code smells or technical debt
• Do not introduce security vulnerabilities (XSS, injection attacks, OWASP top 10)
• Avoid using deprecated APIs or patterns
• Changes should aim to preserve or improve overall code quality

Development Commands

Build and Development

• yarn run compile - Compile TypeScript and webpack the extension
• yarn run watch - Watch mode for development (with dev webpack config)
• yarn run build:prod - Production build (clean, compile, lint)
• yarn run build:dev - Development build (clean, watch, lint)

Linting and Code Quality

• yarn run lint - Lint TypeScript files in src (includes src/ui-test)
• ESLint configuration in eslint.config.mjs with TypeScript and Prettier integration

Testing

• yarn run test:unit - Run unit tests using VS Code test framework
• yarn run test:ui - Run UI/integration tests using extension tester
• yarn run build:test:unit - Build unit tests
• yarn run build:test:ui - Build UI/integration tests
• Unit tests located in src/test/
• UI/integration tests in src/ui-test/

How to run UI/integration tests

1. yarn build:dev
2. yarn build:vsix
3. yarn run test:ui:with-prebuilt-vsix 3.1 For headless: xvfb-run -a yarn run test:ui:with-prebuilt-vsix

Web Mode Testing

• yarn run run:webmode - Run extension in browser environment for testing

Architecture

Extension Structure

• Entry Points:

  • src/extension/extension.ts - Main extension activation for desktop VS Code
  • src/extension/extensionWeb.ts - Web extension entry point
  • src/webview/KaotoEditorEnvelopeApp.ts - Webview editor application

• Source Directories:

  • src/commands/ - VS Code commands for creating Camel files and projects
  • src/constants/ - Domain-grouped constants (commands, settings, views, patterns, …)
  • src/executors/ - Executor implementations (JBang, Camel Launcher) and their helpers
  • src/extension/ - Extension lifecycle: activation, output channel, What's New panel, and domain registrars:
    • registrars/EditorRegistrar.ts - toggle source code, open with Kaoto, undo/redo commands
    • registrars/ExecutorRegistrar.ts - executor setup, JBang/Java path checks, trusted sources
    • registrars/LifecycleRegistrar.ts - What's New panel, recommended extensions
    • registrars/IntegrationsRegistrar.ts - integrations view, run/project/Kubernetes/Maven commands
    • registrars/DeploymentsRegistrar.ts - deployments view, route stop/start/resume/suspend commands
    • registrars/TestsRegistrar.ts - tests view, run and init commands
    • registrars/InfrastructureRegistrar.ts - infrastructure view, start/stop/logs/copy commands
    • registrars/OpenApiRegistrar.ts - OpenAPI view and import command
    • registrars/TrackingEvent.ts - shared sendCommandTrackingEvent helper used by registrars that track commands
  • src/services/ - Domain services with stateful lifecycle or business logic:
    • ApicurioRegistryService, CamelLauncherDownloader, KaotoCatalogService, OpenApiImportService, RedHatMavenNotificationService
    • ApplicationPropertiesFinder, KameletFileReader, MavenRuntimeDetector, PortManager, StepsOnSaveManager, SuggestionRegistry, TestFolderResolver
  • src/tasks/ - Camel task definitions for the VS Code task system
  • src/types/ - Shared TypeScript types and enums
  • src/utils/ - Pure, stateless helper modules (no domain logic):
    • ArgumentConflictDetector, ClasspathRootFinder, DockerErrorDetector, Modals, Path, Process, Version, Vscode
  • src/views/ - Tree view providers, organized by domain feature:
    • deployments/ - Deployments view and items
    • help/ - Help & Feedback view
    • infrastructure/ - Infrastructure services view
    • integrations/ - Integrations view and items
    • openapi/ - OpenAPI files view
    • shared/ - Shared base classes (AbstractFolderTreeProvider, AbstractFolder)
    • tests/ - Citrus tests view and items
  • src/webview/ - Webview integration with the Kaoto editor envelope

• Test Directory (src/test/) mirrors the source structure:

  • commands/, executors/, extension/, services/, utils/, views/, webview/

• UI/Integration Tests (src/ui-test/):

  • editor/ - Editor interaction tests
  • pageObjects/ - Page object models
  • settings/ - Settings tests
  • utils/ - Shared test helpers (editor, extension, settings, terminal, tree-view, workbench)
  • views/ - View-level UI tests

Webpack Configuration

• Multi-target build: Web worker + Web UI
• Builds to dist/ directory
• Uses TypeScript with webpack for bundling
• SASS/CSS support for webview UI components

Dependencies

• Core Editor: @kaoto/kaoto (v2.11.0) - The main Kaoto editor library, repository
• VS Code Integration: @kie-tools-core/* packages for editor envelope and backend, repository
• UI Framework: PatternFly React components
• Camel Support: Uses Camel JBang CLI or Camel Launcher CLI for operations

File Types Supported

• *.camel.yaml, *.camel.yml - Camel route files
• *.camel.xml - Camel XML route files
• *.kamelet.yaml, *.kamelet.yml - Kamelet files
• *.pipe.yaml, *.pipe.yml, *-pipe.yaml, *-pipe.yml - Pipe files
• *.citrus.yaml, *.citrus.test.yaml, *.citrus.it.yaml, *.citrus-test.yaml, *.citrus-it.yaml - Citrus test files

VS Code Integration

• Custom editor for supported file types
• Tree views for integrations and deployments
• Commands for creating new Camel files
• Integration with Camel JBang CLI or Camel Launcher for running and deploying

TypeScript Configuration

• Target ES6 with React JSX support
• Strict null checks and no implicit any
• Module resolution set to "Bundler"
• Source maps enabled for debugging

Testing Framework

• Unit tests use VS Code test framework with Mocha
• Integration tests use vscode-extension-tester
• Chai assertions with chai-friendly ESLint rules
• Test configuration in .vscode-test.mjs