sp-rag 0.4.0 → 0.5.0

package/README.md

@@ -1,10 +1,10 @@
 # `sp-rag`
 
-CLI cho setup nhanh SP-RAG theo hướng dev-friendly:
+CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 
 - lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias
 - cài MCP config đúng format cho từng client
-- cài skill cho các IDE/agent có thư mục skill riêng ổn định
+- cài native skill / rule / custom agent cho từng IDE khi có convention ổn định
 - kiểm tra nhanh health và observability của stack
 - gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
 - đọc docs đã render
@@ -17,7 +17,7 @@ CLI cho setup nhanh SP-RAG theo hướng dev-friendly:
 ## Trạng thái package
 
 - package npm public: `sp-rag`
-- version đang publish: `0.4.0`
+- version đang publish: `0.5.0`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -34,11 +34,13 @@ node dist/index.js doctor
 
 ```bash
 npx sp-rag@latest install --client codex --mcp-token <token truy cập MCP> --doctor
+npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 npx sp-rag@latest token add --token <token truy cập MCP> --client codex
-npx sp-rag@latest mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+npx sp-rag@latest mcp add antigravity --mcp-token <token truy cập MCP>
 npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
-npx sp-rag@latest skill install --skill-client antigravity
-npx sp-rag@latest skill install --skill-client opencode
+npx sp-rag@latest skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 ```
 
 Tương đương bằng `npm`:
@@ -59,15 +61,18 @@ npm exec --yes sp-rag@latest token add -- --token <token truy cập MCP> --clien
 
 ## Skill client được hỗ trợ
 
-- `codex`
-- `claude-code`
-- `antigravity`
-- `opencode`
+- `codex` -> `SKILL.md`
+- `claude-code` -> `SKILL.md`
+- `antigravity` -> `SKILL.md`
+- `opencode` -> `SKILL.md`
+- `cursor` -> `.cursor/rules/sp-rag.mdc`
+- `vscode` -> `.github/agents/sp-rag.agent.md` hoặc `~/.copilot/agents/sp-rag.agent.md`
 
 Ghi chú:
 
-- `cursor` và `vscode` chỉ cài MCP config, không auto-cài skill mặc định
 - generated skill luôn được render bằng tiếng Anh
+- `cursor` hiện nên dùng `scope project` cho rule `.mdc`
+- `vscode` hỗ trợ cả `scope project` lẫn `scope global`
 - nếu không muốn lưu token literal vào file config client, dùng `sp-rag mcp add --auth-env-var SP_RAG_MCP_TOKEN`
 
 ## Path mặc định quan trọng
@@ -84,14 +89,17 @@ Ghi chú:
 - `opencode` project: `opencode.json`
 - `opencode` global: `~/.config/opencode/opencode.json`
 
-### Skill
+### Skill / rule / custom agent
 
 - `codex`: `~/.codex/skills/sp-rag/SKILL.md`
 - `claude-code`: `~/.claude/skills/sp-rag/SKILL.md`
 - `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md`
 - `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md`
+- `cursor` project: `.cursor/rules/sp-rag.mdc`
+- `vscode` project: `.github/agents/sp-rag.agent.md`
+- `vscode` global: `~/.copilot/agents/sp-rag.agent.md`
 
-## Luồng khuyến dùng cho dev mới
+## Luồng khuyên dùng cho dev mới
 
 ```bash
 sp-rag install --client codex --mcp-token <token truy cập MCP> --doctor
@@ -106,9 +114,8 @@ sp-rag mcp add antigravity --mcp-token <token truy cập MCP>
 sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag skill install
-sp-rag skill install --skill-client claude-code
-sp-rag skill install --skill-client antigravity
-sp-rag skill install --skill-client opencode
+sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
 ```
 
@@ -131,9 +138,8 @@ sp-rag mcp add antigravity --mcp-token <token truy cập MCP>
 sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag skill install
-sp-rag skill install --skill-client claude-code
-sp-rag skill install --skill-client antigravity
-sp-rag skill install --skill-client opencode
+sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
 sp-rag update setup --client codex
 ```

package/dist/cli.js

@@ -56,19 +56,28 @@ function supportedSkillClient(value) {
     if (!value) {
         return undefined;
     }
-    if (value === 'codex' || value === 'claude-code' || value === 'antigravity' || value === 'opencode') {
+    if (value === 'codex' ||
+        value === 'cursor' ||
+        value === 'claude-code' ||
+        value === 'antigravity' ||
+        value === 'vscode' ||
+        value === 'opencode') {
         return value;
     }
-    throw new Error('Skill client phải là codex, claude-code, antigravity hoặc opencode.');
+    throw new Error('Skill client phải là codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
 }
 function defaultSkillClientForMcpClient(client) {
     switch (client) {
         case 'codex':
             return 'codex';
+        case 'cursor':
+            return 'cursor';
         case 'claude-code':
             return 'claude-code';
         case 'antigravity':
             return 'antigravity';
+        case 'vscode':
+            return 'vscode';
         case 'opencode':
             return 'opencode';
         default:
@@ -128,8 +137,8 @@ function helpText() {
     return `sp-rag - CLI cho setup, MCP, codegraph, eval và skill của SP-RAG
 
 Lệnh chính:
-  sp-rag install [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|claude-code|antigravity|opencode] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH]
-  sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|claude-code|antigravity|opencode] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag install [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
   sp-rag token add --token TOKEN [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
   sp-rag config show
   sp-rag doctor [--base-url URL]
@@ -141,9 +150,9 @@ Lệnh chính:
   sp-rag codegraph sync [--base-url URL] [--branch BRANCH] [--commit-sha SHA] [--force] [--webhook-token TOKEN] [--gitlab-job-token TOKEN]
   sp-rag docs get <public|function|dev> [--base-url URL] [--format md|json|html]
   sp-rag mcp add <codex|cursor|claude-code|antigravity|vscode|opencode> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
-  sp-rag skill install [--skill-client codex|claude-code|antigravity|opencode] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
+  sp-rag skill install [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
   sp-rag eval run --file eval-suite.json [--base-url URL]
-  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|claude-code|antigravity|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
 `;
 }
 function buildCliConfig(defaults) {
@@ -308,6 +317,7 @@ async function runSkillInstall(parsed, defaults) {
     const result = await installSkill({
         client,
         cwd: optionString(parsed, 'cwd'),
+        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
         targetDir: optionString(parsed, 'target-dir') ?? defaults.skillTargetDir,
         serverAlias: optionString(parsed, 'server-alias') ?? defaults.serverAlias,
         mcpUrl: optionString(parsed, 'mcp-url') ?? defaults.mcpUrl,
@@ -481,7 +491,7 @@ export async function runCli(argv) {
             return 0;
         }
         if (group === 'version') {
-            process.stdout.write('sp-rag 0.4.0\n');
+            process.stdout.write('sp-rag 0.5.0\n');
             return 0;
         }
         process.stdout.write(helpText());

package/dist/lib/skill.js

@@ -1,31 +1,64 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
-export function defaultSkillDir(client = 'codex', _cwd) {
+function clientLabel(client) {
     switch (client) {
         case 'codex':
-            return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
+            return 'Codex';
         case 'claude-code':
-            return path.join(os.homedir(), '.claude', 'skills', 'sp-rag');
+            return 'Claude Code';
         case 'antigravity':
-            return path.join(os.homedir(), '.gemini', 'antigravity', 'skills', 'sp-rag');
+            return 'Antigravity';
         case 'opencode':
-            return path.join(os.homedir(), '.config', 'opencode', 'skills', 'sp-rag');
+            return 'OpenCode';
+        case 'cursor':
+            return 'Cursor';
+        case 'vscode':
+            return 'VS Code';
     }
 }
-function clientLabel(client) {
+function normalizeScope(client, scope) {
+    if (scope) {
+        return scope;
+    }
+    switch (client) {
+        case 'cursor':
+            return 'project';
+        case 'vscode':
+            return 'project';
+        default:
+            return 'global';
+    }
+}
+function requireProjectCwd(client, cwd) {
+    if (!cwd?.trim()) {
+        throw new Error(`${client} cần --cwd hoặc --target-dir để cài skill theo project.`);
+    }
+    return path.resolve(cwd);
+}
+export function defaultSkillDir(client = 'codex', cwd, scope) {
+    const normalizedScope = normalizeScope(client, scope);
     switch (client) {
         case 'codex':
-            return 'Codex';
+            return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
         case 'claude-code':
-            return 'Claude Code';
+            return path.join(os.homedir(), '.claude', 'skills', 'sp-rag');
         case 'antigravity':
-            return 'Antigravity';
+            return path.join(os.homedir(), '.gemini', 'antigravity', 'skills', 'sp-rag');
         case 'opencode':
-            return 'OpenCode';
+            return path.join(os.homedir(), '.config', 'opencode', 'skills', 'sp-rag');
+        case 'cursor':
+            if (normalizedScope !== 'project') {
+                throw new Error('Cursor rule hiện chỉ nên cài ở scope project qua .cursor/rules.');
+            }
+            return path.join(requireProjectCwd(client, cwd), '.cursor', 'rules');
+        case 'vscode':
+            return normalizedScope === 'project'
+                ? path.join(requireProjectCwd(client, cwd), '.github', 'agents')
+                : path.join(os.homedir(), '.copilot', 'agents');
     }
 }
-export function renderSkill(options) {
+function renderSkillMarkdown(context) {
     return `---
 name: sp-rag
 description: Use SP-RAG whenever the user asks about this codebase, internal business domain, rendered docs, import inventory, or codegraph sync status. Prefer MCP-backed evidence before answering from memory.
@@ -33,10 +66,10 @@ description: Use SP-RAG whenever the user asks about this codebase, internal bus
 
 # SP-RAG
 
-Target client: ${clientLabel(options.client)}
-Default MCP server alias: \`${options.serverAlias}\`
-MCP URL: \`${options.mcpUrl}\`
-Docs URL: \`${options.docsUrl}\`
+Target client: ${clientLabel(context.client)}
+Default MCP server alias: \`${context.serverAlias}\`
+MCP URL: \`${context.mcpUrl}\`
+Docs URL: \`${context.docsUrl}\`
 
 ## When To Use This Skill
 
@@ -60,6 +93,72 @@ Docs URL: \`${options.docsUrl}\`
 - When rendered docs already answer the question, cite or summarize those docs instead of rewriting everything from scratch.
 `;
 }
+function renderCursorRule(context) {
+    return `---
+description: Use SP-RAG when the request is about this codebase, internal business workflows, rendered docs, import inventory, or codegraph sync status.
+globs:
+alwaysApply: false
+---
+
+# SP-RAG
+
+- Prefer the \`${context.serverAlias}\` MCP server at \`${context.mcpUrl}\` before answering from memory.
+- Use rendered docs from \`${context.docsUrl}\` when documentation already answers the question.
+- For architecture, domain, entities, relations, and business workflow questions, query MCP first and only then synthesize the answer.
+- For freshness or operational questions, check sync status, recent runs, and metrics before assuming the graph is current.
+- Only trigger codegraph sync when the user explicitly asks for it or stale evidence is the confirmed blocker.
+- If the evidence may be stale, say so clearly.
+`;
+}
+function renderVsCodeAgent(context) {
+    return `---
+name: SP-RAG
+description: Use this custom agent whenever the request is about this codebase, internal business workflows, rendered docs, import inventory, or codegraph sync status.
+tools: ['${context.serverAlias}/*']
+---
+
+You are the SP-RAG custom agent for this workspace.
+
+Use the \`${context.serverAlias}\` MCP server at \`${context.mcpUrl}\` and the rendered docs URL \`${context.docsUrl}\` as your grounded source of truth.
+
+## Recommended Workflow
+
+1. Start with \`healthz\` if connectivity or freshness is uncertain.
+2. Use \`query_context\` for architecture, domain, entities, relations, and workflow questions.
+3. Use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
+4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` for freshness, incident review, or operational debugging.
+5. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
+
+## Guardrails
+
+- Prefer MCP-grounded evidence before answering from memory.
+- When evidence may be stale, say so clearly and mention that a refresh might be needed.
+- Do not trigger sync or import actions unless the workflow truly requires it.
+- When rendered docs already answer the question, summarize those docs instead of rewriting everything from scratch.
+`;
+}
+function renderSkillArtifact(context) {
+    switch (context.client) {
+        case 'cursor':
+            return {
+                fileName: 'sp-rag.mdc',
+                content: renderCursorRule(context),
+            };
+        case 'vscode':
+            return {
+                fileName: 'sp-rag.agent.md',
+                content: renderVsCodeAgent(context),
+            };
+        default:
+            return {
+                fileName: 'SKILL.md',
+                content: renderSkillMarkdown(context),
+            };
+    }
+}
+export function renderSkill(options) {
+    return renderSkillArtifact(options).content;
+}
 export function renderCodexSkill(options) {
     return renderSkill({
         client: 'codex',
@@ -68,16 +167,17 @@ export function renderCodexSkill(options) {
 }
 export async function installSkill(options = {}) {
     const client = options.client ?? 'codex';
-    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd));
-    const filePath = path.join(targetDir, 'SKILL.md');
-    const content = renderSkill({
+    const scope = normalizeScope(client, options.scope);
+    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
+    const artifact = renderSkillArtifact({
         client,
         serverAlias: options.serverAlias?.trim() || 'sp-rag',
         mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
         docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
     });
+    const filePath = path.join(targetDir, artifact.fileName);
     await mkdir(targetDir, { recursive: true });
-    await writeFile(filePath, content, 'utf8');
+    await writeFile(filePath, artifact.content, 'utf8');
     return {
         client,
         path: filePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sp-rag",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG",
   "type": "module",
   "files": [