heymark 2.0.0 → 2.0.1

package/README.ko.md

@@ -26,17 +26,17 @@ _프롬프트 문맥에 맞는 Skill을 자동 로드하는 모습입니다._
 - 단일 소스 관리: Markdown 기반 Skill을 한 곳에서 관리
 - 자동 형식 변환: 도구별 형식으로 Skill 자동 생성
 - 선택 동기화: 전체 또는 특정 도구만 동기화
-- 샘플 Skill 즉시 사용: Skill 저장소 준비 없이 `npx heymark link --samples`로 바로 시작
+- 샘플 Skill 즉시 사용: heymark 샘플 Skill 저장소로 바로 시작
 
 ## Supported Tools
 
-| Tool           | Output Format                            |
-| :------------- | :--------------------------------------- |
-| Cursor         | `.cursor/rules/*.mdc`                    |
-| Claude Code    | `.claude/skills/*/SKILL.md`              |
-| GitHub Copilot | `.github/instructions/*.instructions.md` |
-| OpenAI Codex   | `.agents/skills/*/SKILL.md`              |
-| Antigravity    | `.agent/skills/*/SKILL.md`               |
+| Tool        | CLI usage     | Output Format                            |
+| :---------- | :------------ | :--------------------------------------- |
+| Cursor      | `cursor`      | `.cursor/rules/*.mdc`                    |
+| Claude Code | `claude-code` | `.claude/skills/*/SKILL.md`              |
+| Copilot     | `copilot`     | `.github/instructions/*.instructions.md` |
+| Codex       | `codex`       | `.agents/skills/*/SKILL.md`              |
+| Antigravity | `antigravity` | `.agent/skills/*/SKILL.md`               |
 
 ## How to Use
 
@@ -68,7 +68,7 @@ Skill content...
 ### Quick Start
 
 ```bash
-npx heymark link --samples # 샘플 Skill 바로 연결
+npx heymark link https://github.com/MosslandOpenDevs/heymark.git --folder skill-samples
 npx heymark sync .
 ```
 
@@ -79,20 +79,17 @@ _`link`와 `sync` 실행 후, 각 도구가 요구하는 디렉터리에 Skill
 ### Commands
 
 ```bash
-npx heymark link --samples # 샘플 Skill 바로 연결
+npx heymark link <GitHub-저장소-URL>
+npx heymark link <GitHub-저장소-URL> --folder <folder-name>  # 하위 폴더 사용 시
+npx heymark link <GitHub-저장소-URL> --branch <branch-name>  # 다른 브랜치 사용 시
 
-npx heymark link <GitHub-저장소-URL> # Skill 저장소 연결
-npx heymark link <GitHub-저장소-URL> --folder <folder-name> # 하위 폴더 사용 시
-npx heymark link <GitHub-저장소-URL> --branch <branch-name> # 다른 브랜치 사용 시
+npx heymark sync .                        # 전체 동기화
+npx heymark sync cursor claude-code       # 일부 도구만 동기화
 
-npx heymark sync . # 전체 동기화
-npx heymark sync cursor claude # 일부 도구만 동기화
+npx heymark clean .                       # 전체 정리
+npx heymark clean cursor claude-code      # 일부 도구만 정리
 
-npx heymark clean . # 전체 정리
-npx heymark clean cursor claude # 일부 도구만 정리
-
-npx heymark status # 상태 확인 (status 생략 가능)
-npx heymark help # 명령어 확인
+npx heymark help
 ```
 
 ## How to Dev
@@ -105,7 +102,7 @@ npx heymark help # 명령어 확인
 
 ### Local Development
 
-`How to Use` 섹션의 `npx heymark`를 `node scripts/cli.js`로 바꿔 실행하면 됩니다.
+`How to Use` 섹션의 `npx heymark`를 `node src/index.js`로 바꿔 실행하면 됩니다.
 
 ### Release
 

package/README.md

@@ -28,17 +28,17 @@ _This shows Skills being automatically loaded based on prompt context._
 - Single source management: Manage Markdown-based Skills in one place
 - Automatic format conversion: Generate Skill outputs in each tool's required format
 - Selective sync: Sync all tools or only selected tools
-- Instant sample usage: Start immediately with `npx heymark link --samples` without preparing a Skill repo
+- Sample skills: Try instantly with the heymark sample skill repo
 
 ## Supported Tools
 
-| Tool           | Output Format                            |
-| :------------- | :--------------------------------------- |
-| Cursor         | `.cursor/rules/*.mdc`                    |
-| Claude Code    | `.claude/skills/*/SKILL.md`              |
-| GitHub Copilot | `.github/instructions/*.instructions.md` |
-| OpenAI Codex   | `.agents/skills/*/SKILL.md`              |
-| Antigravity    | `.agent/skills/*/SKILL.md`               |
+| Tool        | CLI usage     | Output Format                            |
+| :---------- | :------------ | :--------------------------------------- |
+| Cursor      | `cursor`      | `.cursor/rules/*.mdc`                    |
+| Claude Code | `claude-code` | `.claude/skills/*/SKILL.md`              |
+| Copilot     | `copilot`     | `.github/instructions/*.instructions.md` |
+| Codex       | `codex`       | `.agents/skills/*/SKILL.md`              |
+| Antigravity | `antigravity` | `.agent/skills/*/SKILL.md`               |
 
 ## How to Use
 
@@ -70,7 +70,7 @@ Skill content...
 ### Quick Start
 
 ```bash
-npx heymark link --samples # quickly link sample Skills
+npx heymark link https://github.com/MosslandOpenDevs/heymark.git --folder skill-samples
 npx heymark sync .
 ```
 
@@ -81,20 +81,17 @@ _After `link` and `sync`, Skill files are generated in each tool's expected dire
 ### Commands
 
 ```bash
-npx heymark link --samples # quickly link sample Skills
+npx heymark link <GitHub-Repository-URL>
+npx heymark link <GitHub-Repository-URL> --folder <folder-name>
+npx heymark link <GitHub-Repository-URL> --branch <branch-name>
 
-npx heymark link <GitHub-Repository-URL> # link a Skill repository
-npx heymark link <GitHub-Repository-URL> --folder <folder-name> # when using a subfolder
-npx heymark link <GitHub-Repository-URL> --branch <branch-name> # when using another branch
+npx heymark sync .                        # sync all tools
+npx heymark sync cursor claude-code       # sync selected tools
 
-npx heymark sync . # sync all tools
-npx heymark sync cursor claude # sync selected tools
+npx heymark clean .                       # clean all generated outputs
+npx heymark clean cursor claude-code      # clean selected tool outputs
 
-npx heymark clean . # clean all generated outputs
-npx heymark clean cursor claude # clean selected tool outputs
-
-npx heymark status # check status (same as running npx heymark)
-npx heymark help # show command help
+npx heymark help
 ```
 
 ## How to Dev
@@ -107,7 +104,7 @@ npx heymark help # show command help
 
 ### Local Development
 
-Replace `npx heymark` in the `How to Use` section with `node scripts/cli.js` for local runs.
+Replace `npx heymark` in the `How to Use` section with `node src/index.js` for local runs.
 
 ### Release
 

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "heymark",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "description": "Rules & Skills Hub for AI Coding Assistants",
     "type": "commonjs",
-    "main": "scripts/cli.js",
-    "bin": "scripts/cli.js",
+    "main": "src/index.js",
+    "bin": "src/index.js",
     "keywords": [
         "ai-coding-assistant",
         "ai-agent",
@@ -44,7 +44,7 @@
         "node": ">=14.0.0"
     },
     "files": [
-        "scripts/"
+        "src/"
     ],
     "repository": {
         "type": "git",

package/src/alias.js

@@ -0,0 +1,41 @@
+const fs = require("fs");
+const path = require("path");
+const Module = require("module");
+
+const PREFIX = "@/";
+const REGISTERED_KEY = "__heymark_alias_registered__";
+const ROOT = __dirname;
+
+function getPath(request) {
+    if (!request.startsWith(PREFIX)) {
+        return null;
+    }
+
+    const rest = request.slice(PREFIX.length);
+    const base = path.join(ROOT, rest);
+    const candidates = [`${base}.js`, path.join(base, "index.js"), base];
+
+    const found = candidates.find((c) => fs.existsSync(c));
+    return found || base;
+}
+
+function registerPath() {
+    const g = /** @type {Record<string, unknown>} */ (globalThis);
+    if (g[REGISTERED_KEY] === true) {
+        return;
+    }
+
+    const original = Module._resolveFilename;
+
+    Module._resolveFilename = function (request, parent, isMain, options) {
+        const resolved = typeof request === "string" ? getPath(request) : null;
+        if (resolved) {
+            return original.call(this, resolved, parent, isMain, options);
+        }
+        return original.call(this, request, parent, isMain, options);
+    };
+
+    g[REGISTERED_KEY] = true;
+}
+
+registerPath();

package/src/commands/clean/index.js

@@ -0,0 +1,17 @@
+const { cleaner } = require("@/commands/cleaner");
+const { selectTools } = require("@/commands/select-tools");
+const { readCache } = require("@/skill-repo/cache-folder");
+
+function runClean(flags, context) {
+    const selectedTools = selectTools(flags, context.tools);
+    const { skills } = readCache(context.cwd);
+
+    const skillNames = skills.map((s) => s.name);
+    const cleanedCount = cleaner(context.tools, selectedTools, skillNames, context.cwd);
+
+    console.log(`[Done] ${cleanedCount} tools cleaned.`);
+}
+
+module.exports = {
+    runClean,
+};

package/src/commands/cleaner.js

@@ -0,0 +1,27 @@
+function cleaner(tools, selectedTools, skillNames, cwd) {
+    let headerPrinted = false;
+    let cleanedCount = 0;
+
+    for (const toolKey of selectedTools) {
+        const cleanedPaths = tools[toolKey].clean(skillNames, cwd);
+        if (cleanedPaths.length === 0) continue;
+
+        if (!headerPrinted) {
+            console.log("[Clean]");
+            headerPrinted = true;
+        }
+
+        cleanedPaths.forEach((p) => console.log(`  Removed: ${p}`));
+        cleanedCount++;
+    }
+
+    if (headerPrinted) {
+        console.log("");
+    }
+
+    return cleanedCount;
+}
+
+module.exports = {
+    cleaner,
+};

package/src/commands/constants.js

@@ -0,0 +1,14 @@
+const COMMAND_LINK = "link";
+const COMMAND_SYNC = "sync";
+const COMMAND_CLEAN = "clean";
+const COMMAND_HELP = "help";
+
+const LATEST_VERSION_COMMAND = "npx heymark@latest";
+
+module.exports = {
+    COMMAND_LINK,
+    COMMAND_SYNC,
+    COMMAND_CLEAN,
+    COMMAND_HELP,
+    LATEST_VERSION_COMMAND,
+};

package/src/commands/help/index.js

@@ -0,0 +1,34 @@
+const { LATEST_VERSION_COMMAND } = require("@/commands/constants");
+
+function runHelp(flags, context) {
+    if (flags.length > 0) {
+        console.error(`[Error] Unknown: ${flags.join(", ")}. help takes no arguments.`);
+        process.exit(1);
+    }
+
+    const toolLines = Object.entries(context.tools)
+        .map(([key, tool]) => `  ${key.padEnd(14)} ${tool.output}`)
+        .join("\n");
+
+    console.log(`
+Usage:
+  heymark link <repo-url>
+  heymark sync .
+  heymark sync <tool1> <tool2> ...
+  heymark clean .
+  heymark clean <tool1> <tool2> ...
+
+Link flags:
+    --branch | -b
+    --folder | -f
+
+Supported tools:
+${toolLines}
+
+Update:  ${LATEST_VERSION_COMMAND}
+`);
+}
+
+module.exports = {
+    runHelp,
+};

package/src/commands/link/flags/branch.js

@@ -0,0 +1,18 @@
+const key = "branch";
+const FLAG = "--branch";
+const SHORT_FLAG = "-b";
+
+function is(flag) {
+    return flag === FLAG || flag === SHORT_FLAG;
+}
+
+function parse(flags, index) {
+    const value = flags[index + 1];
+    if (!value) {
+        console.error("[Error] --branch needs a value.");
+        process.exit(1);
+    }
+    return { value: value.trim(), advance: 1 };
+}
+
+module.exports = { key, is, parse };

package/src/commands/link/flags/folder.js

@@ -0,0 +1,18 @@
+const key = "folder";
+const FLAG = "--folder";
+const SHORT_FLAG = "-f";
+
+function is(flag) {
+    return flag === FLAG || flag === SHORT_FLAG;
+}
+
+function parse(flags, index) {
+    const value = flags[index + 1];
+    if (!value) {
+        console.error("[Error] --folder needs a value.");
+        process.exit(1);
+    }
+    return { value: value.trim(), advance: 1 };
+}
+
+module.exports = { key, is, parse };

package/src/commands/link/index.js

@@ -0,0 +1,58 @@
+const path = require("path");
+const { writeConfig } = require("@/skill-repo/config-file");
+const { SKILL_REPO_DEFAULT_BRANCH } = require("@/skill-repo/constants");
+const branch = require("@/commands/link/flags/branch");
+const folder = require("@/commands/link/flags/folder");
+
+function parseFlags(flags, handlers) {
+    const result = {};
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        const handler = handlers.find((h) => h.is(flag));
+        if (handler) {
+            const parsed = handler.parse(flags, i);
+            result[handler.key] = parsed.value;
+            i += parsed.advance;
+            continue;
+        }
+        console.error(`[Error] Unknown flag: ${flag}`);
+        process.exit(1);
+    }
+    return result;
+}
+
+function parseConfig(flags) {
+    const repoUrl = flags[0];
+    if (!repoUrl || repoUrl.startsWith("--")) {
+        console.error(
+            "[Error] Provide a repo URL. Example: heymark link https://github.com/org/repo.git"
+        );
+        process.exit(1);
+    }
+
+    const parsed = parseFlags(flags.slice(1), [branch, folder]);
+
+    return {
+        repoUrl: repoUrl.trim(),
+        branch: parsed.branch || SKILL_REPO_DEFAULT_BRANCH,
+        folder: parsed.folder || "",
+    };
+}
+
+function runLink(flags, context) {
+    const config = parseConfig(flags);
+    const configPath = writeConfig(context.cwd, config);
+
+    console.log(`[Link] Saved to ${path.relative(context.cwd, configPath) || configPath}`);
+    console.log(`  repo: ${config.repoUrl}`);
+    if (config.branch !== SKILL_REPO_DEFAULT_BRANCH) {
+        console.log(`  branch: ${config.branch}`);
+    }
+    if (config.folder) {
+        console.log(`  folder: ${config.folder}`);
+    }
+}
+
+module.exports = {
+    runLink,
+};

package/src/commands/select-tools.js

@@ -0,0 +1,35 @@
+const ALL_TOOLS_TOKEN = ".";
+
+function selectTools(flags, availableTools) {
+    const availableToolKeys = Object.keys(availableTools);
+    if (flags.length === 0) {
+        return availableToolKeys;
+    }
+
+    if (flags.some((tool) => tool.includes(","))) {
+        console.error("[Error] Use spaces between tools, not commas.");
+        process.exit(1);
+    }
+
+    if (flags.includes(ALL_TOOLS_TOKEN)) {
+        if (flags.length > 1) {
+            console.error("[Error] Use '.' alone for all tools.");
+            process.exit(1);
+        }
+        return availableToolKeys;
+    }
+
+    const invalid = flags.filter((tool) => !availableTools[tool]);
+    if (invalid.length > 0) {
+        console.error(
+            `[Error] Unknown: ${invalid.join(", ")}. Available: ${availableToolKeys.join(", ")}`
+        );
+        process.exit(1);
+    }
+
+    return Array.from(new Set(flags));
+}
+
+module.exports = {
+    selectTools,
+};

package/src/commands/sync/index.js

@@ -0,0 +1,35 @@
+const { cleaner } = require("@/commands/cleaner");
+const { selectTools } = require("@/commands/select-tools");
+const { readCache } = require("@/skill-repo/cache-folder");
+const { readConfig } = require("@/skill-repo/config-file");
+const { SKILL_REPO_DEFAULT_BRANCH } = require("@/skill-repo/constants");
+
+function runSync(flags, context) {
+    const selectedTools = selectTools(flags, context.tools);
+    const { skills } = readCache(context.cwd);
+    const config = readConfig(context.cwd);
+
+    console.log("[Sync]");
+    if (config) {
+        console.log(`  repo:   ${config.repoUrl}`);
+        if (config.folder) console.log(`  folder: ${config.folder}`);
+        if (config.branch !== SKILL_REPO_DEFAULT_BRANCH) console.log(`  branch: ${config.branch}`);
+    }
+    console.log("");
+
+    const skillNames = skills.map((s) => s.name);
+    cleaner(context.tools, selectedTools, skillNames, context.cwd);
+
+    for (const toolKey of selectedTools) {
+        const tool = context.tools[toolKey];
+        const count = tool.generate(skills, context.cwd);
+        console.log(`  ${tool.name.padEnd(16)} -> ${tool.output} (${count} skills)`);
+    }
+
+    console.log("");
+    console.log(`[Done] ${selectedTools.length} tools synced.`);
+}
+
+module.exports = {
+    runSync,
+};

package/src/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+require("./alias.js");
+
+const { COMMAND_LINK, COMMAND_SYNC, COMMAND_CLEAN, COMMAND_HELP } = require("@/commands/constants");
+const { runLink } = require("@/commands/link");
+const { runSync } = require("@/commands/sync");
+const { runClean } = require("@/commands/clean");
+const { runHelp } = require("@/commands/help");
+const { loadTools } = require("@/tools/loader");
+
+function main() {
+    const context = {
+        cwd: process.cwd(),
+        tools: loadTools(),
+    };
+
+    const args = process.argv.slice(2);
+
+    if (args.length === 0) {
+        runHelp([], context);
+        return;
+    }
+
+    const command = args[0];
+    const flags = args.slice(1);
+
+    if (command === COMMAND_LINK) {
+        runLink(flags, context);
+        return;
+    }
+
+    if (command === COMMAND_SYNC) {
+        runSync(flags, context);
+        return;
+    }
+
+    if (command === COMMAND_CLEAN) {
+        runClean(flags, context);
+        return;
+    }
+
+    if (command === COMMAND_HELP) {
+        runHelp(flags, context);
+        return;
+    }
+
+    console.error(`[Error] Unknown command: ${command}. Run: heymark help`);
+    process.exit(1);
+}
+
+main();

package/src/skill-repo/cache-folder.js

@@ -0,0 +1,77 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const { HEYMARK, SKILL_REPO_DEFAULT_BRANCH } = require("@/skill-repo/constants");
+const { readConfig } = require("@/skill-repo/config-file");
+const { readSkillFiles } = require("@/skill-repo/skill-file-parser");
+
+function getCloneFolderPath(cwd, repoUrl) {
+    const name = repoUrl.trim().split("/").pop() || "repo";
+    const dirName = name.endsWith(".git") ? name.slice(0, -4) : name;
+    return path.join(cwd, HEYMARK.DIR, HEYMARK.CACHE_DIR, dirName);
+}
+
+function gitClone(cwd, dir, branch, repoUrl) {
+    execSync(`git clone --depth 1 --branch "${branch}" "${repoUrl}" "${dir}"`, {
+        stdio: "inherit",
+        cwd,
+    });
+}
+
+function gitPull(dir, branch) {
+    execSync(`git fetch origin && git checkout --quiet . && git pull --quiet origin "${branch}"`, {
+        stdio: "pipe",
+        cwd: dir,
+    });
+}
+
+function writeCache(cwd) {
+    const config = readConfig(cwd);
+    if (!config) {
+        console.error(
+            `[Error] Not linked. Run: heymark link <repo-url> (config: ${HEYMARK.DIR}/${HEYMARK.CONFIG_FILE})`
+        );
+        process.exit(1);
+    }
+
+    const branch = config.branch || SKILL_REPO_DEFAULT_BRANCH;
+    const cacheBase = path.join(cwd, HEYMARK.DIR, HEYMARK.CACHE_DIR);
+    const cloneFolderPath = getCloneFolderPath(cwd, config.repoUrl);
+
+    if (!fs.existsSync(cloneFolderPath)) {
+        fs.mkdirSync(cacheBase, { recursive: true });
+        try {
+            gitClone(cwd, cloneFolderPath, branch, config.repoUrl);
+        } catch {
+            console.error("[Error] Clone failed. Check repo access (SSH or token).");
+            process.exit(1);
+        }
+    } else {
+        try {
+            gitPull(cloneFolderPath, branch);
+        } catch {
+            // Continue with cached clone when fetch/pull fails.
+        }
+    }
+
+    return { config, cloneFolderPath };
+}
+
+function readCache(cwd) {
+    const { config, cloneFolderPath } = writeCache(cwd);
+
+    const folder = config.folder || "";
+    const skillsFolderPath = folder ? path.join(cloneFolderPath, folder) : cloneFolderPath;
+    if (!fs.existsSync(skillsFolderPath) || !fs.statSync(skillsFolderPath).isDirectory()) {
+        console.error(`[Error] Folder not found in repo: ${folder || "(root)"}`);
+        process.exit(1);
+    }
+
+    const skills = readSkillFiles(skillsFolderPath);
+
+    return { config, skillsFolderPath, skills };
+}
+
+module.exports = {
+    readCache,
+};