heymark 1.1.2 → 1.2.0

package/README.md

@@ -1,170 +1,170 @@
-# 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.
+# 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             |
+| Copilot     | `.github/instructions/*.instructions.md` | Multi-pattern mapping via `applyTo`                      |
+| 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.

package/package.json

@@ -1,57 +1,56 @@
-{
-    "name": "heymark",
-    "version": "1.1.2",
-    "description": "Centralized AI coding tool conventions with auto-conversion to multiple formats",
-    "main": "scripts/sync.js",
-    "bin": {
-        "heymark": "scripts/sync.js"
-    },
-    "scripts": {
-        "sync": "node scripts/sync.js",
-        "init": "node scripts/sync.js init",
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "ai",
-        "coding",
-        "conventions",
-        "cursor",
-        "claude",
-        "copilot",
-        "codex",
-        "rules"
-    ],
-    "author": {
-        "name": "i2na",
-        "email": "yena.e121@gmail.com",
-        "url": "https://github.com/i2na"
-    },
-    "contributors": [
-        {
-            "name": "i2na",
-            "email": "yena.e121@gmail.com",
-            "url": "https://github.com/i2na"
-        },
-        {
-            "name": "yezzero",
-            "email": "yeyeonggim06@gmail.com",
-            "url": "https://github.com/yezzero"
-        }
-    ],
-    "license": "MIT",
-    "engines": {
-        "node": ">=14.0.0"
-    },
-    "files": [
-        "scripts/",
-        "rules/",
-        "README.md"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/MosslandOpenDevs/heymark.git"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
-}
+{
+    "name": "heymark",
+    "version": "1.2.0",
+    "description": "Rules & Skills Hub for AI Coding Assistants",
+    "type": "commonjs",
+    "main": "scripts/sync.js",
+    "bin": "scripts/sync.js",
+    "keywords": [
+        "ai-coding-assistant",
+        "ai-agent",
+        "ai-skill",
+        "ai-rule",
+        "skill-management",
+        "cursor",
+        "claude-code",
+        "copilot",
+        "codex",
+        "antigravity"
+    ],
+    "homepage": "https://github.com/MosslandOpenDevs/heymark#readme",
+    "bugs": {
+        "url": "https://github.com/MosslandOpenDevs/heymark/issues",
+        "email": "yena@moss.land"
+    },
+    "license": "MIT",
+    "author": {
+        "name": "i-2na",
+        "email": "yena@moss.land",
+        "url": "https://github.com/i2na"
+    },
+    "contributors": [
+        {
+            "name": "i-2na",
+            "email": "yena@moss.land",
+            "url": "https://github.com/i2na"
+        },
+        {
+            "name": "yezzero",
+            "email": "yeyeonggim06@gmail.com",
+            "url": "https://github.com/yezzero"
+        }
+    ],
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "files": [
+        "scripts/"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/MosslandOpenDevs/heymark.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/scripts/lib/config.js

@@ -1,73 +1,110 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-const CONFIG_DIR = ".heymark";
-const CONFIG_FILENAME = "config.json";
-/** 프로젝트 루트 기준 설정 파일 경로 (표시용) */
-const CONFIG_RELATIVE = path.join(CONFIG_DIR, CONFIG_FILENAME);
-
-/**
- * rulesSource: GitHub 저장소 URL (https://github.com/org/repo 또는 git@github.com:org/repo.git)
- * branch: 브랜치 (기본 main)
- * rulesSourceDir: 저장소 내부에서 .md가 있는 하위 디렉터리 (기본 "" = 루트)
- * @typedef {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} RuleBookConfig
- */
-
-/**
- * 프로젝트 루트에서 .heymark/config.json을 읽습니다.
- * @param {string} projectRoot - 프로젝트 루트 (보통 process.cwd())
- * @returns {RuleBookConfig | null}
- */
-function loadConfig(projectRoot) {
-    const configPath = path.join(projectRoot, CONFIG_DIR, CONFIG_FILENAME);
-    if (!fs.existsSync(configPath)) return null;
-
-    try {
-        const raw = fs.readFileSync(configPath, "utf8");
-        const data = JSON.parse(raw);
-        if (!data || typeof data.rulesSource !== "string" || !data.rulesSource.trim()) {
-            return null;
-        }
-        return {
-            rulesSource: data.rulesSource.trim(),
-            branch:
-                typeof data.branch === "string" && data.branch.trim() ? data.branch.trim() : "main",
-            rulesSourceDir:
-                typeof data.rulesSourceDir === "string" ? data.rulesSourceDir.trim() : "",
-        };
-    } catch {
-        return null;
-    }
-}
-
-/**
- * 초기 설정 파일을 생성합니다. (원격 GitHub 저장소 URL 사용) .heymark/config.json에 저장합니다.
- * @param {string} projectRoot
- * @param {RuleBookConfig} config - { rulesSource: repoUrl, branch?, rulesSourceDir? }
- */
-function writeConfig(projectRoot, config) {
-    const configDir = path.join(projectRoot, CONFIG_DIR);
-    if (!fs.existsSync(configDir)) {
-        fs.mkdirSync(configDir, { recursive: true });
-    }
-    const configPath = path.join(configDir, CONFIG_FILENAME);
-    const toWrite = {
-        rulesSource: config.rulesSource,
-        branch: config.branch || "main",
-    };
-    if (config.rulesSourceDir) {
-        toWrite.rulesSourceDir = config.rulesSourceDir;
-    }
-    fs.writeFileSync(configPath, JSON.stringify(toWrite, null, 2), "utf8");
-    return configPath;
-}
-
-module.exports = {
-    CONFIG_DIR,
-    CONFIG_FILENAME,
-    CONFIG_RELATIVE,
-    loadConfig,
-    writeConfig,
-};
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_DIR = ".heymark";
+const CONFIG_FILENAME = "config.json";
+const DEFAULT_BRANCH = "main";
+const CONFIG_RELATIVE = path.join(CONFIG_DIR, CONFIG_FILENAME);
+
+/**
+ * @typedef {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} RuleBookConfig
+ */
+
+/**
+ * Resolve config file path from project root.
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function getConfigPath(projectRoot) {
+    return path.join(projectRoot, CONFIG_DIR, CONFIG_FILENAME);
+}
+
+/**
+ * Normalize and validate config payload.
+ * @param {unknown} value
+ * @returns {RuleBookConfig | null}
+ */
+function normalizeConfig(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+
+    const raw =
+        /** @type {{ rulesSource?: unknown, branch?: unknown, rulesSourceDir?: unknown }} */ (
+            value
+        );
+    if (typeof raw.rulesSource !== "string" || !raw.rulesSource.trim()) {
+        return null;
+    }
+
+    return {
+        rulesSource: raw.rulesSource.trim(),
+        branch:
+            typeof raw.branch === "string" && raw.branch.trim()
+                ? raw.branch.trim()
+                : DEFAULT_BRANCH,
+        rulesSourceDir: typeof raw.rulesSourceDir === "string" ? raw.rulesSourceDir.trim() : "",
+    };
+}
+
+/**
+ * Read config from project root.
+ * @param {string} projectRoot
+ * @returns {RuleBookConfig | null}
+ */
+function loadConfig(projectRoot) {
+    const configPath = getConfigPath(projectRoot);
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+
+    try {
+        const raw = fs.readFileSync(configPath, "utf8");
+        return normalizeConfig(JSON.parse(raw));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Create initial config file in .heymark/config.json.
+ * @param {string} projectRoot
+ * @param {RuleBookConfig} config
+ * @returns {string}
+ */
+function writeConfig(projectRoot, config) {
+    const configDir = path.join(projectRoot, CONFIG_DIR);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    const normalized = normalizeConfig(config);
+    if (!normalized) {
+        throw new Error("Invalid config payload");
+    }
+
+    const configPath = path.join(configDir, CONFIG_FILENAME);
+    const toWrite = {
+        rulesSource: normalized.rulesSource,
+        branch: normalized.branch || DEFAULT_BRANCH,
+    };
+    if (normalized.rulesSourceDir) {
+        toWrite.rulesSourceDir = normalized.rulesSourceDir;
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(toWrite, null, 2), "utf8");
+    return configPath;
+}
+
+module.exports = {
+    CONFIG_DIR,
+    CONFIG_FILENAME,
+    CONFIG_RELATIVE,
+    DEFAULT_BRANCH,
+    getConfigPath,
+    loadConfig,
+    normalizeConfig,
+    writeConfig,
+};