@minhpnq1807/contextos 0.2.0 → 0.5.0

package/plugins/ctx/lib/skill-discoverer.js

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { enhanceRuleScoresWithEmbeddings, warmRuleEmbeddings } from "./embedding-scorer.js";
+
+const DEFAULT_LIMIT = 3;
+const DEFAULT_MAX_SKILLS = 2000;
+const DEFAULT_EMBEDDING_CANDIDATES = 120;
+const DEFAULT_SEMANTIC_CATALOG_LIMIT = 300;
+
+export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return [
+    path.join(cwd, ".codex", "skills"),
+    path.join(cwd, ".claude", "skills"),
+    path.join(cwd, ".gemini", "skills"),
+    path.join(cwd, ".gemini", "antigravity", "skills"),
+    path.join(cwd, ".gemini", "antigravity-cli", "skills"),
+    path.join(home, ".config", "skillshare", "skills"),
+    path.join(home, ".codex", "skills"),
+    path.join(home, ".claude", "skills"),
+    path.join(home, ".gemini", "skills"),
+    path.join(home, ".gemini", "antigravity", "skills"),
+    path.join(home, ".gemini", "antigravity-cli", "skills")
+  ];
+}
+
+export function parseSkillFrontmatter(content = "", { fallbackName = "", skillPath = "" } = {}) {
+  const text = String(content || "");
+  const frontmatter = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
+  const fields = frontmatter ? parseYamlishFields(frontmatter[1]) : {};
+  const body = frontmatter ? text.slice(frontmatter[0].length) : text;
+  const fallbackDescription = firstParagraph(body);
+  return {
+    name: fields.name || fallbackName || path.basename(path.dirname(skillPath)),
+    description: fields.description || fallbackDescription,
+    path: skillPath
+  };
+}
+
+function parseYamlishFields(frontmatter) {
+  const fields = {};
+  const lines = String(frontmatter || "").split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    value = value.replace(/^["']|["']$/g, "");
+    fields[key] = value;
+  }
+  return fields;
+}
+
+function firstParagraph(body) {
+  return String(body || "")
+    .split(/\n\s*\n/)
+    .map((part) => part.replace(/^#+\s*/gm, "").replace(/\s+/g, " ").trim())
+    .find(Boolean) || "";
+}
+
+export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd }), maxSkills = DEFAULT_MAX_SKILLS } = {}) {
+  const skills = [];
+  const seen = new Set();
+  for (const root of roots) {
+    for (const skillPath of findSkillFiles(root)) {
+      if (skills.length >= maxSkills) return skills;
+      const realPath = safeRealpath(skillPath) || skillPath;
+      if (seen.has(realPath)) continue;
+      seen.add(realPath);
+      let content = "";
+      try {
+        content = fs.readFileSync(skillPath, "utf8");
+      } catch {
+        continue;
+      }
+      const skill = parseSkillFrontmatter(content, {
+        fallbackName: path.basename(path.dirname(skillPath)),
+        skillPath
+      });
+      if (!skill.name || !skill.description) continue;
+      skills.push({
+        ...skill,
+        root,
+        scope: isInsidePath(skillPath, cwd) ? "project" : "global",
+        relativePath: path.relative(cwd, skillPath)
+      });
+    }
+  }
+  return skills;
+}
+
+function findSkillFiles(root) {
+  const files = [];
+  walk(root, 0, files);
+  return files;
+}
+
+function walk(directory, depth, files) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      walk(fullPath, depth + 1, files);
+    } else if (entry.isFile() && entry.name === "SKILL.md") {
+      files.push(fullPath);
+    }
+  }
+}
+
+function safeRealpath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(path.resolve(parentPath), path.resolve(filePath));
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export async function suggestSkills({
+  prompt = "",
+  skills = [],
+  dataDir,
+  limit = DEFAULT_LIMIT,
+  timeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800)
+} = {}) {
+  if (!String(prompt || "").trim() || !skills.length) return [];
+  const base = scoreSkillsByKeyword({ prompt, skills });
+  if (skills.length > DEFAULT_SEMANTIC_CATALOG_LIMIT) {
+    return finalizeSkillScores(base, limit);
+  }
+
+  const embeddingCandidates = selectEmbeddingCandidates(base);
+  if (!embeddingCandidates.length) return [];
+
+  const embedding = await enhanceRuleScoresWithEmbeddings(embeddingCandidates, prompt, {
+    dataDir,
+    sources: embeddingCandidates.map((skill) => skill.path).filter(Boolean),
+    timeoutMs,
+    allowRemote: false
+  });
+
+  return finalizeSkillScores(embedding.rules, limit);
+}
+
+function finalizeSkillScores(skills, limit) {
+  return skills
+    .map((rule) => ({
+      name: rule.name,
+      description: rule.description,
+      path: rule.path,
+      scope: rule.scope,
+      keywordScore: rule.keywordScore,
+      score: Math.min(1, Number(rule.score || 0)),
+      embeddingScore: rule.embeddingScore,
+      reasons: rule.reasons || []
+    }))
+    .filter((skill) => Number(skill.keywordScore || 0) >= 0.35 || Number(skill.embeddingScore || 0) >= 0.62)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, limit);
+}
+
+function selectEmbeddingCandidates(skills) {
+  if (skills.length <= DEFAULT_EMBEDDING_CANDIDATES) return skills;
+  return [...skills]
+    .filter((skill) => Number(skill.keywordScore || 0) > 0)
+    .sort((a, b) => Number(b.keywordScore || 0) - Number(a.keywordScore || 0) || a.name.localeCompare(b.name))
+    .slice(0, DEFAULT_EMBEDDING_CANDIDATES);
+}
+
+export async function warmSkillEmbeddings({
+  cwd = process.cwd(),
+  dataDir,
+  allowRemote = true,
+  skills = scanSkills({ cwd })
+} = {}) {
+  if (!dataDir || !skills.length) return { count: 0, cachePath: null };
+  return warmRuleEmbeddings({
+    rules: skills.map((skill) => ({ content: `${skill.name} ${skill.description}` })),
+    task: "skill discovery semantic retrieval",
+    dataDir,
+    sources: skills.map((skill) => skill.path).filter(Boolean),
+    allowRemote
+  });
+}
+
+function scoreSkillsByKeyword({ prompt, skills }) {
+  const normalizedPrompt = normalize(prompt);
+  const promptTokens = new Set(normalizedPrompt.split(/\s+/).filter(Boolean));
+  return skills.map((skill, index) => {
+    const name = String(skill.name || "");
+    const description = String(skill.description || "");
+    const content = `${name} ${description}`;
+    const skillTokens = new Set(normalize(content).split(/\s+/).filter(Boolean));
+    const matches = [...skillTokens].filter((token) => promptTokens.has(token) && token.length > 2);
+    const normalizedName = normalize(name);
+    const nameTokens = normalizedName.split(/\s+/).filter((token) => token.length > 2);
+    const nameHit = normalizedPrompt.includes(normalizedName);
+    const nameTokenHit = nameTokens.length > 1 && nameTokens.every((token) => promptTokens.has(token));
+    const scopeBonus = skill.scope === "project" ? 0.08 : 0;
+    const score = Math.min(1, (matches.length ? 0.25 + matches.length * 0.08 : 0) + (nameHit ? 0.2 : 0) + (nameTokenHit ? 0.18 : 0) + scopeBonus);
+    return {
+      id: `skill-${index + 1}`,
+      name,
+      description,
+      path: skill.path,
+      scope: skill.scope,
+      content,
+      score,
+      keywordScore: score,
+      reasons: [
+        ...(matches.length ? [`keyword:${matches.slice(0, 4).join(",")}`] : []),
+        ...(nameHit || nameTokenHit ? ["name-match"] : [])
+      ],
+      originalOrder: index
+    };
+  });
+}
+
+function normalize(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}

package/plugins/ctx/lib/skillshare-sync.js

@@ -0,0 +1,239 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync, execSync } from "node:child_process";
+
+const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
+const INSTALL_SH_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.sh";
+const INSTALL_PS_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1";
+
+function statusLine(label, value) {
+  return `[ctx] ${label.padEnd(38)} ${value}`;
+}
+
+function runCommand(command, args = [], { cwd = process.cwd(), stdio = "pipe", dryRun = false } = {}) {
+  if (dryRun) return { stdout: "", skipped: true };
+  const stdout = execFileSync(command, args, { cwd, stdio, encoding: "utf8" });
+  return { stdout: stdout || "" };
+}
+
+function runShell(command, { cwd = process.cwd(), stdio = "inherit", dryRun = false } = {}) {
+  if (dryRun) return { stdout: "", skipped: true };
+  const stdout = execSync(command, { cwd, stdio, encoding: "utf8" });
+  return { stdout: stdout || "" };
+}
+
+export function parseSyncSkillsArgs(args = []) {
+  const agentsFlag = args.indexOf("--agents");
+  const agents = agentsFlag >= 0
+    ? String(args[agentsFlag + 1] || "").split(",").map((item) => item.trim()).filter(Boolean)
+    : DEFAULT_AGENTS;
+  return {
+    skills: args.includes("--skills"),
+    agents,
+    dryRun: args.includes("--dry-run"),
+    noCollect: args.includes("--no-collect"),
+    yes: args.includes("--yes") || args.includes("-y")
+  };
+}
+
+export function detectOS(platform = process.platform) {
+  if (platform === "darwin") return "mac";
+  if (platform === "win32") return "windows";
+  return "linux";
+}
+
+export function skillshareConfigDir({ home = os.homedir() } = {}) {
+  return path.join(home, ".config", "skillshare");
+}
+
+export function skillshareSourceDir({ home = os.homedir() } = {}) {
+  return path.join(skillshareConfigDir({ home }), "skills");
+}
+
+export function checkSkillshareInstalled({ run = runCommand } = {}) {
+  try {
+    const result = run("skillshare", ["--version"]);
+    return { installed: true, version: result.stdout.trim() || "installed" };
+  } catch {
+    return { installed: false, version: "" };
+  }
+}
+
+async function shouldInstallSkillshare({ yes = false } = {}) {
+  if (yes) return true;
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("[ctx] skillshare is not installed. Install now? [Y/n] ");
+    return !/^n(o)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function installSkillshare({
+  run = runCommand,
+  runShellCommand = runShell,
+  yes = false,
+  dryRun = false,
+  platform = process.platform
+} = {}) {
+  const accepted = dryRun || await shouldInstallSkillshare({ yes });
+  if (!accepted) {
+    throw new Error("skillshare is required for ctx sync --skills. Install it manually with `curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh` or rerun with --yes.");
+  }
+
+  const osName = detectOS(platform);
+  if (osName === "windows") {
+    run("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", `irm ${INSTALL_PS_URL} | iex`], { stdio: "inherit", dryRun });
+  } else {
+    runShellCommand(`curl -fsSL ${INSTALL_SH_URL} | sh`, { stdio: "inherit", dryRun });
+  }
+
+  const check = checkSkillshareInstalled({ run });
+  if (!dryRun && !check.installed) {
+    throw new Error("skillshare install finished but `skillshare --version` still failed. Check PATH or install skillshare manually.");
+  }
+  return check;
+}
+
+export function detectExistingSkills({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return skillRoots({ cwd, home })
+    .map((root) => ({ path: root, count: countSkillFiles(root) }))
+    .filter((entry) => entry.count > 0);
+}
+
+function skillRoots({ cwd, home }) {
+  return [
+    path.join(home, ".claude", "skills"),
+    path.join(home, ".codex", "skills"),
+    path.join(home, ".gemini", "antigravity", "skills"),
+    path.join(home, ".gemini", "antigravity-cli", "skills"),
+    path.join(cwd, ".claude", "skills"),
+    path.join(cwd, ".codex", "skills"),
+    path.join(cwd, ".gemini", "antigravity", "skills"),
+    path.join(cwd, ".gemini", "antigravity-cli", "skills")
+  ];
+}
+
+function countSkillFiles(root) {
+  return findSkillFiles(root).length;
+}
+
+function findSkillFiles(root) {
+  const files = [];
+  walk(root, 0, files);
+  return files;
+}
+
+function walk(directory, depth, files) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) {
+      const stat = safeStat(fullPath);
+      if (stat?.isDirectory()) walk(fullPath, depth + 1, files);
+    } else if (entry.isDirectory()) {
+      walk(fullPath, depth + 1, files);
+    } else if (entry.isFile() && entry.name === "SKILL.md") {
+      files.push(fullPath);
+    }
+  }
+}
+
+function safeStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export function isSkillshareInitialized({ home = os.homedir() } = {}) {
+  return fs.existsSync(skillshareConfigDir({ home }));
+}
+
+export async function syncSkills({
+  cwd = process.cwd(),
+  home = os.homedir(),
+  args = [],
+  run = runCommand,
+  runShellCommand = runShell,
+  logger = console.log,
+  rebuildSkillEmbeddings = async () => ({ count: 0, cachePath: null })
+} = {}) {
+  const options = parseSyncSkillsArgs(args);
+  if (!options.skills) throw new Error("Usage: ctx sync --skills [--dry-run] [--no-collect] [--agents codex,claude,antigravity]");
+
+  const installed = checkSkillshareInstalled({ run });
+  logger(statusLine("Checking skillshare installation...", installed.installed ? `✓ ${installed.version}` : "not found"));
+  if (!installed.installed) {
+    logger("");
+    logger("skillshare is required to sync skills across agents.");
+    const postInstall = await installSkillshare({
+      run,
+      runShellCommand,
+      yes: options.yes,
+      dryRun: options.dryRun,
+      platform: process.platform
+    });
+    logger(statusLine("Installing skillshare...", options.dryRun ? "dry-run" : `✓ ${postInstall.version}`));
+  }
+
+  const initialized = isSkillshareInitialized({ home });
+  logger(statusLine("Checking skillshare config...", initialized ? "✓ initialized" : "not initialized"));
+
+  if (!initialized) {
+    const existing = detectExistingSkills({ cwd, home });
+    if (existing.length) {
+      logger("[ctx] Found existing skills:");
+      for (const entry of existing) {
+        logger(`      ${entry.path.padEnd(44)} ${entry.count} skills`);
+      }
+      if (!options.noCollect) {
+        run("skillshare", ["backup"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+        logger(statusLine("Backing up...", options.dryRun ? "dry-run" : "✓ backup created"));
+      }
+    } else {
+      logger("[ctx] No existing skills found.");
+    }
+
+    run("skillshare", ["init"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+    logger(statusLine("Initializing skillshare...", options.dryRun ? "dry-run" : "✓ initialized"));
+
+    if (existing.length && !options.noCollect) {
+      run("skillshare", ["collect", "--all"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+      const collected = countSkillFiles(skillshareSourceDir({ home }));
+      logger(statusLine("Collecting from all agents...", options.dryRun ? "dry-run" : `✓ ${collected} skills collected`));
+    }
+  }
+
+  const syncArgs = ["sync"];
+  if (options.dryRun) syncArgs.push("--dry-run");
+  if (options.agents.length) syncArgs.push("--agents", options.agents.join(","));
+  run("skillshare", syncArgs, { cwd, stdio: "inherit", dryRun: false });
+  const syncedCount = countSkillFiles(skillshareSourceDir({ home }));
+  logger(statusLine("Running skillshare sync...", options.dryRun ? "dry-run" : `✓ ${syncedCount} skills → ${options.agents.join(", ")}`));
+
+  let embeddings = { count: 0, cachePath: null, skipped: options.dryRun };
+  if (!options.dryRun) {
+    embeddings = await rebuildSkillEmbeddings({ cwd, home, sourceDir: skillshareSourceDir({ home }) });
+    logger(statusLine("Rebuilding skill embeddings...", `✓ ${embeddings.count || 0} skills indexed`));
+  } else {
+    logger(statusLine("Rebuilding skill embeddings...", "skipped in dry-run"));
+  }
+
+  logger("");
+  logger("Done. Skills are now synced.");
+  logger(`Source: ${skillshareSourceDir({ home })}`);
+  return { options, initialized, sourceDir: skillshareSourceDir({ home }), syncedCount, embeddings };
+}

package/plugins/ctx/lib/stop-hook.js

@@ -5,9 +5,10 @@ import { readGitSnapshot, checkCompliance } from "./measure.js";
 import { buildReport, formatReport } from "./reporter.js";
 import { loadRuntimeEvidence } from "./telemetry.js";
 import { filterActionableRules } from "./analyzer.js";
+import { resolveHookCwd } from "./hook-io.js";
 
 export function handleStopPayload(payload, { contextPath, reportPath, historyPath, telemetryPath } = {}) {
-  const cwd = payload.cwd || payload.working_directory || process.cwd();
+  const cwd = resolveHookCwd(payload);
   const promptContext = contextPath && fs.existsSync(contextPath) ? readJsonFile(contextPath) : null;
   const rawScheduledRules = [
     ...(promptContext?.scheduled?.highRules || []),

package/plugins/ctx/mcp/contextos-server.js

@@ -11,16 +11,23 @@ export function createContextOSMcpServer({ dataDir }) {
 
   server.registerTool("ctx_score_context", {
     title: "Score ContextOS prompt context",
-    description: "Scores AGENTS.md rules and suggests files for a Codex prompt.",
+    description: "Scores AGENTS.md rules and suggests files/skills for an agent prompt.",
     inputSchema: {
       cwd: z.string().optional(),
       prompt: z.string(),
       openFiles: z.array(z.string()).optional(),
-      maxFiles: z.number().int().positive().max(20).optional()
+      maxFiles: z.number().int().positive().max(20).optional(),
+      maxSkills: z.number().int().positive().max(10).optional(),
+      skills: z.array(z.object({
+        name: z.string(),
+        description: z.string(),
+        path: z.string().optional()
+      })).optional()
     },
     outputSchema: {
       scoredRules: z.array(z.any()),
       suggestedFiles: z.array(z.any()),
+      suggestedSkills: z.array(z.any()),
       telemetry: z.record(z.string(), z.any())
     }
   }, async (args) => {
@@ -29,7 +36,9 @@ export function createContextOSMcpServer({ dataDir }) {
       prompt: args.prompt || "",
       openFiles: args.openFiles || [],
       dataDir,
-      maxFiles: args.maxFiles || 5
+      maxFiles: args.maxFiles || 5,
+      maxSkills: args.maxSkills || 3,
+      skills: args.skills
     });
     return {
       content: [
@@ -41,6 +50,7 @@ export function createContextOSMcpServer({ dataDir }) {
       structuredContent: {
         scoredRules: result.scoredRules,
         suggestedFiles: result.suggestedFiles,
+        suggestedSkills: result.suggestedSkills,
         telemetry: result.telemetry
       }
     };

package/plugins/ctx/mcp/server.js

@@ -68,7 +68,9 @@ async function handleBridgeRequest(socket, raw) {
       prompt: payload.prompt || "",
       openFiles: payload.openFiles || [],
       dataDir,
-      maxFiles: payload.maxFiles || 5
+      maxFiles: payload.maxFiles || 5,
+      maxSkills: payload.maxSkills || 3,
+      skills: payload.skills
     });
     socket.end(JSON.stringify(result));
   } catch (error) {
@@ -76,6 +78,7 @@ async function handleBridgeRequest(socket, raw) {
       error: error?.message || String(error),
       scoredRules: [],
       suggestedFiles: [],
+      suggestedSkills: [],
       telemetry: { elapsedMs: 0, modelStatus: "error" }
     }));
   }