MagicHelix Core

The core library for MagicAgentHelix. Provides project analysis, configuration merging, and tag detection logic.

📦 Installation

``bash
npm install @el-j/magic-helix-core
`

🎯 Purpose

This package is the brain of MagicAgentHelix. It:

1. Analyzes projects to detect frameworks, libraries, and conventions
2. Merges configurations (built-in + user custom)
3. Tags files based on dependencies, config files, and file patterns
4. Provides built-in templates for common frameworks

🔧 Usage

$3

`typescript
import { analyzeProjectTags, mergeConfigs } from '@el-j/magic-helix-core';

// Load and merge configuration
const config = mergeConfigs(userConfig);

// Analyze a project
const analysisData = {
dependencies: {
'vue': '^3.4.0',
'tailwindcss': '^3.4.0',
'vitest': '^2.0.0'
},
configFiles: ['tsconfig.json', 'vite.config.ts'],
projectFiles: ['src/App.vue', 'src/main.ts']
};

const tags = analyzeProjectTags(
analysisData,
config.dependencyTagMap,
config.configFileTagMap,
config.fileGlobTagMap
);

console.log(tags);
// Set { 'framework-vue', 'style-tailwind', 'test-vitest', 'lang-typescript' }
`

$3

`typescript
import { loadUserConfig, mergeConfigs } from '@el-j/magic-helix-core';

// Load user config from file (or pass custom config)
const userConfig = loadUserConfig('./custom-config.json');

// Merge with built-in configuration
const mergedConfig = mergeConfigs(userConfig);

// Access the merged configuration
console.log(mergedConfig.dependencyTagMap);
console.log(mergedConfig.tagTemplateMap);
`

📚 API Reference

$3

Analyzes project data and returns a set of applicable tags.

Parameters:
- analysisData: ProjectAnalysisData - Project information
- dependencies: Record - Package dependencies
- configFiles: string[] - Configuration files found
- projectFiles: string[] - All project files
- dependencyTagMap: DependencyTagMap - Maps package names to tags
- configFileTagMap: ConfigFileTagMap - Maps config files to tags
- fileGlobTagMap: FileGlobTagMap - Maps file patterns to tags

Returns: Set - Set of applicable tags

$3

Merges user configuration with built-in defaults.

Parameters:
- userConfig: Partial - Optional user configuration

Returns: MergedConfig - Complete merged configuration

$3

Loads user configuration from a file.

Parameters:
- configPath?: string - Optional path to config file (defaults to magic-helix.config.json, with legacy support for ai-aligner.config.json)

Returns: Partial - Loaded user configuration or empty object

🏗️ Built-in Configuration

The core includes comprehensive built-in detection for:

$3


- Vue.js (vue)
- React (react)
- Angular (@angular/core)
- NestJS (@nestjs/core)

$3

- Tailwind CSS (tailwindcss)
- PrimeVue (primevue)
- Material-UI (@mui/material)
- Quasar (quasar)

$3

- Vitest (vitest)
- Jest (jest)
- Cypress (cypress)
- Playwright (playwright)

$3

- RxJS (rxjs)
- Pinia (pinia)
- Redux (redux)
- Zustand (zustand)

$3

- TypeScript (tsconfig.json, .ts, .tsx)
- JavaScript (.js, .jsx)
- Go (*.go)
- Python (*.py)

🔌 Browser Support

The core library is isomorphic and works in both Node.js and browser environments.

For browser usage, all Node.js-specific APIs (like fs) should be handled by the consuming application.

📖 Type Definitions

`typescript
interface ProjectAnalysisData {
dependencies: Record;
configFiles: string[];
projectFiles: string[];
}

interface Config {
target: string;
templateDirectory: string;
outputDirectory: string;
dependencyTagMap: DependencyTagMap;
configFileTagMap: ConfigFileTagMap;
fileGlobTagMap: FileGlobTagMap;
tagTemplateMap: TagTemplateMap;
}

type DependencyTagMap = Record;
type ConfigFileTagMap = Record;
type FileGlobTagMap = Record;
type TagTemplateMap = Record>;
`

🧪 Testing

`bash
npm test # Run tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage
`

📦 Package Structure

`
dist/
├── index.mjs # ESM bundle
├── index.cjs # CommonJS bundle
├── index.d.ts # TypeScript declarations
└── default_templates/ # Built-in templates
``

📚 More Information

See the monorepo root README.md for full development instructions.

📄 License

MIT