heymark 1.1.0 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mossland Open Source
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,170 @@
+# Heymark
+
+AI 코딩 도구별 Skill 문서를 단일 위치에서 관리하고, 각 도구 형식으로 자동 변환하는 도구입니다.  
+한 번 작성한 Markdown 소스를 여러 에이전트 도구에 맞춰 재사용할 수 있습니다.
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Supported Agent Tools](#supported-agent-tools)
+4. [Tech Stack](#tech-stack)
+5. [Heymark Usage](#heymark-usage)
+6. [Heymark Development](#heymark-development)
+
+## Overview
+
+프로젝트마다 AI 도구별 Skill 파일을 따로 관리하면 문서가 분산되고 유지보수 비용이 커집니다.  
+Heymark는 단일 진실 공급원(Single Source of Truth) 원칙으로, 하나의 Markdown 소스를 여러 도구 형식으로 변환합니다.  
+한 번 작성한 Skill을 Cursor, Claude Code, GitHub Copilot, OpenAI Codex, Antigravity에서 바로 사용할 수 있습니다.
+
+## Features
+
+- 단일 소스 관리: Markdown 파일 하나로 여러 AI 도구의 Skill을 통합 관리
+- 자동 형식 변환: 각 도구의 네이티브 형식으로 자동 변환 (YAML frontmatter, AGENTS.md 등)
+- 선택적 변환: 필요한 도구만 선택해서 변환 가능
+- NPM 패키지 배포: npx 기반으로 설치 없이 실행 가능
+- 플러그인 구조: 변환 모듈을 추가해 지원 도구 확장 가능
+
+## Supported Agent Tools
+
+| Tool           | Output Format                            | Key Features                                             |
+| :------------- | :--------------------------------------- | :------------------------------------------------------- |
+| Cursor         | `.cursor/rules/*.mdc`                    | YAML frontmatter (`description`, `globs`, `alwaysApply`) |
+| Claude Code    | `.claude/skills/*/SKILL.md`              | Skill 디렉터리 구조 + YAML frontmatter                   |
+| GitHub Copilot | `.github/instructions/*.instructions.md` | `applyTo` 다중 패턴 매핑                                 |
+| OpenAI Codex   | `.agents/skills/*/SKILL.md`              | Skill 디렉터리 구조 + YAML frontmatter                   |
+| Antigravity    | `.agent/skills/*/SKILL.md`               | Skill 디렉터리 구조 + YAML frontmatter                   |
+
+## Tech Stack
+
+- Runtime: Node.js
+- Language: JavaScript
+- Core: File system API, YAML frontmatter parsing
+
+## Heymark Usage
+
+### 1. Prepare the Skill Markdown Archive Repository
+
+Skill 소스 디렉터리(외부 또는 개인 GitHub 저장소)에 Markdown 파일을 작성하고, YAML frontmatter로 메타데이터를 정의합니다.
+
+```markdown
+---
+description: "AI assistant behavior guidelines"
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: true
+---
+
+# Skill Title
+
+Skill content...
+```
+
+저장소 구조는 다음처럼 단순하게 구성하면 됩니다.
+
+```text
+my-skills-repository/
+  ai-behavior.md
+  code-conventions.md
+  api-skills.md
+```
+
+Skill 소스는 원격 GitHub 저장소(Public/Private)에서 읽습니다.
+
+### 2. Initial Setup
+
+최초 1회, 사용할 Skill 소스 저장소를 설정합니다.
+
+```bash
+# Skill 소스 설정 (.heymark/config.json 생성)
+npx heymark init <GitHub-저장소-URL>
+```
+
+```bash
+# HTTPS (Private이면 Git credential/토큰 설정 필요)
+npx heymark init https://github.com/org/my-rules.git
+
+# SSH (Private 저장소 권장)
+npx heymark init git@github.com:org/my-rules.git
+
+# 저장소 안에서 .md가 하위 폴더에 있을 때
+npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
+```
+
+### 3. Run
+
+설치 없이 npx로 바로 실행할 수 있습니다.  
+Skill은 외부 GitHub 저장소에서 가져오며, 저장소 내 Markdown 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
+
+```bash
+# .heymark/config.json에 설정된 외부 Skill 저장소에서 가져와 모든 도구 형식으로 변환
+# (기존 생성 파일 삭제 후 새로 생성)
+npx heymark
+
+# 단일 실행에서만 다른 외부 저장소 사용 (.heymark/config.json 무시)
+npx heymark --source https://github.com/org/other-rules.git
+
+# 특정 도구만 변환
+npx heymark -t cursor,claude
+
+# 미리보기 (파일 생성 없이 변환 결과만 확인)
+npx heymark --preview
+
+# 이전에 생성된 도구별 파일 삭제
+npx heymark --clean
+
+# CLI help
+npx heymark --help
+```
+
+## Heymark Development
+
+### 1. Local Execution
+
+```bash
+# Skill 소스 설정 (최초 1회, GitHub 저장소 URL)
+node scripts/sync.js init https://github.com/org/my-rules.git
+
+# 모든 도구 형식으로 변환
+node scripts/sync.js
+
+# 단일 실행에서만 다른 저장소 사용
+node scripts/sync.js --source https://github.com/org/other-rules.git
+
+# 특정 도구만 변환
+node scripts/sync.js -t cursor,claude
+
+# 미리보기 (파일 생성 없이 확인)
+node scripts/sync.js --preview
+
+# 생성된 파일 삭제
+node scripts/sync.js --clean
+```
+
+### 2. Release
+
+```bash
+# NPM 로그인
+npm login
+# Username: your-npm-username
+# Email: your-email@example.com
+
+# 1. Skill 수정 후 테스트
+node scripts/sync.js --preview
+
+# 2. 버전 업데이트 (자동으로 Git 태그 생성)
+npm version patch  # 또는 minor, major
+
+# 3. GitHub에 푸시
+git push --follow-tags  # 커밋과 태그를 함께 푸시
+
+# 4. NPM에 배포
+npm publish
+```
+
+### 3. Versioning
+
+- `patch` (1.0.0 -> 1.0.1): 버그 수정, 오타 수정
+- `minor` (1.0.0 -> 1.1.0): 새 Skill 추가, 기능 개선
+- `major` (1.0.0 -> 2.0.0): 호환성 깨지는 변경
+- `npm version` 명령어는 자동으로 Git 태그를 생성합니다.
+- `git push --follow-tags`는 일반 커밋과 태그를 함께 푸시합니다. (권장)
+- 또는 `git push && git push --tags`로 커밋 푸시 후 모든 태그를 별도로 푸시할 수 있습니다.

package/README.md

@@ -1,226 +1,170 @@
-# Heymark
-
-AI 코딩 도구의 컨벤션을 중앙에서 관리하고, 각 도구 형식으로 자동 변환하는 시스템.
-
-1. [Overview](#overview)
-2. [Features](#features)
-3. [Tech Stack](#tech-stack)
-4. [Publishing](#publishing)
-5. [Integration](#integration)
-6. [Getting Started](#getting-started)
-7. [Tool Support](#tool-support)
-
-## Overview
-
-프로젝트마다 AI 도구별 규칙 파일을 따로 작성하면 관리가 파편화된다.
-이 시스템은 단일 진실 공급원(Single Source of Truth) 원칙에 따라, 한 곳에서 작성한 규칙을 여러 AI 도구 형식으로 자동 변환한다.
-규칙을 한 번만 작성하면 Cursor, Claude Code, GitHub Copilot, OpenAI Codex 등에서 즉시 사용할 수 있다.
-
-## Features
-
-- **단일 소스 관리**: 마크다운 파일 하나로 모든 AI 도구의 규칙 통합 관리
-- **자동 형식 변환**: 4종 AI 도구의 네이티브 형식으로 자동 변환 (YAML frontmatter, AGENTS.md 등)
-- **선택적 변환**: 특정 도구만 선택하여 변환 가능
-- **NPM 패키지 배포**: NPM registry를 통한 public 배포로 간편한 설치 및 버전 관리
-- **플러그인 구조**: 변환 모듈 추가만으로 새 도구 지원 확장
-
-## Tech Stack
-
-- **Runtime**: Node.js
-- **Language**: JavaScript
-- **Core**: File system API, YAML frontmatter parsing
-
-## Publishing
-
-패키지 관리자용 가이드 (일반 사용자는 [Integration](#integration) 참고).
-
-### 초기 설정 (한 번만)
-
-```bash
-# NPM 로그인
-npm login
-# Username: your-npm-username
-# Email: your-email@example.com
-```
-
-### 배포 프로세스
-
-```bash
-# 1. 규칙 수정 후 테스트
-node scripts/sync.js --preview
-
-# 2. 버전 업데이트 (자동으로 Git 태그 생성)
-npm version patch  # 또는 minor, major
-
-# 3. GitHub에 푸시
-git push --follow-tags  # 커밋과 태그를 함께 푸시
-
-# 4. NPM에 배포
-npm publish
-```
-
-**버전 관리:**
-
-- `patch` (1.0.0 → 1.0.1): 버그 수정, 오타 수정
-- `minor` (1.0.0 → 1.1.0): 새 규칙 추가, 기능 개선
-- `major` (1.0.0 → 2.0.0): 호환성 깨지는 변경
-
-**Git 태그 설명:**
-
-- `npm version` 명령어는 자동으로 Git 태그를 생성합니다
-- `git push --follow-tags`: 일반 커밋과 태그를 함께 푸시 (추천)
-- 또는 `git push && git push --tags`: 커밋 푸시 후 모든 태그 푸시
-
-## Integration
-
-### Installation
-
-```bash
-# 패키지 설치
-npm install --save-dev heymark
-```
-
-### 초기 설정 (규칙 소스 = 원격 GitHub 저장소)
-
-규칙은 **원격 GitHub 저장소(Public/Private)** 에서 읽습니다.  
-최초 1회만 설정하면 됩니다.
-
-```bash
-# 규칙 소스 설정 (.heymark/config.json 생성)
-npx heymark init <GitHub-저장소-URL>
-```
-
-예시:
-
-```bash
-# HTTPS (Private이면 Git credential/토큰 설정 필요)
-npx heymark init https://github.com/org/my-rules.git
-
-# SSH (Private 저장소 권장)
-npx heymark init git@github.com:org/my-rules.git
-
-# 저장소 안에서 .md가 하위 폴더에 있을 때
-npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
-```
-
-설정은 **`.heymark/config.json`**에, 캐시(클론된 저장소)는 `.heymark/cache/`에 생성됩니다.
-
-```gitignore
-.heymark/
-```
-
-이후 `heymark` 실행 시 해당 저장소를 clone/pull 한 뒤 `.md` 파일들을 변환합니다.
-
-### Usage with npx
-
-설치 없이 바로 실행하거나, 설치 후 npx로 실행할 수 있습니다.  
-규칙은 **원격 GitHub 저장소**에서 가져오며, 해당 저장소 안의 마크다운 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
-
-```bash
-# .heymark/config.json에 설정된 외부 규칙 저장소에서 가져와 모든 도구 형식으로 변환 (기존 생성 파일 삭제 후 새로 생성)
-npx heymark
-
-# 이번에만 다른 외부 저장소 사용 (.heymark/config.json 무시)
-npx heymark --source https://github.com/org/other-rules.git
-
-# 특정 도구만 변환
-npx heymark -t cursor,claude
-
-# 미리보기 (파일 생성 없이 변환 결과만 확인)
-npx heymark --preview
-
-# 이전에 생성된 도구별 파일 삭제
-npx heymark --clean
-
-# 도움말
-npx heymark --help
-```
-
-**설치 없이 바로 사용:**
-
-```bash
-# 설치 없이 최신 버전으로 실행
-npx heymark@latest
-```
-
-**패키지 업데이트:**
-
-```bash
-npm update heymark
-npx heymark
-```
-
-**동작 방식:**
-
-- 기본적으로 기존 생성된 파일을 삭제한 후 새로 생성합니다
-- 이를 통해 이전 버전의 파일이 남지 않고 깔끔하게 동기화됩니다
-
-## Getting Started
-
-규칙을 작성하고 로컬에서 테스트하는 방법.
-
-### Writing Rules
-
-규칙 소스 디렉터리(외부 레포)에 마크다운 파일 작성. YAML frontmatter로 메타데이터 정의:
-
-```markdown
----
-description: "AI assistant behavior guidelines"
-globs: "**/*.ts,**/*.tsx"
-alwaysApply: true
----
-
-# Rule Title
-
-Rule content...
-```
-
-### Local Testing
-
-```bash
-# 규칙 소스 설정 (최초 1회, GitHub 저장소 URL)
-node scripts/sync.js init https://github.com/org/my-rules.git
-
-# 모든 도구 형식으로 변환
-node scripts/sync.js
-
-# 이번에만 다른 저장소 사용
-node scripts/sync.js --source https://github.com/org/other-rules.git
-
-# 특정 도구만 변환
-node scripts/sync.js -t cursor,claude
-
-# 미리보기 (파일 생성 없이 확인)
-node scripts/sync.js --preview
-
-# 생성된 파일 삭제
-node scripts/sync.js --clean
-```
-
-## Tool Support
-
-### Supported Tools
-
-| Tool           | Output Format               | Key Features                    |
-| :------------- | :-------------------------- | :------------------------------ |
-| Cursor         | `.cursor/rules/*.mdc`       | YAML frontmatter, glob 매칭     |
-| Claude Code    | `.claude/skills/*/SKILL.md` | 스킬 디렉토리 구조              |
-| GitHub Copilot | `.github/instructions/*.md` | applyTo 패턴 매칭               |
-| OpenAI Codex   | `AGENTS.md`                 | 단일 파일 병합 (Agent Rules v1) |
-
-### Adding New Tools
-
-변환 모듈을 추가하면 자동 인식된다. 필수 export 인터페이스:
-
-```javascript
-module.exports = {
-    name: "Tool Name",
-    output: "output/path/pattern",
-    generate(rules, projectRoot) {
-        /* ... */
-    },
-    clean(ruleNames, projectRoot) {
-        /* ... */
-    },
-};
-```
+# Heymark
+
+Heymark is a tool that manages Skill documentation for AI coding tools in a single location and automatically converts it into each tool format.  
+A Markdown source written once can be reused across multiple agent tools.
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Supported Agent Tools](#supported-agent-tools)
+4. [Tech Stack](#tech-stack)
+5. [Heymark Usage](#heymark-usage)
+6. [Heymark Development](#heymark-development)
+
+## Overview
+
+Managing Skill files separately for each AI tool leads to fragmented documentation and higher maintenance costs.  
+Heymark follows the Single Source of Truth principle and converts one Markdown source into multiple tool formats.  
+A Skill written once can be used immediately in Cursor, Claude Code, GitHub Copilot, OpenAI Codex, and Antigravity.
+
+## Features
+
+- Single source management: Manage Skills for multiple AI tools with one Markdown file
+- Automatic format conversion: Convert into each tool's native format (YAML frontmatter, AGENTS.md, etc.)
+- Selective conversion: Convert only the tools you need
+- NPM package distribution: Run with `npx` without installation
+- Plugin structure: Extend supported tools by adding conversion modules
+
+## Supported Agent Tools
+
+| Tool           | Output Format                            | Key Features                                             |
+| :------------- | :--------------------------------------- | :------------------------------------------------------- |
+| Cursor         | `.cursor/rules/*.mdc`                    | YAML frontmatter (`description`, `globs`, `alwaysApply`) |
+| Claude Code    | `.claude/skills/*/SKILL.md`              | Skill directory structure + YAML frontmatter             |
+| GitHub Copilot | `.github/instructions/*.instructions.md` | Multi-pattern mapping via `applyTo`                      |
+| OpenAI Codex   | `.agents/skills/*/SKILL.md`              | Skill directory structure + YAML frontmatter             |
+| Antigravity    | `.agent/skills/*/SKILL.md`               | Skill directory structure + YAML frontmatter             |
+
+## Tech Stack
+
+- Runtime: Node.js
+- Language: JavaScript
+- Core: File system API, YAML frontmatter parsing
+
+## Heymark Usage
+
+### 1. Prepare the Skill Markdown Archive Repository
+
+Create Markdown files in a Skill source directory (external or personal GitHub repository) and define metadata with YAML frontmatter.
+
+```markdown
+---
+description: "AI assistant behavior guidelines"
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: true
+---
+
+# Skill Title
+
+Skill content...
+```
+
+You can keep the repository structure simple, as shown below.
+
+```text
+my-skills-repository/
+  ai-behavior.md
+  code-conventions.md
+  api-skills.md
+```
+
+Skill sources are read from a remote GitHub repository (Public/Private).
+
+### 2. Initial Setup
+
+For first-time use, configure the Skill source repository once.
+
+```bash
+# Configure Skill source (.heymark/config.json will be created)
+npx heymark init <GitHub-Repository-URL>
+```
+
+```bash
+# HTTPS (for private repositories, Git credentials/token setup is required)
+npx heymark init https://github.com/org/my-rules.git
+
+# SSH (recommended for private repositories)
+npx heymark init git@github.com:org/my-rules.git
+
+# When .md files are in a subdirectory of the repository
+npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
+```
+
+### 3. Run
+
+You can run it directly with `npx` without installation.  
+Skills are fetched from an external GitHub repository, and Markdown files in that repository are converted into each AI tool format and generated in the current project.
+
+```bash
+# Fetch from the external Skill repository configured in .heymark/config.json and convert to all tool formats
+# (delete previously generated files and recreate them)
+npx heymark
+
+# Use a different external repository for this run only (ignore .heymark/config.json)
+npx heymark --source https://github.com/org/other-rules.git
+
+# Convert only specific tools
+npx heymark -t cursor,claude
+
+# Preview (check conversion result without creating files)
+npx heymark --preview
+
+# Delete tool-specific files generated previously
+npx heymark --clean
+
+# CLI help
+npx heymark --help
+```
+
+## Heymark Development
+
+### 1. Local Execution
+
+```bash
+# Configure Skill source (first-time only, GitHub repository URL)
+node scripts/sync.js init https://github.com/org/my-rules.git
+
+# Convert to all tool formats
+node scripts/sync.js
+
+# Use a different repository for this run only
+node scripts/sync.js --source https://github.com/org/other-rules.git
+
+# Convert only specific tools
+node scripts/sync.js -t cursor,claude
+
+# Preview (check without creating files)
+node scripts/sync.js --preview
+
+# Delete generated files
+node scripts/sync.js --clean
+```
+
+### 2. Release
+
+```bash
+# NPM login
+npm login
+# Username: your-npm-username
+# Email: your-email@example.com
+
+# 1. Test after updating Skills
+node scripts/sync.js --preview
+
+# 2. Update version (Git tag is created automatically)
+npm version patch  # or minor, major
+
+# 3. Push to GitHub
+git push --follow-tags  # push commits and tags together
+
+# 4. Publish to NPM
+npm publish
+```
+
+### 3. Versioning
+
+- `patch` (1.0.0 -> 1.0.1): Bug fixes, typo fixes
+- `minor` (1.0.0 -> 1.1.0): New Skills, feature improvements
+- `major` (1.0.0 -> 2.0.0): Breaking changes
+- The `npm version` command automatically creates a Git tag.
+- `git push --follow-tags` pushes normal commits and tags together. (Recommended)
+- Alternatively, you can run `git push && git push --tags` to push commits first and then push all tags separately.