heymark 1.1.3 → 2.0.0

package/scripts/cli.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CONFIG_RELATIVE, DEFAULT_BRANCH, loadConfig, writeConfig } = require("./lib/config");
+const { loadRules } = require("./lib/parser");
+const { CACHE_DIR_NAME, getLinkedRulesDir, sanitizeRepoName } = require("./lib/repo");
+
+const SCRIPT_DIR = __dirname;
+const PROJECT_ROOT = process.cwd();
+
+const COMMAND_LINK = "link";
+const COMMAND_SYNC = "sync";
+const COMMAND_CLEAN = "clean";
+const COMMAND_STATUS = "status";
+const COMMAND_HELP = "help";
+
+const OPTION_BRANCH = "--branch";
+const OPTION_FOLDER = "--folder";
+const OPTION_SAMPLES = "--samples";
+const SHORT_BRANCH = "-b";
+const SHORT_FOLDER = "-f";
+const TARGET_ALL = "all";
+const TARGET_DOT = ".";
+const LATEST_VERSION_COMMAND = "npx heymark@latest";
+const SAMPLES_REPO_URL = "https://github.com/MosslandOpenDevs/heymark.git";
+const SAMPLES_FOLDER = "samples";
+
+function exitWithError(message, details = []) {
+    console.error(`[Error] ${message}`);
+    details.forEach((detail) => console.error(`  ${detail}`));
+    process.exit(1);
+}
+
+function discoverTools() {
+    const toolsDir = path.join(SCRIPT_DIR, "tools");
+    const registry = {};
+
+    fs.readdirSync(toolsDir)
+        .filter((fileName) => fileName.endsWith(".js"))
+        .sort()
+        .forEach((file) => {
+            const key = path.basename(file, ".js");
+            registry[key] = require(path.join(toolsDir, file));
+        });
+
+    return registry;
+}
+
+function showHelp(tools) {
+    const toolLines = Object.entries(tools)
+        .map(([toolKey, toolDefinition]) => {
+            const paddedKey = toolKey.padEnd(10);
+            const paddedName = toolDefinition.name.padEnd(16);
+            return `  ${paddedKey} ${paddedName} -> ${toolDefinition.output}`;
+        })
+        .join("\n");
+
+    console.log(`
+Heymark CLI
+
+Reads *.md from a GitHub repository (public or private) and generates
+tool-specific configuration files for various AI coding assistants.
+Same rules everywhere: A computer, B computer, same remote repo.
+
+Usage:
+  heymark help
+  heymark link <repo-url> [--branch <name>] [--folder <path>]
+  heymark link --samples
+  heymark sync [.|<tool>...]
+  heymark clean [.|<tool>...]
+  heymark status
+  heymark
+
+Options:
+  --branch, -b <name>  Branch name (used with 'link')
+  --folder, -f <path>  Subdirectory path in repository (used with 'link')
+  --samples            Use built-in sample Skill repository
+
+Targets:
+  .                    All available tools
+  <tool>...            Space-separated tool names (no commas)
+
+Available tools:
+${toolLines}
+
+Examples:
+  heymark help
+  heymark link --samples
+  heymark link https://github.com/org/my-rules.git
+  heymark link https://github.com/org/my-rules.git --folder rules --branch main
+  heymark sync .
+  heymark sync cursor claude
+  heymark clean .
+  heymark status
+  heymark
+
+Latest version:
+  ${LATEST_VERSION_COMMAND}
+`);
+}
+
+function parseLinkArgs(args) {
+    if (args.length === 1 && args[0] === OPTION_SAMPLES) {
+        return {
+            repoUrl: SAMPLES_REPO_URL,
+            branch: DEFAULT_BRANCH,
+            folder: SAMPLES_FOLDER,
+        };
+    }
+
+    if (args.includes(OPTION_SAMPLES)) {
+        exitWithError("--samples cannot be combined with other link arguments.", [
+            "Use: heymark link --samples",
+        ]);
+    }
+
+    const repoUrl = args[0];
+    if (!repoUrl || repoUrl.startsWith("--")) {
+        exitWithError("link requires a GitHub repository URL.", [
+            "Example: heymark link https://github.com/org/my-rules.git",
+            "Example: heymark link git@github.com:org/my-rules.git",
+            "Optional: --branch <branch>  --folder <subdir>  (e.g. --folder rules)",
+        ]);
+    }
+
+    let branch = DEFAULT_BRANCH;
+    let folder = "";
+
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+
+        if (arg === OPTION_BRANCH || arg === SHORT_BRANCH) {
+            const value = args[++i];
+            if (!value) {
+                exitWithError("--branch requires a branch name.");
+            }
+            branch = value.trim();
+            continue;
+        }
+
+        if (arg === OPTION_FOLDER || arg === SHORT_FOLDER) {
+            const value = args[++i];
+            if (!value) {
+                exitWithError("--folder requires a folder path.");
+            }
+            folder = value.trim();
+            continue;
+        }
+
+        exitWithError(`Unknown option for link: ${arg}`);
+    }
+
+    return { repoUrl: repoUrl.trim(), branch, folder };
+}
+
+function runLink(args) {
+    const config = parseLinkArgs(args);
+    const configPath = writeConfig(PROJECT_ROOT, config);
+
+    console.log(
+        `[Link] Linked repository saved to ${path.relative(PROJECT_ROOT, configPath) || configPath}`
+    );
+    console.log(`  repoUrl: ${config.repoUrl}`);
+    if (config.branch !== DEFAULT_BRANCH) {
+        console.log(`  branch: ${config.branch}`);
+    }
+    if (config.folder) {
+        console.log(`  folder: ${config.folder}`);
+    }
+    console.log("");
+    console.log("Run 'heymark sync .' to fetch rules and generate tool configs.");
+}
+
+function loadLinkedConfigOrExit() {
+    const linkedConfig = loadConfig(PROJECT_ROOT);
+    if (linkedConfig) {
+        return linkedConfig;
+    }
+
+    exitWithError("No linked repository found.", [
+        `Run: heymark ${COMMAND_LINK} <github-repo-url>`,
+        `Config: ${CONFIG_RELATIVE}`,
+    ]);
+}
+
+function resolveSelectedTools(toolArgs, availableTools) {
+    const availableToolKeys = Object.keys(availableTools);
+    if (toolArgs.length === 0) {
+        return availableToolKeys;
+    }
+
+    const selectedTools = toolArgs.map((tool) => tool.trim().toLowerCase()).filter(Boolean);
+    if (selectedTools.length === 0) {
+        return availableToolKeys;
+    }
+
+    if (selectedTools.some((tool) => tool.includes(","))) {
+        exitWithError("Tool names must be space-separated (no commas).", [
+            "Example: heymark sync cursor claude",
+        ]);
+    }
+
+    const hasDotToken = selectedTools.includes(TARGET_DOT);
+    const hasAllToken = selectedTools.includes(TARGET_ALL);
+
+    if (hasAllToken) {
+        exitWithError("'all' is not supported. Use '.' for all tools.");
+    }
+
+    if (hasDotToken) {
+        if (selectedTools.length > 1) {
+            exitWithError(`'${TARGET_DOT}' cannot be combined with tool names.`);
+        }
+        return availableToolKeys;
+    }
+
+    const invalidTools = selectedTools.filter((tool) => !availableTools[tool]);
+    if (invalidTools.length > 0) {
+        exitWithError(`Unknown tool(s): ${invalidTools.join(", ")}`, [
+            `Available: ${availableToolKeys.join(", ")}`,
+        ]);
+    }
+
+    return Array.from(new Set(selectedTools));
+}
+
+function cleanGeneratedFiles(tools, selectedTools, ruleNames, onlyPrintWhenDeleted) {
+    for (const toolKey of selectedTools) {
+        const cleanedPaths = tools[toolKey].clean(ruleNames, PROJECT_ROOT);
+        if (onlyPrintWhenDeleted && cleanedPaths.length === 0) {
+            continue;
+        }
+
+        cleanedPaths.forEach((filePath) => {
+            console.log(`  Deleted: ${filePath}`);
+        });
+    }
+}
+
+function loadRulesFromLinkedRepo() {
+    const linkedConfig = loadLinkedConfigOrExit();
+    const rulesDir = getLinkedRulesDir(PROJECT_ROOT, linkedConfig);
+    const rules = loadRules(rulesDir);
+    return { linkedConfig, rulesDir, rules };
+}
+
+function printSyncContext(selectedTools, rulesDir) {
+    const rulesRelPath = path.relative(PROJECT_ROOT, rulesDir) || ".";
+    console.log("[Sync] Starting convention sync...");
+    console.log(`  Source:  ${rulesRelPath} (from linked repo)`);
+    console.log(`  Target:  ${PROJECT_ROOT}`);
+    console.log(`  Tools:   ${selectedTools.join(", ")}`);
+    console.log("");
+}
+
+function runSync(toolArgs, tools) {
+    const selectedTools = resolveSelectedTools(toolArgs, tools);
+    const { rulesDir, rules } = loadRulesFromLinkedRepo();
+    printSyncContext(selectedTools, rulesDir);
+
+    console.log(`[Load] ${rules.length} rule(s): ${rules.map((rule) => rule.name).join(", ")}`);
+    console.log("");
+
+    const ruleNames = rules.map((rule) => rule.name);
+
+    // Ensure regenerated output is always fresh.
+    console.log("[Clean] Removing existing generated files...");
+    cleanGeneratedFiles(tools, selectedTools, ruleNames, true);
+    console.log("");
+
+    console.log("[Generate]");
+    for (const toolKey of selectedTools) {
+        const toolDefinition = tools[toolKey];
+        const count = toolDefinition.generate(rules, PROJECT_ROOT);
+        const summary = `${toolDefinition.name.padEnd(16)} -> ${toolDefinition.output}`;
+        console.log(`  ${summary} (${count} rules)`);
+    }
+
+    console.log("");
+    console.log(`[Done] ${selectedTools.length} tool(s) synced successfully.`);
+}
+
+function runClean(toolArgs, tools) {
+    const selectedTools = resolveSelectedTools(toolArgs, tools);
+    const { rulesDir, rules } = loadRulesFromLinkedRepo();
+    const rulesRelPath = path.relative(PROJECT_ROOT, rulesDir) || ".";
+
+    console.log("[Clean] Removing generated files...");
+    console.log(`  Source: ${rulesRelPath} (from linked repo)`);
+    console.log(`  Tools:  ${selectedTools.join(", ")}`);
+    console.log("");
+
+    const ruleNames = rules.map((rule) => rule.name);
+    cleanGeneratedFiles(tools, selectedTools, ruleNames, false);
+
+    console.log("");
+    console.log(`[Done] ${selectedTools.length} tool(s) cleaned successfully.`);
+}
+
+function runStatus(tools) {
+    const linkedConfig = loadConfig(PROJECT_ROOT);
+    const toolKeys = Object.keys(tools);
+
+    console.log("[Status] Heymark");
+    console.log(`  Project: ${PROJECT_ROOT}`);
+    console.log(`  Config:  ${CONFIG_RELATIVE}`);
+    console.log(`  Tools:   ${toolKeys.join(", ")}`);
+    console.log(`  Latest:  ${LATEST_VERSION_COMMAND}`);
+    console.log("");
+
+    if (!linkedConfig) {
+        console.log("No repository is linked yet.");
+        console.log(`Run: heymark ${COMMAND_LINK} <github-repo-url>`);
+        return;
+    }
+
+    const cachePath = path.join(
+        PROJECT_ROOT,
+        CACHE_DIR_NAME,
+        sanitizeRepoName(linkedConfig.repoUrl)
+    );
+    const cacheState = fs.existsSync(cachePath) ? "ready" : "not-fetched";
+
+    console.log("Linked repository:");
+    console.log(`  repoUrl: ${linkedConfig.repoUrl}`);
+    console.log(`  branch:  ${linkedConfig.branch || DEFAULT_BRANCH}`);
+    console.log(`  folder:  ${linkedConfig.folder || "(root)"}`);
+    console.log(`  cache:   ${cacheState}`);
+}
+
+function main() {
+    const tools = discoverTools();
+    const args = process.argv.slice(2);
+
+    if (args.length === 0) {
+        runStatus(tools);
+        return;
+    }
+
+    const command = args[0];
+    const commandArgs = args.slice(1);
+
+    if (command === COMMAND_LINK) {
+        runLink(commandArgs);
+        return;
+    }
+    if (command === COMMAND_SYNC) {
+        runSync(commandArgs, tools);
+        return;
+    }
+    if (command === COMMAND_CLEAN) {
+        runClean(commandArgs, tools);
+        return;
+    }
+    if (command === COMMAND_STATUS) {
+        if (commandArgs.length > 0) {
+            exitWithError("status does not accept arguments.");
+        }
+        runStatus(tools);
+        return;
+    }
+    if (command === COMMAND_HELP) {
+        if (commandArgs.length > 0) {
+            exitWithError("help does not accept arguments.");
+        }
+        showHelp(tools);
+        return;
+    }
+
+    exitWithError(`Unknown command: ${command}`, ["Use 'heymark help' for usage information."]);
+}
+
+main();

package/scripts/lib/config.js

@@ -9,7 +9,7 @@ const DEFAULT_BRANCH = "main";
 const CONFIG_RELATIVE = path.join(CONFIG_DIR, CONFIG_FILENAME);
 
 /**
- * @typedef {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} RuleBookConfig
+ * @typedef {{ repoUrl: string, branch?: string, folder?: string }} THeymarkConfig
  */
 
 /**
@@ -24,35 +24,51 @@ function getConfigPath(projectRoot) {
 /**
  * Normalize and validate config payload.
  * @param {unknown} value
- * @returns {RuleBookConfig | null}
+ * @returns {THeymarkConfig | 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()) {
+    const raw = /** @type {{
+     *   repoUrl?: unknown,
+     *   branch?: unknown,
+     *   folder?: unknown,
+     *   rulesSource?: unknown,
+     *   rulesSourceDir?: unknown
+     * }} */ (value);
+
+    const repoUrl =
+        typeof raw.repoUrl === "string" && raw.repoUrl.trim()
+            ? raw.repoUrl.trim()
+            : typeof raw.rulesSource === "string" && raw.rulesSource.trim()
+              ? raw.rulesSource.trim()
+              : "";
+
+    if (!repoUrl) {
         return null;
     }
 
     return {
-        rulesSource: raw.rulesSource.trim(),
+        repoUrl,
         branch:
             typeof raw.branch === "string" && raw.branch.trim()
                 ? raw.branch.trim()
                 : DEFAULT_BRANCH,
-        rulesSourceDir: typeof raw.rulesSourceDir === "string" ? raw.rulesSourceDir.trim() : "",
+        folder:
+            typeof raw.folder === "string"
+                ? raw.folder.trim()
+                : typeof raw.rulesSourceDir === "string"
+                  ? raw.rulesSourceDir.trim()
+                  : "",
     };
 }
 
 /**
  * Read config from project root.
  * @param {string} projectRoot
- * @returns {RuleBookConfig | null}
+ * @returns {THeymarkConfig | null}
  */
 function loadConfig(projectRoot) {
     const configPath = getConfigPath(projectRoot);
@@ -71,7 +87,7 @@ function loadConfig(projectRoot) {
 /**
  * Create initial config file in .heymark/config.json.
  * @param {string} projectRoot
- * @param {RuleBookConfig} config
+ * @param {THeymarkConfig} config
  * @returns {string}
  */
 function writeConfig(projectRoot, config) {
@@ -87,11 +103,11 @@ function writeConfig(projectRoot, config) {
 
     const configPath = path.join(configDir, CONFIG_FILENAME);
     const toWrite = {
-        rulesSource: normalized.rulesSource,
+        repoUrl: normalized.repoUrl,
         branch: normalized.branch || DEFAULT_BRANCH,
     };
-    if (normalized.rulesSourceDir) {
-        toWrite.rulesSourceDir = normalized.rulesSourceDir;
+    if (normalized.folder) {
+        toWrite.folder = normalized.folder;
     }
 
     fs.writeFileSync(configPath, JSON.stringify(toWrite, null, 2), "utf8");

package/scripts/lib/repo.js

@@ -30,24 +30,24 @@ function sanitizeRepoName(repoUrl) {
     return normalized.replace(/[^a-zA-Z0-9._-]/g, "-") || "repo";
 }
 
-function cloneRulesRepo(projectRoot, clonePath, branch, repoUrl) {
+function cloneLinkedRepo(projectRoot, clonePath, branch, repoUrl) {
     execSync(`git clone --depth 1 --branch "${branch}" "${repoUrl}" "${clonePath}"`, {
         stdio: "inherit",
         cwd: projectRoot,
     });
 }
 
-function updateRulesRepo(clonePath, branch) {
+function updateLinkedRepo(clonePath, branch) {
     execSync(`git fetch origin && git checkout --quiet . && git pull --quiet origin "${branch}"`, {
         stdio: "pipe",
         cwd: clonePath,
     });
 }
 
-function resolveRulesDirectory(clonePath, rulesSourceDir) {
-    const rulesDir = rulesSourceDir ? path.join(clonePath, rulesSourceDir) : clonePath;
+function resolveLinkedFolder(clonePath, folder) {
+    const rulesDir = folder ? path.join(clonePath, folder) : clonePath;
     if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) {
-        console.error(`[Error] Rules directory not found in repo: ${rulesSourceDir || "(root)"}`);
+        console.error(`[Error] Rules directory not found in repo: ${folder || "(root)"}`);
         process.exit(1);
     }
     return rulesDir;
@@ -57,13 +57,13 @@ function resolveRulesDirectory(clonePath, rulesSourceDir) {
  * Clone or update remote repository and return local rules directory.
  * Private repositories require user git credentials (SSH key or token).
  * @param {string} projectRoot
- * @param {{ rulesSource: string, branch?: string, rulesSourceDir?: string }} config
+ * @param {{ repoUrl: string, branch?: string, folder?: string }} config
  * @returns {string}
  */
-function getRulesDirFromRepo(projectRoot, config) {
-    const repoUrl = config.rulesSource;
+function getLinkedRulesDir(projectRoot, config) {
+    const repoUrl = config.repoUrl;
     const branch = config.branch || DEFAULT_BRANCH;
-    const rulesSourceDir = config.rulesSourceDir || "";
+    const folder = config.folder || "";
 
     const cacheBase = path.join(projectRoot, CACHE_DIR_NAME);
     const repoName = sanitizeRepoName(repoUrl);
@@ -72,26 +72,26 @@ function getRulesDirFromRepo(projectRoot, config) {
     if (!fs.existsSync(clonePath)) {
         fs.mkdirSync(cacheBase, { recursive: true });
         try {
-            cloneRulesRepo(projectRoot, clonePath, branch, repoUrl);
+            cloneLinkedRepo(projectRoot, clonePath, branch, repoUrl);
         } catch {
             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");
+            console.error("  Example: heymark link https://github.com/org/repo.git");
             process.exit(1);
         }
     } else {
         try {
-            updateRulesRepo(clonePath, branch);
+            updateLinkedRepo(clonePath, branch);
         } catch {
             // Continue with cached clone when fetch or pull fails.
         }
     }
 
-    return resolveRulesDirectory(clonePath, rulesSourceDir);
+    return resolveLinkedFolder(clonePath, folder);
 }
 
 module.exports = {
     CACHE_DIR_NAME,
-    getRulesDirFromRepo,
+    getLinkedRulesDir,
     sanitizeRepoName,
 };

package/scripts/tools/antigravity.js

@@ -38,16 +38,12 @@ module.exports = {
     },
 
     clean(ruleNames, projectRoot) {
-        const cleaned = [];
-
-        for (const ruleName of ruleNames) {
-            const skillDir = getSkillDir(projectRoot, ruleName);
-            if (fs.existsSync(skillDir)) {
-                fs.rmSync(skillDir, { recursive: true });
-                cleaned.push(path.join(SKILLS_DIR, ruleName));
-            }
+        const skillsDirPath = path.join(projectRoot, SKILLS_DIR);
+        if (!fs.existsSync(skillsDirPath)) {
+            return [];
         }
 
-        return cleaned;
+        fs.rmSync(skillsDirPath, { recursive: true, force: true });
+        return [SKILLS_DIR];
     },
 };

package/scripts/tools/claude.js

@@ -38,16 +38,12 @@ module.exports = {
     },
 
     clean(ruleNames, projectRoot) {
-        const cleaned = [];
-
-        for (const ruleName of ruleNames) {
-            const skillDir = getSkillDir(projectRoot, ruleName);
-            if (fs.existsSync(skillDir)) {
-                fs.rmSync(skillDir, { recursive: true });
-                cleaned.push(path.join(SKILLS_DIR, ruleName));
-            }
+        const skillsDirPath = path.join(projectRoot, SKILLS_DIR);
+        if (!fs.existsSync(skillsDirPath)) {
+            return [];
         }
 
-        return cleaned;
+        fs.rmSync(skillsDirPath, { recursive: true, force: true });
+        return [SKILLS_DIR];
     },
 };

package/scripts/tools/codex.js

@@ -38,16 +38,12 @@ module.exports = {
     },
 
     clean(ruleNames, projectRoot) {
-        const cleaned = [];
-
-        for (const ruleName of ruleNames) {
-            const skillDir = getSkillDir(projectRoot, ruleName);
-            if (fs.existsSync(skillDir)) {
-                fs.rmSync(skillDir, { recursive: true });
-                cleaned.push(path.join(SKILLS_DIR, ruleName));
-            }
+        const skillsDirPath = path.join(projectRoot, SKILLS_DIR);
+        if (!fs.existsSync(skillsDirPath)) {
+            return [];
         }
 
-        return cleaned;
+        fs.rmSync(skillsDirPath, { recursive: true, force: true });
+        return [SKILLS_DIR];
     },
 };

package/scripts/tools/copilot.js

@@ -50,16 +50,12 @@ module.exports = {
     },
 
     clean(ruleNames, projectRoot) {
-        const cleaned = [];
-
-        for (const ruleName of ruleNames) {
-            const filePath = getInstructionPath(projectRoot, ruleName);
-            if (fs.existsSync(filePath)) {
-                fs.unlinkSync(filePath);
-                cleaned.push(path.join(INSTRUCTIONS_DIR, `${ruleName}${FILE_SUFFIX}`));
-            }
+        const instructionsDirPath = path.join(projectRoot, INSTRUCTIONS_DIR);
+        if (!fs.existsSync(instructionsDirPath)) {
+            return [];
         }
 
-        return cleaned;
+        fs.rmSync(instructionsDirPath, { recursive: true, force: true });
+        return [INSTRUCTIONS_DIR];
     },
 };

package/scripts/tools/cursor.js

@@ -37,16 +37,12 @@ module.exports = {
     },
 
     clean(ruleNames, projectRoot) {
-        const cleaned = [];
-
-        for (const ruleName of ruleNames) {
-            const filePath = getRulePath(projectRoot, ruleName);
-            if (fs.existsSync(filePath)) {
-                fs.unlinkSync(filePath);
-                cleaned.push(path.join(RULES_DIR, `${ruleName}${FILE_SUFFIX}`));
-            }
+        const rulesDirPath = path.join(projectRoot, RULES_DIR);
+        if (!fs.existsSync(rulesDirPath)) {
+            return [];
         }
 
-        return cleaned;
+        fs.rmSync(rulesDirPath, { recursive: true, force: true });
+        return [RULES_DIR];
     },
 };