@starlens-app/cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlens-app/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Starlens CLI — manage your GitHub starred repositories from the terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "src/index.mjs",
+    "skills/",
     "README.md"
   ],
   "engines": {

package/skills/starlens/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: starlens
+description: Use when an agent runtime such as Hermes, OpenClaw, custom HTTP agents, or coding assistants needs to search, inspect, organize, tag, sync, or ask questions over a user's GitHub starred repositories stored in StarLens. Prefer this skill for agent-side StarLens integration through HTTP APIs with STARLENS_API_BASE_URL and STARLENS_TOKEN.
+---
+
+# StarLens
+
+## Purpose
+
+Use StarLens as the user's searchable memory of GitHub starred repositories. This skill tells an agent when and how to call StarLens over HTTP.
+
+Prefer HTTP API access for Hermes, OpenClaw, server-side agents, remote workers, and containerized runtimes. Use MCP only for IDE or terminal clients that natively support MCP.
+
+## Required Configuration
+
+Read these values from the agent runtime environment, secret store, or project config:
+
+```bash
+STARLENS_API_BASE_URL="https://starlens.example.com"
+STARLENS_TOKEN="stl_xxx"
+```
+
+Send every API request with:
+
+```http
+Authorization: Bearer ${STARLENS_TOKEN}
+Accept: application/json
+```
+
+For JSON request bodies, also send:
+
+```http
+Content-Type: application/json
+```
+
+Never print, log, summarize, or store `STARLENS_TOKEN` in model-visible output.
+
+## Workflow
+
+1. Normalize the user's intent into one of these operations: search, inspect, sync, favorite, note, tag, or ask.
+2. Use `GET /api/search` first when the user gives a repository topic, keyword, language, tag, owner, or partial repository name.
+3. Use `GET /api/repos/{idOrFullName}` when the user gives a concrete repository id or `owner/repo`.
+4. Use write endpoints only when the user clearly asks to modify StarLens state, such as adding a note, tagging a repo, or marking a favorite.
+5. Use `POST /api/ai/ask` when the user asks for synthesis across starred repositories.
+6. Return concise answers with repository names, URLs when available, and the reason each result is relevant.
+
+Read `references/http-api.md` when you need exact endpoint parameters, request bodies, or response handling.
+
+## Behavior Rules
+
+- Treat StarLens as private user data. Do not expose results beyond the current task.
+- Prefer specific queries over broad scans. Ask a follow-up only when the request cannot be mapped to a safe query.
+- If a repository lookup by id or `owner/repo` returns 404, search by that same text before reporting failure.
+- If the API returns 401, tell the user the StarLens token is missing, expired, or revoked.
+- If the API returns 429 or 5xx, retry at most once with a short delay, then report the service issue.
+- Do not create API tokens. Token management is browser-session only.
+- Do not use MCP for Hermes/OpenClaw-style runtimes unless the user explicitly says that runtime supports MCP and wants it.
+
+## Common Examples
+
+Search vector database stars:
+
+```bash
+curl "$STARLENS_API_BASE_URL/api/search?q=vector%20database&page=1&pageSize=10&sort=relevance" \
+  -H "Authorization: Bearer $STARLENS_TOKEN" \
+  -H "Accept: application/json"
+```
+
+Ask across starred repositories:
+
+```bash
+curl -X POST "$STARLENS_API_BASE_URL/api/ai/ask" \
+  -H "Authorization: Bearer $STARLENS_TOKEN" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{"question":"哪些 starred repos 适合做本地 RAG 原型？"}'
+```

package/skills/starlens/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "StarLens Agent"
+  short_description: "Use StarLens HTTP APIs from agent runtimes."
+  default_prompt: "Use the StarLens skill to search, inspect, organize, and ask questions over GitHub starred repositories through the configured HTTP API."

package/skills/starlens/references/http-api.md

@@ -0,0 +1,100 @@
+# StarLens HTTP API
+
+All endpoints are relative to `STARLENS_API_BASE_URL`.
+
+## Response Envelope
+
+Successful responses use:
+
+```json
+{ "ok": true, "data": {} }
+```
+
+Failed responses use:
+
+```json
+{ "ok": false, "error": { "code": "string", "message": "string" } }
+```
+
+If `ok` is not `true`, treat the request as failed even when the HTTP status is unexpected.
+
+## Authentication
+
+Use a personal StarLens API token:
+
+```http
+Authorization: Bearer stl_xxx
+Accept: application/json
+```
+
+## Search Stars
+
+`GET /api/search`
+
+Query parameters:
+
+| Name | Type | Notes |
+| --- | --- | --- |
+| `q` | string | Keyword, topic, repo name, owner, or natural query. |
+| `page` | integer | Defaults to `1`. |
+| `pageSize` | integer | Use `10` to `20` for agent answers. |
+| `sort` | string | `relevance`, `recent`, `stars`, or `updated`. |
+| `language` | string | Filter by repository language. |
+| `owner` | string | Filter by GitHub owner. |
+| `tag` | string | Filter by StarLens tag. |
+| `favorite` | boolean | Filter favorites. |
+
+Use this endpoint before detail lookup when the user provides a topic, partial name, or ambiguous repository reference.
+
+## Repository Detail
+
+`GET /api/repos/{idOrFullName}`
+
+`idOrFullName` can be a StarLens repository id or `owner/repo`. If it returns 404, search the same text with `/api/search` before giving up.
+
+## Sync Stars
+
+`POST /api/sync`
+
+Trigger GitHub Stars sync for the authenticated StarLens user. Use only when the user asks to refresh or sync.
+
+## Update Repository State
+
+`PATCH /api/repos/{idOrFullName}`
+
+Body fields:
+
+```json
+{
+  "isFavorite": true,
+  "note": "Short user note"
+}
+```
+
+Send only fields that should change. Use an empty `note` string only when the user asks to clear a note.
+
+## Tags
+
+Add a tag:
+
+`POST /api/repos/{idOrFullName}/tags`
+
+```json
+{ "tag": "rag" }
+```
+
+Remove a tag:
+
+`DELETE /api/repos/{idOrFullName}/tags/{tag}`
+
+## AI Ask
+
+`POST /api/ai/ask`
+
+```json
+{ "question": "哪些 starred repos 适合做本地 RAG 原型？" }
+```
+
+Use this endpoint for synthesis, comparison, recommendations, and natural-language questions over the user's starred repositories.
+
+The server chooses the user's default AI Provider first and falls back to the system default AI configuration when no user default is available.

package/src/index.mjs

@@ -715,6 +715,97 @@ function detectProjectRoot() {
   return new URL("../../..", import.meta.url).pathname.replace(/\/$/, "");
 }
 
+// Skill 源目录（npm 包内的 skills/ 目录）
+function getSkillSourceDir() {
+  return new URL("../../skills/starlens", import.meta.url).pathname;
+}
+
+// 各客户端全局 skill 目标路径
+const SKILL_TARGETS = {
+  claude:    { path: join(homedir(), ".claude", "skills", "starlens"),    label: "Claude Code" },
+  opencode:  { path: join(homedir(), ".opencode", "skills", "starlens"),  label: "OpenCode" },
+  codex:     { path: join(homedir(), ".codex", "skills", "starlens"),     label: "Codex CLI" },
+  openclaw:  { path: join(homedir(), ".openclaw", "skills", "starlens"),  label: "OpenClaw" },
+  hermes:    { path: join(homedir(), ".hermes", "skills", "starlens"),    label: "Hermes" },
+};
+
+async function copyDir(src, dest) {
+  const { readdir, copyFile } = await import("node:fs/promises");
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function installSkillFiles(client, projectPath) {
+  const skillSrc = getSkillSourceDir();
+
+  // 检查 skill 源是否存在（全局安装时应该存在）
+  try {
+    await access(skillSrc);
+  } catch {
+    return { ok: false, reason: "skill 文件未找到（可能是旧版本，请更新：npm i -g @starlens-app/cli）" };
+  }
+
+  const results = [];
+
+  // 1. 全局路径（对应当前客户端）
+  const globalTarget = SKILL_TARGETS[client];
+  if (globalTarget) {
+    try {
+      await copyDir(skillSrc, globalTarget.path);
+      results.push({ path: globalTarget.path, ok: true });
+    } catch (e) {
+      results.push({ path: globalTarget.path, ok: false, reason: e.message });
+    }
+  }
+
+  // 2. Cursor 项目级：.cursor/rules/starlens.mdc
+  if (client === "cursor" && projectPath) {
+    const cursorRulesDir = join(projectPath, ".cursor", "rules");
+    const cursorTarget = join(cursorRulesDir, "starlens.mdc");
+    try {
+      await mkdir(cursorRulesDir, { recursive: true });
+      const skillContent = await readFile(join(skillSrc, "SKILL.md"), "utf8");
+      // 转换 SKILL.md → .mdc（保持内容不变，Cursor 兼容 markdown frontmatter）
+      await writeFile(cursorTarget, skillContent);
+      results.push({ path: cursorTarget, ok: true });
+    } catch (e) {
+      results.push({ path: cursorTarget, ok: false, reason: e.message });
+    }
+  }
+
+  // 3. VS Code 项目级：.github/copilot-instructions.md（追加）
+  if (client === "vscode" && projectPath) {
+    const githubDir = join(projectPath, ".github");
+    const vscodeTarget = join(githubDir, "copilot-instructions.md");
+    try {
+      await mkdir(githubDir, { recursive: true });
+      const skillContent = await readFile(join(skillSrc, "SKILL.md"), "utf8");
+      // 去掉 frontmatter，只保留正文
+      const body = skillContent.replace(/^---[\s\S]*?---\n/, "").trim();
+      let existing = "";
+      try { existing = await readFile(vscodeTarget, "utf8"); } catch { /* 不存在则新建 */ }
+      const marker = "<!-- starlens-skill -->";
+      if (!existing.includes(marker)) {
+        await writeFile(vscodeTarget, existing + (existing ? "\n\n" : "") + marker + "\n" + body + "\n" + marker);
+      }
+      results.push({ path: vscodeTarget, ok: true });
+    } catch (e) {
+      results.push({ path: vscodeTarget, ok: false, reason: e.message });
+    }
+  }
+
+  return { ok: results.some(r => r.ok), results };
+}
+
 function createReadlineInterface() {
   return createInterface({ input: process.stdin, output: process.stdout, terminal: false });
 }
@@ -959,8 +1050,8 @@ async function runInstallSkillWizard(args, env) {
 
     // Step 2: select client
     const clientMap = {
-      "1": "claude", "2": "cursor", "3": "codex", "4": "opencode", "5": "other",
-      "claude": "claude", "cursor": "cursor", "codex": "codex", "opencode": "opencode", "other": "other",
+      "1": "claude", "2": "cursor", "3": "vscode", "4": "codex", "5": "opencode", "6": "openclaw", "7": "hermes", "8": "other",
+      "claude": "claude", "cursor": "cursor", "vscode": "vscode", "codex": "codex", "opencode": "opencode", "openclaw": "openclaw", "hermes": "hermes", "other": "other",
     };
 
     let client = clientArg.value?.toLowerCase();
@@ -969,16 +1060,19 @@ async function runInstallSkillWizard(args, env) {
       console.log("请选择你的 AI 客户端：");
       console.log("  1) Claude Code");
       console.log("  2) Cursor");
-      console.log("  3) Codex");
-      console.log("  4) opencode");
-      console.log("  5) 其他（仅输出配置片段）");
+      console.log("  3) VS Code (Copilot)");
+      console.log("  4) Codex CLI");
+      console.log("  5) OpenCode");
+      console.log("  6) OpenClaw");
+      console.log("  7) Hermes");
+      console.log("  8) 其他（仅输出配置片段）");
       const clientChoice = await wizardPrompt(rl, "输入序号或名称", "1");
       client = clientMap[clientChoice.toLowerCase()] ?? "other";
     } else {
       client = clientMap[client];
     }
 
-    const clientLabels = { claude: "Claude Code", cursor: "Cursor", codex: "Codex", opencode: "opencode", other: "其他" };
+    const clientLabels = { claude: "Claude Code", cursor: "Cursor", vscode: "VS Code", codex: "Codex CLI", opencode: "OpenCode", openclaw: "OpenClaw", hermes: "Hermes", other: "其他" };
     console.log(`已选择客户端：${clientLabels[client]}`);
 
     // Step 3: token
@@ -1066,6 +1160,10 @@ async function runInstallSkillWizard(args, env) {
         console.log("将以下内容合并到 ~/.config/opencode/opencode.json：");
         console.log("");
         console.log(renderHostedOpencodeSnippet(apiBaseUrl, token));
+      } else if (client === "vscode" || client === "openclaw" || client === "hermes") {
+        console.log(`${clientLabels[client]} 不支持 HTTP MCP，Skill 文件已自动安装。`);
+        console.log("如需 HTTP API 直连，请参考文档：");
+        console.log(`  ${apiBaseUrl}/docs/integrations`);
       } else {
         console.log("HTTP MCP 端点信息：");
         console.log("");
@@ -1104,14 +1202,33 @@ async function runInstallSkillWizard(args, env) {
         console.log("");
         console.log(renderOpencodeSnippet(projectRoot));
       } else {
-        console.log("通用 Agent Skill 环境变量配置：");
+        console.log("通用 Agent Skill 环境变量配置（vscode/openclaw/hermes 等）：");
         console.log("");
         console.log(`  STARLENS_TOKEN="${token || "stl_xxx"}"`);
         console.log(`  STARLENS_API_BASE_URL="${apiBaseUrl}"`);
+        console.log("");
+        console.log("Skill 文件已自动安装到对应客户端目录，无需额外 MCP 配置。");
+      }
+    }
+
+    // Step 6: install skill files
+    console.log("");
+    console.log("─".repeat(40));
+    console.log("安装 Starlens Agent Skill...");
+    const skillResult = await installSkillFiles(client, projectRoot ?? process.cwd());
+    if (skillResult.results) {
+      for (const r of skillResult.results) {
+        if (r.ok) {
+          console.log(`✓ Skill 已安装：${r.path}`);
+        } else {
+          console.log(`⚠  Skill 安装失败：${r.path}（${r.reason}）`);
+        }
       }
+    } else if (!skillResult.ok) {
+      console.log(`⚠  ${skillResult.reason}`);
     }
 
-    // Step 6: verify token (optional)
+    // Step 7: verify token (optional)
     if (token) {
       console.log("");
       const doVerify = await wizardPrompt(rl, "是否验证 Token 可用性？(y/N)", "N");
@@ -1151,7 +1268,9 @@ async function runInstallSkillWizard(args, env) {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+import { realpathSync } from "node:fs";
+const _realArgv1 = (() => { try { return realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (import.meta.url === `file://${_realArgv1}`) {
   main().catch((error) => {
     console.error(error instanceof CliError ? error.message : error.stack || error.message);
     process.exitCode = error.exitCode ?? 1;