@tinkcarlos/skillora 0.2.0

package/bin/cli.js

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+"use strict";
+
+const { Command } = require("commander");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const packageRoot = path.resolve(__dirname, "..");
+const bundledSkillsDir = path.join(packageRoot, ".claude", "skills");
+const pkg = require(path.join(packageRoot, "package.json"));
+
+const program = new Command();
+
+function resolveTargetDir(options) {
+  if (options.target) {
+    return path.resolve(options.target);
+  }
+  const baseDir = options.global ? os.homedir() : process.cwd();
+  const rootDir = options.universal ? ".agent" : ".claude";
+  return path.join(baseDir, rootDir, "skills");
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function listSkillDirs(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(rootDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(rootDir, entry.name))
+    .filter((dir) => fs.existsSync(path.join(dir, "SKILL.md")));
+}
+
+function stripQuotes(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function validateSkillName(rawName) {
+  if (typeof rawName !== "string") {
+    throw new Error("Skill name must be a string.");
+  }
+  const name = rawName.trim();
+  if (!name) {
+    throw new Error("Skill name is required.");
+  }
+  if (name === "." || name === "..") {
+    throw new Error('Skill name cannot be "." or "..".');
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    throw new Error("Skill name must not contain path separators.");
+  }
+  if (name.includes(":")) {
+    throw new Error('Skill name must not contain ":" characters.');
+  }
+  if (name.includes("\0")) {
+    throw new Error("Skill name contains invalid characters.");
+  }
+  return name;
+}
+
+function parseFrontmatter(content) {
+  if (!content || !content.startsWith("---")) {
+    return {};
+  }
+  const endIndex = content.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return {};
+  }
+  const raw = content.slice(3, endIndex).trim();
+  const lines = raw.split(/\r?\n/);
+  const data = {};
+  let currentKey = null;
+  let multilineValue = [];
+
+  for (const line of lines) {
+    const indented = line.startsWith("  ") || line.startsWith("\t");
+    if (indented && currentKey) {
+      multilineValue.push(line.trim());
+      continue;
+    }
+
+    if (currentKey && multilineValue.length > 0) {
+      data[currentKey] = multilineValue.join(" ").trim();
+      multilineValue = [];
+    }
+
+    const idx = line.indexOf(":");
+    if (idx === -1) {
+      continue;
+    }
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+
+    if (rawValue === "|" || rawValue === ">") {
+      currentKey = key;
+      multilineValue = [];
+      continue;
+    }
+
+    const value = stripQuotes(rawValue);
+    if (key && value) {
+      data[key] = value;
+    }
+    currentKey = null;
+  }
+
+  if (currentKey && multilineValue.length > 0) {
+    data[currentKey] = multilineValue.join(" ").trim();
+  }
+
+  return data;
+}
+
+function readSkillMeta(skillDir) {
+  const skillPath = path.join(skillDir, "SKILL.md");
+  try {
+    const content = fs.readFileSync(skillPath, "utf8");
+    const frontmatter = parseFrontmatter(content);
+    return {
+      name: frontmatter.name || path.basename(skillDir),
+      description: frontmatter.description || "",
+      userInvocable: frontmatter["user-invocable"] !== "false",
+    };
+  } catch (err) {
+    console.error(`Warning: Failed to read ${skillPath}: ${err.message}`);
+    return {
+      name: path.basename(skillDir),
+      description: "",
+      userInvocable: true,
+    };
+  }
+}
+
+function copySkillDir(srcDir, destDir, force) {
+  if (fs.existsSync(destDir)) {
+    if (!force) {
+      return { skipped: true };
+    }
+    try {
+      fs.rmSync(destDir, { recursive: true, force: true });
+    } catch (err) {
+      console.error(`Warning: Failed to remove ${destDir}: ${err.message}`);
+      return { skipped: true, error: err.message };
+    }
+  }
+  try {
+    fs.cpSync(srcDir, destDir, { recursive: true });
+    return { skipped: false };
+  } catch (err) {
+    console.error(`Warning: Failed to copy ${srcDir}: ${err.message}`);
+    return { skipped: true, error: err.message };
+  }
+}
+
+function getSearchRoots() {
+  const cwd = process.cwd();
+  const home = os.homedir();
+  return [
+    path.join(cwd, ".agent", "skills"),
+    path.join(home, ".agent", "skills"),
+    path.join(cwd, ".claude", "skills"),
+    path.join(home, ".claude", "skills"),
+    bundledSkillsDir,
+  ];
+}
+
+function findSkillDir(skillName, options) {
+  const hasTargetOption = options.target || options.global || options.universal;
+  if (hasTargetOption) {
+    const targetDir = resolveTargetDir(options);
+    const candidate = path.join(targetDir, skillName);
+    if (fs.existsSync(path.join(candidate, "SKILL.md"))) {
+      return candidate;
+    }
+    return null;
+  }
+
+  for (const root of getSearchRoots()) {
+    const candidate = path.join(root, skillName);
+    if (fs.existsSync(path.join(candidate, "SKILL.md"))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function escapeXml(value) {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function renderSkillsTable(skills, cliName) {
+  const invocableSkills = skills.filter((s) => s.userInvocable);
+  const slashCommands = invocableSkills.map((s) => `/${s.name}`).join(", ");
+
+  const usage = [
+    "<usage>",
+    "When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.",
+    "",
+    "How to invoke skills:",
+    "",
+    "**Claude Code (native):**",
+    `- Slash command: ${slashCommands || "(none)"}`,
+    '- Or use Skill tool: Skill("skill-name")',
+    "",
+    "**Cursor / Codex / Gemini / Windsurf / Aider:**",
+    `- Run: \`${cliName} read <skill-name>\``,
+    "- The skill content will load with detailed instructions",
+    "",
+    "Usage notes:",
+    "- Only use skills listed in <available_skills> below",
+    "- Do not invoke a skill that is already loaded in your context",
+    "</usage>",
+  ].join("\n");
+
+  const entries = skills
+    .map((skill) => {
+      const name = escapeXml(skill.name);
+      const description = escapeXml(skill.description);
+      const invocable = skill.userInvocable ? "true" : "false";
+      return [
+        "<skill>",
+        `<name>${name}</name>`,
+        `<description>${description}</description>`,
+        `<user-invocable>${invocable}</user-invocable>`,
+        "<location>project</location>",
+        "</skill>",
+      ].join("\n");
+    })
+    .join("\n\n");
+
+  return [
+    "<!-- SKILLS_TABLE_START -->",
+    usage,
+    "",
+    "<available_skills>",
+    "",
+    entries,
+    "",
+    "</available_skills>",
+    "<!-- SKILLS_TABLE_END -->",
+  ].join("\n");
+}
+
+function buildSkillsSystemBlock(skillsTable) {
+  return [
+    '<skills_system priority="1">',
+    "",
+    "## Available Skills",
+    "",
+    skillsTable,
+    "",
+    "</skills_system>",
+  ].join("\n");
+}
+
+function updateAgentsMdContent(content, skillsTable) {
+  const startMarker = "<!-- SKILLS_TABLE_START -->";
+  const endMarker = "<!-- SKILLS_TABLE_END -->";
+  const startIndex = content.indexOf(startMarker);
+  const endIndex = content.indexOf(endMarker);
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = content.slice(0, startIndex);
+    const after = content.slice(endIndex + endMarker.length);
+    return `${before}${skillsTable}${after}`.trimEnd() + "\n";
+  }
+
+  const block = buildSkillsSystemBlock(skillsTable);
+  if (!content.trim()) {
+    return `${block}\n`;
+  }
+  return `${content.trimEnd()}\n\n${block}\n`;
+}
+
+const { runInit } = require("../lib/init");
+
+program
+  .name("skillora")
+  .description("Install and load bundled Claude Code skills")
+  .version(pkg.version);
+
+program
+  .command("init")
+  .description("Initialize project with skills (interactive)")
+  .option(
+    "-p, --platform <platforms>",
+    "Platforms to configure (comma-separated: claude-code,cursor,codex,gemini,windsurf,aider)",
+  )
+  .option("-g, --global", "Install to global ~/.claude/skills/")
+  .option(
+    "-u, --universal",
+    "Install to .agent/skills/ (multi-agent compatible)",
+  )
+  .option("-f, --force", "Overwrite existing skills")
+  .action(async (options) => {
+    if (!fs.existsSync(bundledSkillsDir)) {
+      console.error("Bundled skills directory not found.");
+      process.exit(1);
+    }
+    try {
+      await runInit(options, bundledSkillsDir);
+    } catch (err) {
+      console.error("Error:", err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("install")
+  .description("Install bundled skills into the target directory")
+  .option("-g, --global", "Install globally (default: project install)")
+  .option("-u, --universal", "Install to .agent/skills (universal)")
+  .option("-t, --target <path>", "Install to a custom directory")
+  .option("-f, --force", "Overwrite existing skills")
+  .action((options) => {
+    if (!fs.existsSync(bundledSkillsDir)) {
+      console.error("Bundled skills directory not found.");
+      process.exit(1);
+    }
+
+    const targetDir = resolveTargetDir(options);
+    ensureDir(targetDir);
+
+    const skillDirs = listSkillDirs(bundledSkillsDir);
+    if (skillDirs.length === 0) {
+      console.log("No bundled skills found to install.");
+      return;
+    }
+
+    let installed = 0;
+    let skipped = 0;
+    for (const skillDir of skillDirs) {
+      const destDir = path.join(targetDir, path.basename(skillDir));
+      const result = copySkillDir(skillDir, destDir, options.force);
+      if (result.skipped) {
+        skipped += 1;
+      } else {
+        installed += 1;
+      }
+    }
+
+    console.log(`Installed: ${installed}, Skipped: ${skipped}`);
+    console.log(`Target: ${targetDir}`);
+  });
+
+program
+  .command("list")
+  .description("List installed skills in the target directory")
+  .option("-g, --global", "List global skills")
+  .option("-u, --universal", "List skills in .agent/skills")
+  .option("-t, --target <path>", "List skills in a custom directory")
+  .action((options) => {
+    const targetDir = resolveTargetDir(options);
+    const skillDirs = listSkillDirs(targetDir);
+    if (skillDirs.length === 0) {
+      console.log("No skills found.");
+      return;
+    }
+    for (const skillDir of skillDirs) {
+      console.log(path.basename(skillDir));
+    }
+  });
+
+program
+  .command("read <skill-name>")
+  .description("Read a skill to stdout (for AI agents)")
+  .option("-g, --global", "Read from global skills directory")
+  .option("-u, --universal", "Read from .agent/skills")
+  .option("-t, --target <path>", "Read from a custom directory")
+  .action((skillName, options) => {
+    let safeName;
+    try {
+      safeName = validateSkillName(skillName);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    const skillDir = findSkillDir(safeName, options);
+    if (!skillDir) {
+      console.error(`Skill not found: ${safeName}`);
+      process.exit(1);
+    }
+
+    const skillPath = path.join(skillDir, "SKILL.md");
+    let content;
+    try {
+      content = fs.readFileSync(skillPath, "utf8");
+    } catch (err) {
+      console.error(`Failed to read skill: ${err.message}`);
+      process.exit(1);
+    }
+    process.stdout.write(`Reading: ${safeName}\n`);
+    process.stdout.write(`Base directory: ${skillDir}\n\n`);
+    process.stdout.write(content);
+    if (!content.endsWith("\n")) {
+      process.stdout.write("\n");
+    }
+  });
+
+program
+  .command("sync")
+  .description("Update AGENTS.md with installed skills")
+  .option("-o, --output <path>", "Output file path (default: AGENTS.md)")
+  .option("-g, --global", "Sync global skills")
+  .option("-u, --universal", "Sync skills in .agent/skills")
+  .option("-t, --target <path>", "Sync skills from a custom directory")
+  .action((options) => {
+    const targetDir = resolveTargetDir(options);
+    const outputPath = options.output
+      ? path.resolve(options.output)
+      : path.join(process.cwd(), "AGENTS.md");
+
+    const skillDirs = listSkillDirs(targetDir);
+    const skills = skillDirs
+      .map(readSkillMeta)
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    const cliName = program.name();
+    const skillsTable = renderSkillsTable(skills, cliName);
+    const existing = fs.existsSync(outputPath)
+      ? fs.readFileSync(outputPath, "utf8")
+      : "";
+    const updated = updateAgentsMdContent(existing, skillsTable);
+    fs.writeFileSync(outputPath, updated, "utf8");
+
+    console.log(`Synced ${skills.length} skill(s) to ${outputPath}`);
+  });
+
+program
+  .command("remove <skill-name>")
+  .alias("rm")
+  .description("Remove a skill from the target directory")
+  .option("-g, --global", "Remove from global skills directory")
+  .option("-u, --universal", "Remove from .agent/skills")
+  .option("-t, --target <path>", "Remove from a custom directory")
+  .action((skillName, options) => {
+    let safeName;
+    try {
+      safeName = validateSkillName(skillName);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    const targetDir = resolveTargetDir(options);
+    const skillDir = path.join(targetDir, safeName);
+    if (!fs.existsSync(skillDir)) {
+      console.error(`Skill not found: ${safeName}`);
+      process.exit(1);
+    }
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    console.log(`Removed: ${safeName}`);
+  });
+
+program.parse();