heymark 2.0.0 → 2.1.0

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,
+};

package/src/skill-repo/config-file.js

@@ -0,0 +1,87 @@
+const fs = require("fs");
+const path = require("path");
+const { HEYMARK, SKILL_REPO_DEFAULT_BRANCH } = require("@/skill-repo/constants");
+
+function getConfigFilePath(cwd) {
+    return path.join(cwd, HEYMARK.DIR, HEYMARK.CONFIG_FILE);
+}
+
+function parseRawConfig(rawConfig) {
+    if (!rawConfig || typeof rawConfig !== "object") {
+        return null;
+    }
+
+    const raw = rawConfig;
+
+    const repoUrl =
+        typeof raw.repoUrl === "string" && raw.repoUrl.trim()
+            ? raw.repoUrl.trim()
+            : typeof raw.skillSource === "string" && raw.skillSource.trim()
+              ? raw.skillSource.trim()
+              : typeof raw.rulesSource === "string" && raw.rulesSource.trim()
+                ? raw.rulesSource.trim()
+                : "";
+
+    if (!repoUrl) {
+        return null;
+    }
+
+    const branch =
+        typeof raw.branch === "string" && raw.branch.trim()
+            ? raw.branch.trim()
+            : SKILL_REPO_DEFAULT_BRANCH;
+
+    const folder =
+        typeof raw.folder === "string"
+            ? raw.folder.trim()
+            : typeof raw.skillSourceDir === "string"
+              ? raw.skillSourceDir.trim()
+              : typeof raw.rulesSourceDir === "string"
+                ? raw.rulesSourceDir.trim()
+                : "";
+
+    return { repoUrl, branch, folder };
+}
+
+function writeConfig(cwd, config) {
+    const dir = path.join(cwd, HEYMARK.DIR);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const data = parseRawConfig(config);
+    if (!data) {
+        throw new Error("Invalid config");
+    }
+
+    const filePath = getConfigFilePath(cwd);
+    const payload = {
+        repoUrl: data.repoUrl,
+        branch: data.branch || SKILL_REPO_DEFAULT_BRANCH,
+    };
+    if (data.folder) {
+        payload.folder = data.folder;
+    }
+
+    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), "utf8");
+    return filePath;
+}
+
+function readConfig(cwd) {
+    const filePath = getConfigFilePath(cwd);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return parseRawConfig(JSON.parse(raw));
+    } catch {
+        return null;
+    }
+}
+
+module.exports = {
+    writeConfig,
+    readConfig,
+};

package/src/skill-repo/constants.js

@@ -0,0 +1,14 @@
+const HEYMARK = {
+    DIR: ".heymark",
+    CONFIG_FILE: "config.json",
+    CACHE_DIR: "cache",
+};
+
+const SKILL_FILE_EXTENSION = ".md";
+const SKILL_REPO_DEFAULT_BRANCH = "main";
+
+module.exports = {
+    HEYMARK,
+    SKILL_FILE_EXTENSION,
+    SKILL_REPO_DEFAULT_BRANCH,
+};

package/src/skill-repo/skill-file-parser.js

@@ -0,0 +1,79 @@
+const fs = require("fs");
+const path = require("path");
+const { SKILL_FILE_EXTENSION } = require("@/skill-repo/constants");
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]+?)\r?\n---\r?\n?([\s\S]*)$/;
+
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { metadata: {}, body: content.trim() };
+    }
+
+    const [, metadataBlock, body] = match;
+
+    const metadata = {};
+    metadataBlock.split(/\r?\n/).forEach((line) => {
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex === -1) return;
+
+        const key = line.slice(0, separatorIndex).trim();
+        let value = line.slice(separatorIndex + 1).trim();
+
+        if (
+            (value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))
+        ) {
+            value = value.slice(1, -1);
+        }
+
+        if (value === "true") metadata[key] = true;
+        else if (value === "false") metadata[key] = false;
+        else metadata[key] = value;
+    });
+
+    return { metadata, body: body.trim() };
+}
+
+function readSkillFile(skillsDir, fileName) {
+    const filePath = path.join(skillsDir, fileName);
+    const raw = fs.readFileSync(filePath, "utf8");
+    const { metadata, body } = parseFrontmatter(raw);
+    const baseName = path.basename(fileName, SKILL_FILE_EXTENSION);
+
+    return {
+        fileName,
+        name: typeof metadata.name === "string" && metadata.name ? metadata.name : baseName,
+        description:
+            typeof metadata.description === "string" && metadata.description
+                ? metadata.description
+                : baseName,
+        globs: typeof metadata.globs === "string" ? metadata.globs : "",
+        alwaysApply: metadata.alwaysApply === true,
+        metadata,
+        body,
+    };
+}
+
+function readSkillFiles(skillsDir) {
+    if (!fs.existsSync(skillsDir)) {
+        console.error(`[Error] Skills folder not found: ${skillsDir}`);
+        process.exit(1);
+    }
+
+    const files = fs
+        .readdirSync(skillsDir)
+        .filter((fileName) => fileName.endsWith(SKILL_FILE_EXTENSION))
+        .sort();
+
+    if (files.length === 0) {
+        console.error(`[Error] No .md files in: ${skillsDir}`);
+        process.exit(1);
+    }
+
+    return files.map((fileName) => readSkillFile(skillsDir, fileName));
+}
+
+module.exports = {
+    readSkillFiles,
+};

package/src/tools/antigravity/index.js

@@ -0,0 +1,33 @@
+const { ANTIGRAVITY } = require("@/tools/constants");
+const { generate, clean } = require("@/tools/skill-per-folder");
+
+function createContent(skill) {
+    const frontmatterLines = [
+        "---",
+        `name: ${skill.name}`,
+        `description: "${skill.description}"`,
+        "---",
+    ];
+
+    return `${frontmatterLines.join("\n")}\n\n${skill.body}\n`;
+}
+
+module.exports = {
+    key: ANTIGRAVITY.KEY,
+    name: ANTIGRAVITY.NAME,
+    output: ANTIGRAVITY.OUTPUT_PATTERN,
+
+    generate(skills, cwd) {
+        return generate({
+            cwd,
+            dir: ANTIGRAVITY.SKILLS_DIR,
+            fileName: ANTIGRAVITY.SKILL_FILE_NAME,
+            skills,
+            createContent,
+        });
+    },
+
+    clean(skillNames, cwd) {
+        return clean(cwd, ANTIGRAVITY.SKILLS_DIR);
+    },
+};

package/src/tools/claude-code/index.js

@@ -0,0 +1,33 @@
+const { CLAUDE_CODE } = require("@/tools/constants");
+const { generate, clean } = require("@/tools/skill-per-folder");
+
+function createContent(skill) {
+    const frontmatterLines = [
+        "---",
+        `name: ${skill.name}`,
+        `description: "${skill.description}"`,
+        "---",
+    ];
+
+    return `${frontmatterLines.join("\n")}\n\n${skill.body}\n`;
+}
+
+module.exports = {
+    key: CLAUDE_CODE.KEY,
+    name: CLAUDE_CODE.NAME,
+    output: CLAUDE_CODE.OUTPUT_PATTERN,
+
+    generate(skills, cwd) {
+        return generate({
+            cwd,
+            dir: CLAUDE_CODE.SKILLS_DIR,
+            fileName: CLAUDE_CODE.SKILL_FILE_NAME,
+            skills,
+            createContent,
+        });
+    },
+
+    clean(skillNames, cwd) {
+        return clean(cwd, CLAUDE_CODE.SKILLS_DIR);
+    },
+};