magehub: Instructions file for Codex

AGENTS.md -- MageHub

TypeScript CLI tool that packages Magento 2 AI coding skills as reusable context files for multiple AI tools. Node.js 18+, ESM modules, Commander.js CLI framework.

Build / Lint / Test Commands

npm install            # Install dependencies
npm run build          # Build with tsup (ESM, node18 target) -> dist/
npm run lint           # ESLint with TypeScript type-checking
npm run format:check   # Prettier check (no auto-fix)
npm run test           # Vitest -- run all tests (232 tests, 13 files)
npm run test:watch     # Vitest in watch mode

Running a Single Test

# By file path
npx vitest run tests/unit/skill-loader.test.ts

# By test name pattern (-t flag)
npx vitest run -t "loadSkillFile"

# Combine file and name filter
npx vitest run tests/unit/renderer.test.ts -t "renderSkillListTable"

Test Organization

• tests/unit/ -- Unit tests (8 files), tests/cli.test.ts + tests/core.test.ts -- integration
• tests/snapshot/ -- Snapshot tests, tests/e2e/ -- smoke tests (all 7 output formats)
• tests/helpers/ -- Shared fixtures and utilities, tests/fixtures/ -- static test data

Coverage: V8 provider, covers src/**/*.ts (excludes src/index.ts, src/types/**).

Code Style

Formatting (Prettier + EditorConfig)

• Single quotes, semicolons, trailing commas (all)
• 2-space indentation, LF line endings, UTF-8
• Final newline required, no trailing whitespace
• Config: .prettierrc, .editorconfig

Imports

Imports are organized in three groups separated by blank lines:

// 1. Node built-ins (always prefixed with `node:`)
import { readdir, readFile } from 'node:fs/promises';
import path from 'node:path';

// 2. Third-party packages
import YAML from 'yaml';

// 3. Local project imports (relative paths with .js extension)
import type { Skill } from '../types/skill.js';
import { validateSkillSchema } from './schema-validator.js';

Key rules:

• All local imports use .js extensions (required by NodeNext module resolution)
• No path aliases -- all imports are relative
• import type is enforced for type-only imports (ESLint: consistent-type-imports)
• Mixed value+type imports use inline type: import { loadSkills, type LoadedSkill } from './skill-loader.js';