@minhpnq1807/contextos 0.5.39 → 0.5.40

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.40
+
+- **Update notifier:** `ctx` now checks npm for newer versions in the background (once per day, 3s timeout). If a newer release exists, a boxed notice is printed at the very end of any command: `Update available: 0.5.39 → 0.5.40`. Check result is cached in `$CONTEXTOS_DATA/.update-check.json` to avoid repeated network calls.
+- **Community skill library browser (`ctx skills`):** New command to browse curated skill libraries from the community. Fetches and parses README files from 4 sources:
+  - [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) — 1,400+ universal skills
+  - [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Claude Code skills & workflows
+  - [awesome-codex-skills](https://github.com/ComposioHQ/awesome-codex-skills) — Codex CLI skills & automations
+  - [awesome-copilot](https://github.com/github/awesome-copilot) — GitHub Copilot instructions & agents
+  Results are cached for 24 hours. Use `--agents <names>` to filter and `--refresh` to force refetch.
+- **Post-install skill recommendations:** After interactive `ctx install` or `ctx setup`, a styled recommendation panel shows top 5 skills from each relevant library with descriptions and repo URLs. This guides new users toward useful community skills immediately after setup.
+- **Test stability:** Increased timeout for MCP bridge fallback test to prevent CI flakiness.
+
 ## 0.5.39
 
 - **Report layout fix:** Replaced ASCII table formatting with clean markdown output. Reports now render correctly in all agent UIs (Antigravity, Claude Code, Codex) without truncation or line-wrapping issues.

package/bin/ctx.js

@@ -34,6 +34,8 @@ import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthr
 import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
 import { multiSelect } from "../plugins/ctx/lib/multi-select.js";
 import { syncWorkflows, warmWorkflowEmbeddings } from "../plugins/ctx/lib/workflow-discoverer.js";
+import { checkForUpdate } from "../plugins/ctx/lib/update-notifier.js";
+import { fetchSkillsForAgents, printSkillRecommendations, getAllLibraries } from "../plugins/ctx/lib/skill-library.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -70,6 +72,9 @@ Usage:
   ctx sync --workflows                              Sync workflows across agents
   ctx sync --workflows --agents <names>             Sync workflows to specific agents
   ctx sync --workflows --dry-run                    Preview workflow sync without writing
+  ctx skills                                        Browse community skill libraries
+  ctx skills --agents <names>                       Filter skills for specific agents
+  ctx skills --refresh                              Force refresh skill library cache
   ctx embeddings warm -- "task"                     Pre-warm embedding caches for a task
   ctx ruler -- <ruler args>                         Passthrough to ruler CLI
   ctx skillshare -- <skillshare args>               Passthrough to skillshare CLI
@@ -608,6 +613,12 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
   console.log("│  Next: restart/open your agent from this project directory.");
   console.log("│  Try: ctx debug -- \"Recheck authen flow\"");
   console.log("");
+
+  // Recommend community skills based on selected agents
+  try {
+    const libraryResults = await fetchSkillsForAgents(options.agents, { dataDir: contextOSDataDir() });
+    printSkillRecommendations(libraryResults);
+  } catch { /* skill library is best-effort */ }
 }
 
 const args = process.argv.slice(2);
@@ -622,6 +633,8 @@ function installAgentsFromArgs(args) {
   return null; // no flag → interactive selection
 }
 
+const notifyUpdate = checkForUpdate({ currentVersion: packageVersion(), dataDir: contextOSDataDir() });
+
 try {
   if (!command || command === "--help" || command === "-h" || command === "help") {
     console.log(usage());
@@ -654,6 +667,11 @@ try {
           await streamSetupOutput(() => install({ copy, agent }));
           console.log("");
         }
+        // Recommend community skills based on selected agents
+        try {
+          const libraryResults = await fetchSkillsForAgents(selected, { dataDir: contextOSDataDir() });
+          printSkillRecommendations(libraryResults);
+        } catch { /* skill library is best-effort */ }
       }
     }
   } else if (command === "setup") {
@@ -682,6 +700,31 @@ try {
     const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
     if (!task.trim()) throw new Error('Usage: ctx benchmark -- "task"');
     console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
+  } else if (command === "skills") {
+    // Browse community skill libraries
+    const agentsFlag = args.indexOf("--agents");
+    const forceRefresh = args.includes("--refresh");
+    let agents;
+    if (agentsFlag >= 0 && args[agentsFlag + 1]) {
+      agents = args[agentsFlag + 1].split(",").map((a) => a.trim()).filter(Boolean);
+    } else {
+      agents = ["codex", "claude", "agy", "copilot"];
+    }
+    console.log("Fetching community skill libraries...\n");
+    const libraryResults = await fetchSkillsForAgents(agents, {
+      dataDir: contextOSDataDir()
+    });
+    printSkillRecommendations(libraryResults);
+    console.log("");
+    const totalSkills = libraryResults.reduce((sum, r) => sum + r.count, 0);
+    if (totalSkills === 0) {
+      console.log("No skills found. Check your network connection or try --refresh.");
+    } else {
+      console.log(`Total: ${totalSkills} skills across ${libraryResults.filter((r) => r.count > 0).length} libraries.`);
+      console.log("");
+      console.log("To install skills, visit the library URLs above or use:");
+      console.log("  ctx sync --skills       Sync skills across agents via skillshare");
+    }
   } else if (command === "sync") {
     if (args.includes("--workflows")) {
       await syncWorkflows({
@@ -719,4 +762,6 @@ try {
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;
+} finally {
+  await notifyUpdate();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.39",
+  "version": "0.5.40",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,290 @@
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import os from "node:os";
+
+/**
+ * Curated skill library sources, mapped by agent.
+ *
+ * Each source provides a GitHub repo with a README that lists available skills.
+ * We fetch the README, parse skill entries, and let the user pick from a
+ * multi-select panel after agent selection in `ctx install` or `ctx setup`.
+ */
+
+const SKILL_LIBRARIES = [
+  {
+    id: "antigravity-awesome",
+    name: "Antigravity Awesome Skills",
+    repo: "sickn33/antigravity-awesome-skills",
+    url: "https://github.com/sickn33/antigravity-awesome-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/sickn33/antigravity-awesome-skills/main/README.md",
+    agents: ["agy", "claude", "codex", "copilot"],   // universal library
+    description: "1,400+ agentic skills for all agents"
+  },
+  {
+    id: "awesome-claude",
+    name: "Awesome Claude Skills",
+    repo: "ComposioHQ/awesome-claude-skills",
+    url: "https://github.com/ComposioHQ/awesome-claude-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/ComposioHQ/awesome-claude-skills/main/README.md",
+    agents: ["claude"],
+    description: "Curated Claude Code skills & workflows"
+  },
+  {
+    id: "awesome-codex",
+    name: "Awesome Codex Skills",
+    repo: "ComposioHQ/awesome-codex-skills",
+    url: "https://github.com/ComposioHQ/awesome-codex-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/ComposioHQ/awesome-codex-skills/main/README.md",
+    agents: ["codex"],
+    description: "Practical Codex CLI skills & automations"
+  },
+  {
+    id: "awesome-copilot",
+    name: "Awesome Copilot",
+    repo: "github/awesome-copilot",
+    url: "https://github.com/github/awesome-copilot",
+    rawReadmeUrl: "https://raw.githubusercontent.com/github/awesome-copilot/main/README.md",
+    agents: ["copilot"],
+    description: "Community GitHub Copilot instructions & agents"
+  }
+];
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 1 day
+
+// ────────────────────────────── HTTP fetch ────────────────────────────────
+
+function fetchUrl(url, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { timeout: timeoutMs }, (res) => {
+      // Follow redirects (301/302/307/308)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        fetchUrl(res.headers.location, timeoutMs).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        res.resume();
+        return;
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      res.on("error", reject);
+    });
+    req.on("timeout", () => { req.destroy(); reject(new Error(`Timeout fetching ${url}`)); });
+    req.on("error", reject);
+  });
+}
+
+// ────────────────────────────── README parser ─────────────────────────────
+
+/**
+ * Parse a GitHub awesome-list README and extract skill entries.
+ *
+ * Looks for markdown links in list items:
+ *   - [Skill Name](url) - Description
+ *   - **[Skill Name](url)** — Description
+ *
+ * Returns: Array<{ name, url, description }>
+ */
+export function parseSkillEntries(readmeContent) {
+  const entries = [];
+  const lines = readmeContent.split("\n");
+  // Match list items with markdown links
+  const linkPattern = /^[-*]\s+\**\[([^\]]+)\]\(([^)]+)\)\**\s*[-–—:]*\s*(.*)/;
+  for (const line of lines) {
+    const match = line.match(linkPattern);
+    if (!match) continue;
+    const [, name, url, description] = match;
+    // Skip non-skill links (images, badges, section headers)
+    if (/\.(png|jpg|svg|gif)$/i.test(url)) continue;
+    if (url.startsWith("#")) continue;
+    entries.push({
+      name: name.trim(),
+      url: url.trim(),
+      description: (description || "").replace(/^\s*[-–—:]+\s*/, "").trim()
+    });
+  }
+  return entries;
+}
+
+// ────────────────────────────── Cache layer ────────────────────────────────
+
+function cacheDir(dataDir) {
+  return path.join(dataDir, "skill-library-cache");
+}
+
+function cacheFilePath(dataDir, libraryId) {
+  return path.join(cacheDir(dataDir), `${libraryId}.json`);
+}
+
+function readCache(dataDir, libraryId) {
+  const filePath = cacheFilePath(dataDir, libraryId);
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    if (Date.now() - (data.fetchedAt || 0) < CACHE_TTL_MS) {
+      return data.entries || [];
+    }
+  } catch { /* cache miss */ }
+  return null;
+}
+
+function writeCache(dataDir, libraryId, entries) {
+  const dir = cacheDir(dataDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const data = { fetchedAt: Date.now(), entries };
+  fs.writeFileSync(cacheFilePath(dataDir, libraryId), JSON.stringify(data, null, 2));
+}
+
+// ────────────────────────────── Public API ─────────────────────────────────
+
+/**
+ * Get libraries relevant to selected agents.
+ */
+export function getLibrariesForAgents(selectedAgents) {
+  const normalized = selectedAgents.map((a) => a.toLowerCase().replace("antigravity", "agy"));
+  return SKILL_LIBRARIES.filter((lib) =>
+    lib.agents.some((agent) => normalized.includes(agent))
+  );
+}
+
+/**
+ * Fetch skill entries from a library (with caching).
+ */
+export async function fetchLibrarySkills(library, { dataDir, forceRefresh = false } = {}) {
+  if (dataDir && !forceRefresh) {
+    const cached = readCache(dataDir, library.id);
+    if (cached) return { entries: cached, source: "cache" };
+  }
+
+  try {
+    const readme = await fetchUrl(library.rawReadmeUrl);
+    const entries = parseSkillEntries(readme);
+    if (dataDir && entries.length > 0) {
+      writeCache(dataDir, library.id, entries);
+    }
+    return { entries, source: "network" };
+  } catch (error) {
+    // Try cache even if expired on network failure
+    if (dataDir) {
+      try {
+        const filePath = cacheFilePath(dataDir, library.id);
+        const raw = fs.readFileSync(filePath, "utf8");
+        const data = JSON.parse(raw);
+        return { entries: data.entries || [], source: "stale-cache" };
+      } catch { /* no cache at all */ }
+    }
+    return { entries: [], source: "error", error: error.message };
+  }
+}
+
+/**
+ * Fetch skills from all relevant libraries for selected agents.
+ * Returns a flat list grouped by library.
+ */
+export async function fetchSkillsForAgents(selectedAgents, { dataDir } = {}) {
+  const libraries = getLibrariesForAgents(selectedAgents);
+  const results = [];
+
+  for (const lib of libraries) {
+    const { entries, source } = await fetchLibrarySkills(lib, { dataDir });
+    results.push({
+      library: lib,
+      entries,
+      source,
+      count: entries.length
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Format skill library results as multi-select options.
+ * Groups by library with a header option (disabled).
+ */
+export function formatAsSelectOptions(libraryResults) {
+  const options = [];
+  for (const result of libraryResults) {
+    if (result.entries.length === 0) continue;
+    // Add library header as separator
+    options.push({
+      label: `── ${result.library.name} (${result.count} skills) ──`,
+      value: `__header__${result.library.id}`,
+      disabled: true,
+      isHeader: true
+    });
+    // Add top skills (limit to prevent overwhelming the user)
+    const topEntries = result.entries.slice(0, 30);
+    for (const entry of topEntries) {
+      const desc = entry.description ? ` — ${entry.description.slice(0, 60)}` : "";
+      options.push({
+        label: `${entry.name}${desc}`,
+        value: entry.url,
+        selected: false,
+        libraryId: result.library.id,
+        skillName: entry.name
+      });
+    }
+    if (result.entries.length > 30) {
+      options.push({
+        label: `  ... and ${result.entries.length - 30} more at ${result.library.url}`,
+        value: `__more__${result.library.id}`,
+        disabled: true,
+        isHeader: true
+      });
+    }
+  }
+  return options;
+}
+
+/**
+ * Print a compact recommendation panel to the terminal.
+ * Used after agent selection in `ctx install` and `ctx setup`.
+ */
+export function printSkillRecommendations(libraryResults, { logger = console.log } = {}) {
+  const DIM = "\x1B[2m";
+  const RESET = "\x1B[0m";
+  const CYAN = "\x1B[36m";
+  const GREEN = "\x1B[32m";
+  const YELLOW = "\x1B[33m";
+  const BOLD = "\x1B[1m";
+
+  const hasSkills = libraryResults.some((r) => r.entries.length > 0);
+  if (!hasSkills) return;
+
+  logger("");
+  logger(`${CYAN}◇${RESET} ${BOLD}Community skill libraries available:${RESET}`);
+  logger(`${DIM}│${RESET}  Browse and install curated skills from the community.`);
+  logger(`${DIM}│${RESET}`);
+
+  for (const result of libraryResults) {
+    if (result.entries.length === 0) continue;
+    const badge = result.source === "cache" ? `${DIM}(cached)${RESET}` : "";
+    logger(`${DIM}│${RESET}  ${GREEN}●${RESET} ${BOLD}${result.library.name}${RESET} ${badge}`);
+    logger(`${DIM}│${RESET}    ${result.count} skills · ${result.library.description}`);
+    logger(`${DIM}│${RESET}    ${DIM}${result.library.url}${RESET}`);
+
+    // Show top 5 skills as preview
+    const preview = result.entries.slice(0, 5);
+    for (const skill of preview) {
+      const desc = skill.description ? ` ${DIM}— ${skill.description.slice(0, 50)}${RESET}` : "";
+      logger(`${DIM}│${RESET}      ${YELLOW}▸${RESET} ${skill.name}${desc}`);
+    }
+    if (result.entries.length > 5) {
+      logger(`${DIM}│${RESET}      ${DIM}... and ${result.entries.length - 5} more${RESET}`);
+    }
+    logger(`${DIM}│${RESET}`);
+  }
+
+  logger(`${DIM}│${RESET}  ${DIM}Run ${CYAN}ctx skills${RESET}${DIM} to browse and install community skills.${RESET}`);
+}
+
+/**
+ * Get all library definitions.
+ */
+export function getAllLibraries() {
+  return SKILL_LIBRARIES;
+}

package/plugins/ctx/lib/update-notifier.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PACKAGE_NAME = "@minhpnq1807/contextos";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
+const REQUEST_TIMEOUT_MS = 3000;
+
+function cacheFilePath(dataDir) {
+  return path.join(dataDir, ".update-check.json");
+}
+
+function readCache(dataDir) {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFilePath(dataDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(dataDir, data) {
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(cacheFilePath(dataDir), JSON.stringify(data), "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+async function fetchLatestVersion() {
+  const https = await import("node:https");
+  return new Promise((resolve) => {
+    const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+    const req = https.get(url, { timeout: REQUEST_TIMEOUT_MS, headers: { accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return resolve(null);
+      }
+      let body = "";
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body).version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+function compareVersions(current, latest) {
+  const parse = (v) => String(v || "").replace(/^v/, "").split(".").map(Number);
+  const c = parse(current);
+  const l = parse(latest);
+  for (let i = 0; i < 3; i++) {
+    if ((l[i] || 0) > (c[i] || 0)) return 1;
+    if ((l[i] || 0) < (c[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Check for updates in background (non-blocking).
+ * Returns a function that, when called, prints the update message if available.
+ *
+ * Usage:
+ *   const notify = checkForUpdate({ currentVersion, dataDir });
+ *   // ... run CLI command ...
+ *   await notify(); // prints update message at the very end
+ */
+export function checkForUpdate({ currentVersion, dataDir }) {
+  let resultPromise = null;
+
+  // Start background check lazily
+  function startCheck() {
+    if (resultPromise) return resultPromise;
+    resultPromise = (async () => {
+      try {
+        const cache = readCache(dataDir);
+        const isFresh = cache && typeof cache.checkedAt === "number" && (Date.now() - cache.checkedAt < CHECK_INTERVAL_MS);
+
+        if (isFresh) {
+          return cache.latestVersion && compareVersions(currentVersion, cache.latestVersion) > 0
+            ? cache.latestVersion
+            : null;
+        }
+
+        const latestVersion = await fetchLatestVersion();
+        if (latestVersion) {
+          writeCache(dataDir, { checkedAt: Date.now(), latestVersion });
+        }
+
+        return latestVersion && compareVersions(currentVersion, latestVersion) > 0
+          ? latestVersion
+          : null;
+      } catch {
+        return null;
+      }
+    })();
+    return resultPromise;
+  }
+
+  // Start immediately (non-blocking)
+  startCheck();
+
+  return async () => {
+    const latestVersion = await startCheck();
+    if (latestVersion) {
+      console.error(formatUpdateBox(currentVersion, latestVersion));
+    }
+  };
+}
+
+function formatUpdateBox(currentVersion, latestVersion) {
+  const lines = [
+    `Update available: ${currentVersion} → ${latestVersion}`,
+    "",
+    `Run: npm install -g ${PACKAGE_NAME}`,
+    `Then run: ctx install --agents codex`,
+  ];
+  const maxLen = lines.reduce((m, l) => Math.max(m, l.length), 0);
+  const width = maxLen + 4;
+  const pad = (text) => `│ ${text.padEnd(width - 4)} │`;
+  const top = `╭${"─".repeat(width - 2)}╮`;
+  const bottom = `╰${"─".repeat(width - 2)}╯`;
+  return ["", top, ...lines.map(pad), bottom, ""].join("\n");
+}