heymark 1.1.1 → 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,189 +1,170 @@
 # Heymark
 
-AI 코딩 도구의 컨벤션을 중앙에서 관리하고, 각 도구 형식으로 자동 변환하는 시스템.
+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. [Tech Stack](#tech-stack)
-4. [Publishing](#publishing)
-5. [Integration](#integration)
-6. [Getting Started](#getting-started)
-7. [Tool Support](#tool-support)
+3. [Supported Agent Tools](#supported-agent-tools)
+4. [Tech Stack](#tech-stack)
+5. [Heymark Usage](#heymark-usage)
+6. [Heymark Development](#heymark-development)
 
 ## Overview
 
-프로젝트마다 AI 도구별 규칙 파일을 따로 작성하면 관리가 파편화된다.
-이 시스템은 단일 진실 공급원(Single Source of Truth) 원칙에 따라, 한 곳에서 작성한 규칙을 여러 AI 도구 형식으로 자동 변환한다.
-규칙을 한 번만 작성하면 Cursor, Claude Code, GitHub Copilot, OpenAI Codex, Antigravity 등에서 즉시 사용할 수 있다.
+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
 
-- **단일 소스 관리**: 마크다운 파일 하나로 모든 AI 도구의 규칙 통합 관리
-- **자동 형식 변환**: 5종 AI 도구의 네이티브 형식으로 자동 변환 (YAML frontmatter, AGENTS.md 등)
-- **선택적 변환**: 특정 도구만 선택하여 변환 가능
-- **NPM 패키지 배포**: NPM registry를 통한 public 배포로 간편한 설치 및 버전 관리
-- **플러그인 구조**: 변환 모듈 추가만으로 새 도구 지원 확장
+- 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
 
-## Tech Stack
+## Supported Agent Tools
 
-- **Runtime**: Node.js
-- **Language**: JavaScript
-- **Core**: File system API, YAML frontmatter parsing
+| 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             |
 
-## Publishing
+## Tech Stack
 
-패키지 관리자용 가이드 (일반 사용자는 [Integration](#integration) 참고).
+- Runtime: Node.js
+- Language: JavaScript
+- Core: File system API, YAML frontmatter parsing
 
-### 초기 설정 (한 번만)
+## Heymark Usage
 
-```bash
-# NPM 로그인
-npm login
-# Username: your-npm-username
-# Email: your-email@example.com
-```
+### 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.
 
-```bash
-# 1. 규칙 수정 후 테스트
-node scripts/sync.js --preview
-
-# 2. 버전 업데이트 (자동으로 Git 태그 생성)
-npm version patch  # 또는 minor, major
+```markdown
+---
+description: "AI assistant behavior guidelines"
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: true
+---
 
-# 3. GitHub에 푸시
-git push --follow-tags  # 커밋과 태그를 함께 푸시
+# Skill Title
 
-# 4. NPM에 배포
-npm publish
+Skill content...
 ```
 
-**버전 관리:**
-
-- `patch` (1.0.0 → 1.0.1): 버그 수정, 오타 수정
-- `minor` (1.0.0 → 1.1.0): 새 규칙 추가, 기능 개선
-- `major` (1.0.0 → 2.0.0): 호환성 깨지는 변경
+You can keep the repository structure simple, as shown below.
 
-**Git 태그 설명:**
+```text
+my-skills-repository/
+  ai-behavior.md
+  code-conventions.md
+  api-skills.md
+```
 
-- `npm version` 명령어는 자동으로 Git 태그를 생성합니다
-- `git push --follow-tags`: 일반 커밋과 태그를 함께 푸시 (추천)
-- 또는 `git push && git push --tags`: 커밋 푸시 후 모든 태그 푸시
+Skill sources are read from a remote GitHub repository (Public/Private).
 
-## Integration
+### 2. Initial Setup
 
-Rule/Skill은 **원격 GitHub 저장소(Public/Private)** 에서 읽습니다.  
-최초 1회만 설정하면 됩니다.
+For first-time use, configure the Skill source repository once.
 
 ```bash
-# 규칙 소스 설정 (.heymark/config.json 생성)
-npx heymark init <GitHub-저장소-URL>
+# Configure Skill source (.heymark/config.json will be created)
+npx heymark init <GitHub-Repository-URL>
 ```
 
 ```bash
-# HTTPS (Private이면 Git credential/토큰 설정 필요)
+# HTTPS (for private repositories, Git credentials/token setup is required)
 npx heymark init https://github.com/org/my-rules.git
 
-# SSH (Private 저장소 권장)
+# SSH (recommended for private repositories)
 npx heymark init git@github.com:org/my-rules.git
 
-# 저장소 안에서 .md가 하위 폴더에 있을 때
+# When .md files are in a subdirectory of the repository
 npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
 ```
 
-### Usage with npx
+### 3. Run
 
-설치 없이 npx로 바로 실행할 수 있습니다.  
-규칙은 **원격 GitHub 저장소**에서 가져오며, 해당 저장소 안의 마크다운 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
+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
-# .heymark/config.json에 설정된 외부 규칙 저장소에서 가져와 모든 도구 형식으로 변환 (기존 생성 파일 삭제 후 새로 생성)
+# 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
 
-# 이번에만 다른 외부 저장소 사용 (.heymark/config.json 무시)
+# 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
 ```
 
-## Getting Started
-
-### Writing Rules
+## Heymark Development
 
-규칙 소스 디렉터리(외부 레포)에 마크다운 파일 작성. YAML frontmatter로 메타데이터 정의:
-
-```markdown
----
-description: "AI assistant behavior guidelines"
-globs: "**/*.ts,**/*.tsx"
-alwaysApply: true
----
-
-# Rule Title
-
-Rule content...
-```
-
-### Local Testing
+### 1. Local Execution
 
 ```bash
-# 규칙 소스 설정 (최초 1회, GitHub 저장소 URL)
+# 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
 ```
 
-## Tool Support
+### 2. Release
 
-### Adding New Tools
+```bash
+# NPM login
+npm login
+# Username: your-npm-username
+# Email: your-email@example.com
 
-변환 모듈을 추가하면 자동 인식된다. 필수 export 인터페이스:
+# 1. Test after updating Skills
+node scripts/sync.js --preview
 
-```javascript
-module.exports = {
-    name: "Tool Name",
-    output: "output/path/pattern",
-    generate(rules, projectRoot) {
-        /* ... */
-    },
-    clean(ruleNames, projectRoot) {
-        /* ... */
-    },
-};
-```
+# 2. Update version (Git tag is created automatically)
+npm version patch  # or minor, major
 
-### Supported Tools
+# 3. Push to GitHub
+git push --follow-tags  # push commits and tags together
 
-| Tool           | Output Format                            | Key Features                                             |
-| :------------- | :--------------------------------------- | :------------------------------------------------------- |
-| Cursor         | `.cursor/rules/*.mdc`                    | YAML frontmatter (`description`, `globs`, `alwaysApply`) |
-| Claude Code    | `.claude/skills/*/SKILL.md`              | 스킬 디렉토리 구조 + YAML frontmatter                    |
-| GitHub Copilot | `.github/instructions/*.instructions.md` | `applyTo` 다중 패턴 매핑                                 |
-| OpenAI Codex   | `.agents/skills/*/SKILL.md`              | 스킬 디렉토리 구조 + YAML frontmatter                    |
-| Antigravity    | `.agent/skills/*/SKILL.md`               | 스킬 디렉토리 구조 + YAML frontmatter                    |
+# 4. Publish to NPM
+npm publish
+```
+
+### 3. Versioning
 
-Antigravity 스킬 파일 경로: `/.agent/skills/<skill-folder>/SKILL.md`
+- `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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "heymark",
-    "version": "1.1.1",
+    "version": "1.1.2",
     "description": "Centralized AI coding tool conventions with auto-conversion to multiple formats",
     "main": "scripts/sync.js",
     "bin": {

package/scripts/lib/repo.js

@@ -1,80 +1,80 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const { execSync } = require("child_process");
-
-const CACHE_DIR_NAME = path.join(".heymark", "cache");
-
-/**
- * 저장소 URL에서 캐시 폴더명으로 쓸 수 있는 문자열 추출
- * https://github.com/org/repo -> org-repo
- * git@github.com:org/repo.git -> org-repo
- */
-function sanitizeRepoName(url) {
-    let s = url.trim();
-    if (s.endsWith(".git")) s = s.slice(0, -4);
-    const match =
-        s.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\/|$)/) || s.match(/([^/]+\/[^/]+?)(?:\/|$)/);
-    if (match) {
-        return match[1].replace(/\//g, "-");
-    }
-    return s.replace(/[^a-zA-Z0-9._-]/g, "-") || "repo";
-}
-
-/**
- * 원격 저장소를 clone 또는 pull하여, 규칙 .md가 있는 로컬 디렉터리 절대 경로를 반환합니다.
- * Private repo는 사용자의 git 인증(SSH 키, credential)으로 접근해야 합니다.
- * @param {string} projectRoot - 현재 프로젝트 루트
- * @param {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} config
- * @returns {string} - .md 파일이 있는 디렉터리의 절대 경로
- */
-function getRulesDirFromRepo(projectRoot, config) {
-    const url = config.rulesSource;
-    const branch = config.branch || "main";
-    const subDir = config.rulesSourceDir || "";
-
-    const cacheBase = path.join(projectRoot, CACHE_DIR_NAME);
-    const repoName = sanitizeRepoName(url);
-    const clonePath = path.join(cacheBase, repoName);
-
-    if (!fs.existsSync(clonePath)) {
-        fs.mkdirSync(cacheBase, { recursive: true });
-        try {
-            execSync(`git clone --depth 1 --branch "${branch}" "${url}" "${clonePath}"`, {
-                stdio: "inherit",
-                cwd: projectRoot,
-            });
-        } catch (err) {
-            console.error("[Error] Failed to clone rules repository.");
-            console.error("  For private repos, ensure you have access (SSH key or HTTPS token).");
-            console.error("  Example: heymark init https://github.com/org/repo.git");
-            process.exit(1);
-        }
-    } else {
-        try {
-            execSync(
-                "git fetch origin && git checkout --quiet . && git pull --quiet origin " + branch,
-                {
-                    stdio: "pipe",
-                    cwd: clonePath,
-                }
-            );
-        } catch (err) {
-            // pull 실패 시(네트워크 등) 기존 클론 내용으로 진행
-        }
-    }
-
-    const rulesDir = subDir ? path.join(clonePath, subDir) : clonePath;
-    if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) {
-        console.error(`[Error] Rules directory not found in repo: ${subDir || "(root)"}`);
-        process.exit(1);
-    }
-    return rulesDir;
-}
-
-module.exports = {
-    CACHE_DIR_NAME,
-    getRulesDirFromRepo,
-    sanitizeRepoName,
-};
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const CACHE_DIR_NAME = path.join(".heymark", "cache");
+
+/**
+ * 저장소 URL에서 캐시 폴더명으로 쓸 수 있는 문자열 추출
+ * https://github.com/org/repo -> org-repo
+ * git@github.com:org/repo.git -> org-repo
+ */
+function sanitizeRepoName(url) {
+    let s = url.trim();
+    if (s.endsWith(".git")) s = s.slice(0, -4);
+    const match =
+        s.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\/|$)/) || s.match(/([^/]+\/[^/]+?)(?:\/|$)/);
+    if (match) {
+        return match[1].replace(/\//g, "-");
+    }
+    return s.replace(/[^a-zA-Z0-9._-]/g, "-") || "repo";
+}
+
+/**
+ * 원격 저장소를 clone 또는 pull하여, 규칙 .md가 있는 로컬 디렉터리 절대 경로를 반환합니다.
+ * Private repo는 사용자의 git 인증(SSH 키, credential)으로 접근해야 합니다.
+ * @param {string} projectRoot - 현재 프로젝트 루트
+ * @param {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} config
+ * @returns {string} - .md 파일이 있는 디렉터리의 절대 경로
+ */
+function getRulesDirFromRepo(projectRoot, config) {
+    const url = config.rulesSource;
+    const branch = config.branch || "main";
+    const subDir = config.rulesSourceDir || "";
+
+    const cacheBase = path.join(projectRoot, CACHE_DIR_NAME);
+    const repoName = sanitizeRepoName(url);
+    const clonePath = path.join(cacheBase, repoName);
+
+    if (!fs.existsSync(clonePath)) {
+        fs.mkdirSync(cacheBase, { recursive: true });
+        try {
+            execSync(`git clone --depth 1 --branch "${branch}" "${url}" "${clonePath}"`, {
+                stdio: "inherit",
+                cwd: projectRoot,
+            });
+        } catch (err) {
+            console.error("[Error] Failed to clone rules repository.");
+            console.error("  For private repos, ensure you have access (SSH key or HTTPS token).");
+            console.error("  Example: heymark init https://github.com/org/repo.git");
+            process.exit(1);
+        }
+    } else {
+        try {
+            execSync(
+                "git fetch origin && git checkout --quiet . && git pull --quiet origin " + branch,
+                {
+                    stdio: "pipe",
+                    cwd: clonePath,
+                }
+            );
+        } catch (err) {
+            // pull 실패 시(네트워크 등) 기존 클론 내용으로 진행
+        }
+    }
+
+    const rulesDir = subDir ? path.join(clonePath, subDir) : clonePath;
+    if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) {
+        console.error(`[Error] Rules directory not found in repo: ${subDir || "(root)"}`);
+        process.exit(1);
+    }
+    return rulesDir;
+}
+
+module.exports = {
+    CACHE_DIR_NAME,
+    getRulesDirFromRepo,
+    sanitizeRepoName,
+};