CodePress Engine Development

A Babel plugin and development server for React applications that enables visual editing. The plugin injects line number metadata into JSX elements at build time, while the dev server handles live code modifications with automatic formatting and backend synchronization.

Architecture

**Two-part system:**

1. **Babel Plugin (`index.js`)**: Build-time transformation that adds encoded file paths and line numbers to JSX elements

2. **Development Server (`server.js`)**: Fastify-based runtime server that processes visual editor changes and syncs with backend

Build & Test Commands

Execute these commands in the project root:

Code Style Guidelines

JavaScript Conventions

Plugin Configuration (`index.js`)

When modifying the Babel plugin:

1. Pass configuration options directly to the plugin

2. Auto-detect git branch and repository (no manual override)

3. Use sensible defaults for optional parameters

4. Document all options with JSDoc

5. Validate and normalize options at entry point

6. Provide colored console feedback for developers

7. Implement XOR encryption for file paths with URL-safe base64 encoding

8. Add line ranges (startLine-endLine) to each JSX element

9. Add repository/branch info only to container elements

Server Architecture (`server.js`)

When modifying the development server:

1. Use Fastify for HTTP server (high performance, built-in validation)

2. Implement comprehensive request validation schemas

3. Handle errors gracefully with proper HTTP status codes

4. Use service functions to separate concerns (file operations, text changes, backend API)

5. Implement proper CORS handling for browser extension

6. Format modified code with Prettier before writing

7. Implement file locking for single instance operation

8. Validate environment (dev only) on startup

Testing Standards

When writing or updating tests:

1. Write unit tests for all public functions

2. Mock external dependencies: `fs`, `os`, `node-fetch`, `prettier`

3. Tests must be isolated (no environment dependencies)

4. Test both success paths and error scenarios

5. Use Jest mocking patterns (`jest.mock()`, `mockImplementation()`)

6. Verify API endpoints, text operations, and error handling

7. Achieve comprehensive coverage (current: 42 passing tests)

Key Implementation Details

Encoding System

The plugin uses XOR encryption with URL-safe base64 encoding for file paths:

```javascript

// Encoding file paths for security

const encoded = encodeFilePath('/src/components/Button.jsx');

// Decoding in server

const decoded = decodeFilePath(encoded);

```

Text Change Engine

The server supports three text operations:

1. **Insert**: Add text at specified line/column

2. **Delete**: Remove text range (start line/col to end line/col)

3. **Replace**: Atomic delete + insert operation

All operations maintain proper code formatting via Prettier.

API Endpoints

Both endpoints validate requests, apply text changes, format code, and sync with backend API.

Recent Architecture (v1.0.0)

**Major rewrite with complete separation of concerns:**

**Breaking changes from v0.5.0:**

Environment Variables

Required for server operation:

File Structure

Common Development Tasks

Adding New Text Operations

1. Update `applyTextChanges()` in `server.js`

2. Add request validation schema for new operation type

3. Write unit tests in `test/server.test.js`

4. Document in JSDoc comments

Modifying JSX Transformations

1. Update visitor methods in `index.js`

2. Handle line number calculation edge cases

3. Test with various JSX structures

4. Verify production mode safety

Extending API Endpoints

1. Define Fastify route with validation schema

2. Implement service layer function if needed

3. Add error handling with proper status codes

4. Write integration tests

Updating Dependencies

1. Check compatibility with Babel 7.x

2. Verify Fastify plugin compatibility

3. Run full test suite

4. Update JSDoc if APIs change

Troubleshooting