sp-rag 0.6.12 → 0.6.14

package/README.md

@@ -17,7 +17,7 @@ CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 ## Trạng thái package
 
 - package npm public: `sp-rag`
-- version đang publish: `0.6.12`
+- version đang publish: `0.6.14`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -77,8 +77,8 @@ Ghi chú:
 - với `cursor` và `vscode` ở `scope project`, nếu Sếpp đang đứng sẵn trong repo thì có thể bỏ `--cwd`
 - CLI sẽ tự dùng thư mục hiện tại cho cả MCP lẫn skill
 - `update` sẽ tự tính lại target project từ `--cwd` hoặc thư mục hiện tại, không dùng target cũ lệch project nếu user không truyền `--target-dir`
-- rule/agent mới đã được tăng độ ưu tiên MCP-first, giảm khả năng model nhảy thẳng sang grep/read file local
-- skill mới cũng dặn model tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`; không bê nguyên `answer_brief`
+- rule/agent mới route theo intent: feature/domain/docs thì MCP trước, còn edit/debug/current-code thì kiểm tra workspace trước
+- skill mới dùng hướng MCP-grounded + workspace-verified: tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`, không bê nguyên `answer_brief`, và đối chiếu lại `git status --short`/file hiện tại khi cần
 
 Ví dụ:
 

package/dist/cli.js

@@ -426,6 +426,9 @@ async function emitDoctorReport(parsed, defaults, explicitClient, checks) {
 async function runClientSetup(parsed, defaults, client) {
     const nextDefaults = deriveDefaultsForClient(parsed, defaults, client);
     validateStoredToken(nextDefaults);
+    if (!optionFlag(parsed, 'skip-mcp')) {
+        resolveAuthForMcp(parsed, nextDefaults);
+    }
     const configPath = await saveResolvedConfig(nextDefaults);
     process.stdout.write(`Đã lưu config CLI tại ${configPath}\n`);
     if (!optionFlag(parsed, 'skip-mcp')) {

package/dist/lib/config-store.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { parseJsonWithBom, stripUtf8Bom } from './json.js';
 function stripUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }
@@ -22,10 +23,14 @@ export async function loadCliConfig(homeDir) {
         }
         throw error;
     });
-    if (!content) {
+    if (content === null) {
         return null;
     }
-    return JSON.parse(content);
+    const normalized = stripUtf8Bom(content);
+    if (!normalized.trim()) {
+        return null;
+    }
+    return parseJsonWithBom(normalized);
 }
 export async function saveCliConfig(config, homeDir) {
     const filePath = resolveCliConfigPath(homeDir);

package/dist/lib/json.js

@@ -0,0 +1,6 @@
+export function stripUtf8Bom(content) {
+    return content.replace(/^\uFEFF/, '');
+}
+export function parseJsonWithBom(content) {
+    return JSON.parse(stripUtf8Bom(content));
+}

package/dist/lib/mcp-config.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { parseJsonWithBom } from './json.js';
 function escapeRegex(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -8,7 +9,7 @@ function quotedTomlKey(value) {
     return `"${value.replace(/"/g, '\\"')}"`;
 }
 function parseJsonObject(existing) {
-    return existing?.trim() ? JSON.parse(existing) : {};
+    return existing?.trim() ? parseJsonWithBom(existing) : {};
 }
 function withHeaders(target, headers) {
     if (!headers) {

package/dist/lib/skill.js

@@ -72,7 +72,7 @@ export function defaultSkillDir(client = 'codex', cwd, scope) {
 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. You must call SP-RAG MCP tools first before answering from memory or reading local files.
+description: Use SP-RAG for seo-booster codebase, feature, domain, rendered-docs, import-inventory, or codegraph freshness work that needs grounded evidence.
 ---
 
 # SP-RAG
@@ -84,29 +84,43 @@ Docs URL: \`${context.docsUrl}\`
 
 ## When To Use This Skill
 
-- Use this skill whenever the request is about the internal codebase, business workflows, rendered docs, import inventory, or sync state.
-- Use this skill when grounded evidence matters more than memory or intuition.
-- Use this skill when the answer should come from MCP tools or rendered docs before freeform reasoning.
+- Use SP-RAG whenever the request is about seo-booster codebase, features, business workflows, rendered docs, import inventory, or sync state.
+- Use this skill for seo-booster codebase, feature, business workflow, rendered docs, import inventory, and sync-state questions.
+- The operating model is MCP-grounded, workspace-verified.
+- Do not treat MCP as the only source. MCP gives context; current workspace files and git state verify the final answer.
 
-## Recommended Workflow
+## Intent Routing
+
+- For feature, domain, architecture, workflow, docs, or "what does this do" questions: call \`${context.serverAlias}\` MCP first, usually \`query_context\`, then verify with workspace files when implementation details matter.
+- For current-code, edit, bug, failing-test, local-error, or "why is this broken right now" work: inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads, then use MCP to widen context if needed.
+- For mixed questions: get MCP context, inspect current files, compare both, then answer.
+- For docs questions, use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
+- For sync freshness and operations, use \`get_sync_status\`, \`get_sync_runs\`, and \`get_sync_metrics\`. Only use \`trigger_code_graph_sync\` when the user explicitly asks or stale evidence is the confirmed blocker.
+
+## Workspace Verification
+
+1. Run or mentally account for \`git status --short\` before relying on MCP for current behavior.
+2. If MCP cites files, inspect the current workspace version of those files when the answer depends on exact code.
+3. If changed files are related to the question, current workspace files override MCP evidence.
+4. If MCP and workspace disagree, say the graph may be stale and explain which source you are trusting.
+
+## Expand Evidence
 
-1. Call \`healthz\` if the MCP server might be unavailable or the connection is brand new.
-2. Use \`query_context\` for architecture, domain, entities, relations, and business flow questions.
-3. Use \`get_rendered_docs\` for public, function, or dev docs that were already rendered from the latest graph.
-4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` when you need to verify commit freshness, investigate failures, or inspect operational history.
-5. Only call \`trigger_code_graph_sync\` when the user explicitly asks to refresh the graph or when a stale graph is the confirmed blocker.
-6. After \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`. Treat \`answer_brief\` as a hint only.
+- After \`query_context\`, synthesize from \`matched_passages\`, \`top_entities\`, \`top_relations\`, \`citations\`, and \`feature_memory\` diagnostics when present.
+- Treat \`answer_brief\` as a hint only.
+- Do not stop at the first one or two MCP citations for broad feature questions.
+- Expand through related symbols, callers, services, controllers, jobs, routes, models, components, and tests using workspace search when needed.
+- Prefer rendered docs when they answer business behavior, but verify current code before making implementation claims.
 
 ## Guardrails
 
 ${seoBoosterProjectGuard}
-- You must call SP-RAG MCP tools first for codebase or domain questions before using local workspace search, grep, or file reads.
-- Prefer MCP-grounded answers before relying on memory.
-- Treat \`answer_brief\` as a hint only. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
-- If the evidence may be stale, say so clearly and mention that the graph or docs may need a refresh.
+- Find root cause before fixing bugs.
+- Use evidence before conclusions; do not claim completion without verification.
+- For behavior changes, write or update tests before implementation when feasible.
+- If evidence may be stale, say so clearly and mention that the graph or docs may need a refresh.
 - Do not trigger sync or import actions unless the user asked for it or the workflow truly requires it.
-- When rendered docs already answer the question, cite or summarize those docs instead of rewriting everything from scratch.
-- Only fall back to local workspace search or file reads after MCP is unavailable or clearly lacks the needed evidence, and say that you are falling back.
+- When rendered docs already answer the question, cite or summarize those docs, then check current code if the answer depends on implementation details.
 `;
 }
 function renderCursorRule(context) {
@@ -119,14 +133,16 @@ alwaysApply: true
 # SP-RAG
 
 ${seoBoosterProjectGuard}
-- You must call the \`${context.serverAlias}\` MCP server first before using local workspace search, grep, or file reads for codebase and domain questions.
+- Route by intent before choosing tools.
+- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
+- Use workspace search first for current-code, edit, bug, and test-failure work.
+- Verify MCP evidence against \`git status --short\` and current workspace files before making implementation claims.
 - 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.
 - Treat \`answer_brief\` only as a hint. Build the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
+- Do not stop at the first one or two MCP citations for broad feature questions. Expand through related files, symbols, services, controllers, jobs, components, and tests.
 - 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.
-- Only fall back to local workspace search after MCP is unavailable or clearly lacks the needed evidence, and say that you are falling back.
 `;
 }
 function renderVsCodeAgent(context) {
@@ -140,41 +156,44 @@ 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.
 
-You must call an SP-RAG MCP tool before using local workspace search, grep, or file reads for codebase and domain questions.
+Route by intent before choosing tools. MCP gives the semantic map; the current workspace verifies exact code.
 
 ## Recommended Workflow
 
-1. Start with \`healthz\` if connectivity or freshness is uncertain.
-2. Use \`query_context\` for architecture, domain, entities, relations, and workflow questions.
+1. For feature, domain, architecture, workflow, docs, and "what does this do" questions, use \`query_context\` first.
+2. For current-code, edit, debug, failing-test, and local-error work, inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads.
 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.
-6. After \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`. Treat \`answer_brief\` as a hint.
+5. After MCP returns, verify important citations against current workspace files if the answer depends on exact implementation.
+6. Expand beyond the first one or two MCP citations for broad feature questions. Search related symbols, callers, services, controllers, jobs, routes, models, components, and tests.
+7. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
 
 ## Guardrails
 
 ${seoBoosterProjectGuard}
-- Prefer MCP-grounded evidence before answering from memory.
+- Prefer MCP-grounded evidence before answering from memory, but current workspace files override MCP evidence when they differ.
 - Treat \`answer_brief\` as a hint. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
-- Do not use local workspace search, grep, or file reads until SP-RAG MCP has been tried first for the current question.
 - 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.
-- Only fall back to local workspace search or file reads after MCP is unavailable or clearly lacks the needed evidence, and say that you are falling back.
+- Find root cause before fixes, write or update tests for behavior changes when feasible, and verify before claiming completion.
 `;
 }
 function renderVsCodeAlwaysOnInstructions(context) {
     return `# SP-RAG workspace instructions
 
 ${seoBoosterProjectGuard}
-- Always use the \`${context.serverAlias}\` MCP server first for codebase, domain, architecture, workflow, and operational questions before local workspace search, grep, or file reads.
+- Route by intent before choosing tools.
+- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
+- Use workspace inspection first for current-code, edit, debug, failing-test, and local-error work.
+- Verify MCP evidence against current workspace state, including \`git status --short\` and current file contents when implementation details matter.
 - Start with \`healthz\` only when connectivity is uncertain or the session is new.
-- Use \`query_context\` first for feature, entity, relation, and business-flow questions.
 - When \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
 - Treat \`answer_brief\` as a hint only, not the final answer.
+- Expand beyond the first one or two MCP citations for broad feature questions.
 - Use \`get_rendered_docs\` when rendered docs can answer the question faster than raw code inspection.
 - Only trigger codegraph sync when the user explicitly asks for it or stale graph evidence is the confirmed blocker.
-- If MCP is unavailable or clearly lacks evidence, say so explicitly before falling back to local workspace search or file reads.
+- If MCP and current workspace files disagree, say MCP may be stale and trust the current workspace for implementation details.
 `;
 }
 function renderSkillArtifact(context) {

package/package.json

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