configucci/QWEN.md

Configucci — Project Context

Project Overview

Configucci is a React-based web application for managing XML configuration files. It enables users to load, edit, and visualize configurations with support for multiple environments and parameter templating.

Core Features

• Load XML configuration files with multiple environments
• Edit environment parameters with change tracking (yellow border indicates modifications)
• Template system using @paramName@ syntax for dynamic substitution
• Visual preview of configurations in multiple formats (XML, JSON, Raw)
• Bootstrap 5-based responsive UI

Technology Stack

Category	Technology
Framework	React 19.2.0
Language	TypeScript 5.9
Build Tool	Vite 7.2.4
UI Library	Bootstrap 5.3.3
Testing	Vitest 4.0.16 + jsdom
Linting	ESLint 9.17.0 + typescript-eslint
Syntax Highlighting	react-highlight + highlight.js

Project Structure

configucci/
├── src/
│   ├── models/           # Data models and domain logic
│   │   ├── Config.tsx    # Config, ConfigTemplate classes
│   │   ├── ConfigReader.tsx  # XML parser utility
│   │   ├── Env.ts        # Env, AppEvent, AddEvent, DelEvent, UpdateEvent
│   │   ├── EnvParam.ts   # EnvParam class
│   │   └── NamedId.ts    # NamedId interface
│   ├── componets/        # React components (note: directory name typo)
│   │   ├── env/
│   │   │   ├── Environment.tsx      # Environment list & editor
│   │   │   └── EnvironmentParam.tsx # Single parameter editor
│   │   ├── content/
│   │   │   └── Content.tsx          # Tabbed content viewer
│   │   └── FileChooser.tsx          # File upload component
│   ├── builders/         # XML builders
│   │   ├── EnvBuilder.ts
│   │   └── index.ts
│   ├── assets/           # Static assets (images, etc.)
│   ├── test/             # Unit tests
│   │   └── ConfigReader.test.ts
│   ├── App.tsx           # Root component
│   ├── App.css           # Application styles
│   ├── main.tsx          # Entry point
│   └── index.css         # Global styles
├── docs/
│   └── config.json.xml   # Example configuration file
├── public/               # Public static assets
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── vitest.config.ts

Key Data Models

Config

Main configuration container:

• envs: Env[] — Array of environments
• template: ConfigTemplate — Template with parameter placeholders
• Methods: addEnvs(), addTemplate(), getTemplateAsJson(), validateParams()

ConfigTemplate

Template with @paramName@ placeholders:

• Extracts parameters via regex /@(\w+)@/g
• Properties: content (raw text), Params (array of parameter names)

Env

Environment definition:

• id: number, name: string, params: EnvParam[]
• Methods: addParams(), delParam(), updateParams(), isDefault()

EnvParam

Environment parameter:

• id: number, name: string, value: string, isChanged: boolean
• Methods: Changed(), sanitize() (HTML escaping)

AppEvent

Base class for CRUD operations:

• AddEvent<T>, UpdateEvent<T>, DelEvent<T> subclasses

Building and Running

Development Server

npm run dev

Starts Vite dev server with HMR on 0.0.0.0:5173 (accessible externally).

Build

npm run build

Compiles TypeScript and bundles with Vite. Output in dist/.

Preview Production Build

npm run preview

Linting

npm run lint

Testing

npm run test

Runs Vitest tests with jsdom environment.

Configuration File Format

XML configuration files follow this structure:

• Root element: engine
• Environment elements: environment name="..." containing parameter children
• Template element: template containing JSON/text with @param@ placeholders

See docs/config.json.xml for a complete example.

Component Architecture

App (Root)

Manages global state via AppState singleton. Handles:

• File loading through FileChooser
• Environment editing through Environment
• Content preview through Content

FileChooser

File upload component supporting only XML files (text/xml). "Create new" button initializes a default configuration.

Environment

Displays environment list (dropdown) and parameter editor. Features:

• Add/delete/update parameters
• Visual change tracking (yellow border for modified values)
• DEFAULT environment is special (cannot be deleted)

Content

Tabbed viewer with four tabs:

1. Env - XML representation of current environment
2. Content Template - JSON template with syntax highlighting
3. Raw template - Full XML with all environments and template
4. Test-filled template - JavaScript test code (stub)

State Management

Uses AppState singleton pattern:

• Stores current Config and Env[]
• saveEnv() has artificial 1-second delay (simulates async persistence)
• Components subscribe via React useState hooks

Development Conventions

• TypeScript: Strict typing with solution-style references (tsconfig.app.json, tsconfig.node.json)
• ESLint: Uses typescript-eslint with React hooks and refresh plugins
• Testing: Vitest with jsdom, tests in src/test/
• Naming: Component files use PascalCase, models use PascalCase
• Note: Directory is named componets (typo preserved for consistency)

Known Quirks

1. Directory src/componets/ has a typo (should be components/)
2. ConfigReader.tsx has .tsx extension but contains no JSX
3. Some model files use .ts while others use .tsx