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<T>
Base class for CRUD operations:
- `AddEvent<T>`, `UpdateEvent<T>`, `DelEvent<T>` subclasses

## Building and Running

### Development Server
```bash
npm run dev
```
Starts Vite dev server with HMR on 0.0.0.0:5173 (accessible externally).

### Build
```bash
npm run build
```
Compiles TypeScript and bundles with Vite. Output in `dist/`.

### Preview Production Build
```bash
npm run preview
```

### Linting
```bash
npm run lint
```

### Testing
```bash
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`