sp-rag 0.3.0

package/README.md

@@ -0,0 +1,138 @@
+# `sp-rag`
+
+CLI cho 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
+- kiểm tra nhanh health và observability của stack
+- gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
+- đọc docs đã render
+- cài MCP config cho client
+- cài skill để agent ưu tiên dùng RAG nội bộ
+- chạy evaluation/regression suite từ file JSON
+
+## Yêu cầu
+
+- Node.js `>= 20`
+
+## Cài từ source trong monorepo
+
+```bash
+cd apps/sp-rag-cli
+npm install
+npm run build
+node dist/index.js doctor
+```
+
+## Cài nhanh qua `npx`
+
+Nếu package đã được publish, luồng ngắn nhất là:
+
+```bash
+npx sp-rag@latest install --client codex --mcp-token <token>
+npx sp-rag@latest token add --token <token> --client codex
+```
+
+Tương đương bằng `npm`:
+
+```bash
+npm exec --yes sp-rag@latest install -- --client codex --mcp-token <token>
+npm exec --yes sp-rag@latest token add -- --token <token> --client codex
+```
+
+Ghi chú:
+
+- `install` là lệnh onboarding một bước: lưu config, cài MCP config, cài skill, và có thể chạy `doctor`
+- `token add` dùng khi dev đã cài xong nhưng chưa gắn bearer token vào MCP client
+- 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`
+
+## Luồng khuyên dùng cho dev mới
+
+```bash
+sp-rag install --client codex --mcp-token <token> --doctor
+sp-rag token add --token <token> --client codex
+sp-rag config show
+sp-rag codegraph status
+sp-rag codegraph watch --interval-ms 2000
+sp-rag codegraph runs --limit 5
+sp-rag codegraph metrics
+sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
+sp-rag mcp add codex --mcp-token <token>
+sp-rag skill install
+sp-rag eval run --file ./examples/eval-suite.sample.json
+```
+
+## Lệnh chính
+
+```bash
+sp-rag install --client codex --mcp-token <token> --doctor
+sp-rag token add --token <token> --client codex
+sp-rag config show
+sp-rag doctor
+sp-rag codegraph status
+sp-rag codegraph watch --interval-ms 2000
+sp-rag codegraph runs --limit 10
+sp-rag codegraph metrics
+sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
+sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token> --gitlab-job-token <ci-job-token>
+sp-rag docs get public --format md
+sp-rag mcp add codex --mcp-token <token>
+sp-rag skill install
+sp-rag eval run --file ./examples/eval-suite.sample.json
+sp-rag update setup --client codex
+```
+
+## Cấu hình mặc định
+
+CLI lưu cấu hình tại:
+
+- `~/.sp-rag/config.json`
+- có thể override home dir bằng `SP_RAG_HOME_DIR`
+
+CLI có thể lưu thêm:
+
+- `mcpToken` cho flow cài nhanh
+- hoặc `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal
+
+Giá trị mặc định:
+
+- base URL: `https://sp-rag.secomapp.com`
+- MCP URL: `https://sp-rag.secomapp.com/mcp`
+- alias MCP: `sp-rag`
+
+Override nhanh bằng env:
+
+```bash
+SP_RAG_BASE_URL=https://sp-rag.secomapp.com
+SP_RAG_MCP_URL=https://sp-rag.secomapp.com/mcp
+SP_RAG_HOME_DIR=D:/Temp/sp-rag-home
+```
+
+## Evaluation mẫu
+
+- file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json)
+
+## Recovery khi sync bị treo
+
+Nếu worker crash giữa chừng, `codegraph-ts` sẽ tự đổi run `running` cũ sang `failed` ở lần truy cập đầu tiên sau khi service lên lại. Khi ops muốn dọn tay hoặc gắn lý do vận hành rõ ràng hơn, dùng:
+
+```bash
+sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
+```
+
+CLI này gọi `POST /codegraph/sync-recover-stale` và trả lại danh sách run vừa được chuyển sang `failed`.
+
+## Theo dõi active
+
+Khi một sync đang chạy và ops muốn biết phase hiện tại theo thời gian thực, dùng:
+
+```bash
+sp-rag codegraph watch --interval-ms 2000
+```
+
+CLI sẽ in liên tục `lastStatus`, `activity.currentPhase`, `progressPercentHint`, `elapsed` và `message`.
+
+## Tài liệu thêm
+
+- [Hướng dẫn dev sử dụng SP-RAG](../../docs/runbooks/dev-usage-guide.md)
+- [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md)
+- [Runbook MCP Public](../../docs/runbooks/mcp-public-clients.md)

package/dist/cli.js

@@ -0,0 +1,457 @@
+import { readFile } from 'node:fs/promises';
+import { loadCliConfig, saveCliConfig, } from './lib/config-store.js';
+import { runEvaluationSuite } from './lib/eval.js';
+import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, } from './lib/mcp-config.js';
+import { fetchJson, fetchText, runDoctor } from './lib/http.js';
+import { installCodexSkill } from './lib/skill.js';
+function parseArgv(argv) {
+    const positionals = [];
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        if (!current.startsWith('--')) {
+            positionals.push(current);
+            continue;
+        }
+        const eqIndex = current.indexOf('=');
+        if (eqIndex >= 0) {
+            options[current.slice(2, eqIndex)] = current.slice(eqIndex + 1);
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next || next.startsWith('--')) {
+            options[current.slice(2)] = true;
+            continue;
+        }
+        options[current.slice(2)] = next;
+        index += 1;
+    }
+    return { positionals, options };
+}
+function optionString(parsed, key, fallback) {
+    const value = parsed.options[key];
+    if (typeof value === 'string') {
+        return value;
+    }
+    return fallback;
+}
+function optionFlag(parsed, key) {
+    return parsed.options[key] === true;
+}
+function supportedClient(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === 'codex' || value === 'cursor' || value === 'claude-code') {
+        return value;
+    }
+    throw new Error('Client phải là codex, cursor hoặc claude-code.');
+}
+function supportedScope(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === 'global' || value === 'project') {
+        return value;
+    }
+    throw new Error('Scope phải là global hoặc project.');
+}
+async function loadRuntimeDefaults(parsed) {
+    const homeDir = optionString(parsed, 'home-dir');
+    const config = await loadCliConfig(homeDir);
+    const baseUrl = optionString(parsed, 'base-url') ??
+        process.env['SP_RAG_BASE_URL']?.trim() ??
+        config?.baseUrl ??
+        defaultBaseUrl();
+    const mcpUrl = optionString(parsed, 'mcp-url') ??
+        optionString(parsed, 'url') ??
+        process.env['SP_RAG_MCP_URL']?.trim() ??
+        config?.mcpUrl ??
+        defaultMcpUrl();
+    const serverAlias = optionString(parsed, 'server-alias') ??
+        config?.serverAlias ??
+        defaultMcpServerAlias();
+    const docsUrl = optionString(parsed, 'docs-url') ??
+        config?.docsUrl ??
+        `${baseUrl.replace(/\/+$/, '')}/codegraph/docs/public?format=md`;
+    const defaultClient = supportedClient(optionString(parsed, 'client') ?? config?.defaultClient);
+    const defaultScope = supportedScope(optionString(parsed, 'scope') ?? config?.defaultScope);
+    return {
+        config,
+        homeDir,
+        baseUrl,
+        mcpUrl,
+        serverAlias,
+        docsUrl,
+        defaultClient,
+        defaultScope,
+        authEnvVar: optionString(parsed, 'auth-env-var') ?? config?.authEnvVar,
+        mcpToken: optionString(parsed, 'mcp-token') ??
+            optionString(parsed, 'token') ??
+            process.env['SP_RAG_MCP_TOKEN']?.trim() ??
+            config?.mcpToken,
+        skillTargetDir: optionString(parsed, 'target-dir') ?? config?.skillTargetDir,
+    };
+}
+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] [--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] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag token add --token TOKEN [--client codex|cursor|claude-code] [--scope global|project] [--cwd PATH]
+  sp-rag config show
+  sp-rag doctor [--base-url URL]
+  sp-rag codegraph status [--base-url URL]
+  sp-rag codegraph watch [--base-url URL] [--interval-ms N] [--max-polls N]
+  sp-rag codegraph runs [--base-url URL] [--limit N]
+  sp-rag codegraph metrics [--base-url URL]
+  sp-rag codegraph recover [--base-url URL] [--reason TEXT]
+  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> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
+  sp-rag skill install [--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] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
+`;
+}
+function buildCliConfig(defaults) {
+    return {
+        baseUrl: defaults.baseUrl,
+        mcpUrl: defaults.mcpUrl,
+        serverAlias: defaults.serverAlias,
+        defaultClient: defaults.defaultClient,
+        defaultScope: defaults.defaultScope,
+        authEnvVar: defaults.authEnvVar,
+        mcpToken: defaults.mcpToken,
+        skillTargetDir: defaults.skillTargetDir,
+        docsUrl: defaults.docsUrl,
+    };
+}
+async function runCodegraphStatus(baseUrl) {
+    const result = await fetchJson(`${baseUrl.replace(/\/+$/, '')}/codegraph/sync-status`);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+async function runCodegraphRuns(baseUrl, limit) {
+    const result = await fetchJson(`${baseUrl.replace(/\/+$/, '')}/codegraph/sync-runs?limit=${limit}`);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+async function runCodegraphMetrics(baseUrl) {
+    const result = await fetchJson(`${baseUrl.replace(/\/+$/, '')}/codegraph/sync-metrics`);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function formatDurationMs(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return '-';
+    }
+    if (value < 1000) {
+        return `${value}ms`;
+    }
+    return `${(value / 1000).toFixed(1)}s`;
+}
+function formatWatchLine(payload) {
+    const activity = asObject(payload.activity);
+    const status = typeof payload.lastStatus === 'string' ? payload.lastStatus : 'unknown';
+    const phase = typeof activity?.currentPhase === 'string' ? activity.currentPhase : '-';
+    const progress = typeof activity?.progressPercentHint === 'number'
+        ? Math.round(activity.progressPercentHint)
+        : 0;
+    const elapsed = formatDurationMs(activity?.currentPhaseElapsedMs);
+    const message = typeof activity?.message === 'string' ? activity.message : '';
+    const syncId = typeof payload.lastSyncId === 'string' ? payload.lastSyncId : '-';
+    return `[${status}] phase=${phase} progress~${progress}% elapsed=${elapsed} sync=${syncId} ${message}`.trim();
+}
+async function runCodegraphWatch(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const baseUrl = defaults.baseUrl.replace(/\/+$/, '');
+    const intervalMsRaw = Number.parseInt(optionString(parsed, 'interval-ms', '5000') ?? '5000', 10);
+    const maxPollsRaw = Number.parseInt(optionString(parsed, 'max-polls', '0') ?? '0', 10);
+    const intervalMs = Number.isFinite(intervalMsRaw) && intervalMsRaw > 0 ? intervalMsRaw : 5000;
+    const maxPolls = Number.isFinite(maxPollsRaw) && maxPollsRaw > 0 ? maxPollsRaw : 0;
+    let pollCount = 0;
+    while (true) {
+        pollCount += 1;
+        const result = await fetchJson(`${baseUrl}/codegraph/sync-status`);
+        process.stdout.write(`${formatWatchLine(result)}\n`);
+        if (result.lastStatus !== 'running') {
+            return;
+        }
+        if (maxPolls > 0 && pollCount >= maxPolls) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+async function runCodegraphRecover(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const baseUrl = defaults.baseUrl.replace(/\/+$/, '');
+    const reason = optionString(parsed, 'reason');
+    const result = await fetchJson(`${baseUrl}/codegraph/sync-recover-stale`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            ...(reason ? { reason } : {}),
+        }),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+async function runCodegraphSync(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const baseUrl = defaults.baseUrl.replace(/\/+$/, '');
+    const branch = optionString(parsed, 'branch');
+    const commitSha = optionString(parsed, 'commit-sha');
+    const force = optionFlag(parsed, 'force');
+    const webhookToken = optionString(parsed, 'webhook-token');
+    const gitlabJobToken = optionString(parsed, 'gitlab-job-token');
+    const body = JSON.stringify({
+        ...(branch ? { branch } : {}),
+        ...(commitSha ? { commit_sha: commitSha } : {}),
+        ...(gitlabJobToken ? { gitlab_job_token: gitlabJobToken } : {}),
+        force,
+    });
+    const url = webhookToken
+        ? `${baseUrl}/codegraph/webhook/code-change`
+        : `${baseUrl}/codegraph/trigger-sync`;
+    const headers = {
+        'content-type': 'application/json',
+    };
+    if (webhookToken) {
+        headers['x-codegraph-webhook-token'] = webhookToken;
+    }
+    if (gitlabJobToken) {
+        headers['x-gitlab-job-token'] = gitlabJobToken;
+    }
+    const result = await fetchJson(url, {
+        method: 'POST',
+        headers,
+        body,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+async function runDocsGet(parsed) {
+    const docType = parsed.positionals[2];
+    if (!docType) {
+        throw new Error('Thiếu doc type. Dùng public, function hoặc dev.');
+    }
+    const defaults = await loadRuntimeDefaults(parsed);
+    const format = optionString(parsed, 'format', 'md') ?? 'md';
+    const baseUrl = defaults.baseUrl.replace(/\/+$/, '');
+    const query = new URLSearchParams({ format });
+    const url = `${baseUrl}/codegraph/docs/${encodeURIComponent(docType)}?${query.toString()}`;
+    if (format === 'json') {
+        const result = await fetchJson(url);
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    const result = await fetchText(url);
+    process.stdout.write(`${result}${result.endsWith('\n') ? '' : '\n'}`);
+}
+async function runMcpAdd(parsed, defaults, explicitClient) {
+    const client = supportedClient(explicitClient ?? parsed.positionals[2] ?? defaults.defaultClient);
+    if (!client) {
+        throw new Error('Thiếu client. Dùng codex, cursor hoặc claude-code.');
+    }
+    const result = await installMcpConfig({
+        client,
+        url: optionString(parsed, 'url') ?? defaults.mcpUrl,
+        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
+        authEnvVar: optionString(parsed, 'auth-env-var') ?? defaults.authEnvVar,
+        authToken: optionString(parsed, 'mcp-token') ?? defaults.mcpToken,
+        cwd: optionString(parsed, 'cwd'),
+        serverAlias: optionString(parsed, 'server-alias') ?? defaults.serverAlias,
+    });
+    process.stdout.write(`Đã cập nhật cấu hình MCP cho ${result.client} tại ${result.path} (${result.scope}).\n`);
+}
+async function runSkillInstall(parsed, defaults) {
+    const result = await installCodexSkill({
+        targetDir: optionString(parsed, 'target-dir') ?? defaults.skillTargetDir,
+        serverAlias: optionString(parsed, 'server-alias') ?? defaults.serverAlias,
+        mcpUrl: optionString(parsed, 'mcp-url') ?? defaults.mcpUrl,
+        docsUrl: optionString(parsed, 'docs-url') ?? defaults.docsUrl,
+    });
+    process.stdout.write(`Đã cài Codex skill tại ${result.path}\n`);
+}
+async function runInit(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const config = buildCliConfig(defaults);
+    const configPath = await saveCliConfig(config, defaults.homeDir);
+    process.stdout.write(`Đã lưu config CLI tại ${configPath}\n`);
+    if (!optionFlag(parsed, 'skip-mcp') && defaults.defaultClient) {
+        await runMcpAdd(parsed, defaults, defaults.defaultClient);
+    }
+    if (!optionFlag(parsed, 'skip-skill')) {
+        await runSkillInstall(parsed, defaults);
+    }
+    if (optionFlag(parsed, 'doctor')) {
+        const results = await runDoctor({ baseUrl: defaults.baseUrl });
+        for (const result of results) {
+            process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
+        }
+    }
+}
+async function runInstall(parsed) {
+    await runInit(parsed);
+}
+async function runTokenAdd(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const token = optionString(parsed, 'token') ?? optionString(parsed, 'mcp-token') ?? defaults.mcpToken;
+    if (!token?.trim()) {
+        throw new Error('Thiếu token. Dùng --token <token>.');
+    }
+    const nextDefaults = {
+        ...defaults,
+        mcpToken: token.trim(),
+    };
+    const configPath = await saveCliConfig(buildCliConfig(nextDefaults), defaults.homeDir);
+    process.stdout.write(`Đã lưu token MCP tại ${configPath}\n`);
+    if (optionFlag(parsed, 'skip-mcp-update')) {
+        return;
+    }
+    const client = supportedClient(optionString(parsed, 'client') ?? defaults.defaultClient);
+    if (!client) {
+        process.stdout.write('Chưa có client mặc định để cập nhật MCP config. Dùng thêm --client nếu muốn ghi ngay.\n');
+        return;
+    }
+    await runMcpAdd({
+        ...parsed,
+        positionals: ['mcp', 'add', client],
+        options: {
+            ...parsed.options,
+            'mcp-token': token.trim(),
+        },
+    }, nextDefaults, client);
+}
+async function runConfigShow(parsed) {
+    const config = await loadCliConfig(optionString(parsed, 'home-dir'));
+    process.stdout.write(`${JSON.stringify(config ?? {}, null, 2)}\n`);
+}
+async function runEval(parsed) {
+    const filePath = optionString(parsed, 'file');
+    if (!filePath) {
+        throw new Error('Thiếu --file cho bộ eval.');
+    }
+    const defaults = await loadRuntimeDefaults(parsed);
+    const raw = await readFile(filePath, 'utf8');
+    const suite = JSON.parse(raw);
+    const result = await runEvaluationSuite({
+        baseUrl: suite.baseUrl ?? defaults.baseUrl,
+        cases: suite.cases ?? [],
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result.failed === 0 ? 0 : 1;
+}
+async function runUpdateSetup(parsed) {
+    const defaults = await loadRuntimeDefaults(parsed);
+    const client = optionString(parsed, 'client') ?? defaults.defaultClient;
+    if (client) {
+        await runMcpAdd({
+            ...parsed,
+            positionals: ['mcp', 'add', client],
+        }, defaults, client);
+    }
+    if (!optionFlag(parsed, 'skip-skill')) {
+        await runSkillInstall(parsed, defaults);
+    }
+}
+export async function runCli(argv) {
+    const parsed = parseArgv(argv);
+    const [group, action] = parsed.positionals;
+    try {
+        if (!group || group === 'help' || group === '--help') {
+            process.stdout.write(helpText());
+            return 0;
+        }
+        if (group === 'install') {
+            await runInstall(parsed);
+            return 0;
+        }
+        if (group === 'init') {
+            await runInit(parsed);
+            return 0;
+        }
+        if (group === 'token' && action === 'add') {
+            await runTokenAdd(parsed);
+            return 0;
+        }
+        if (group === 'config' && action === 'show') {
+            await runConfigShow(parsed);
+            return 0;
+        }
+        if (group === 'doctor') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            const results = await runDoctor({
+                baseUrl: defaults.baseUrl,
+            });
+            for (const result of results) {
+                process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
+            }
+            return results.every((result) => result.ok) ? 0 : 1;
+        }
+        if (group === 'codegraph' && action === 'status') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            await runCodegraphStatus(defaults.baseUrl);
+            return 0;
+        }
+        if (group === 'codegraph' && action === 'runs') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            const limit = Number.parseInt(optionString(parsed, 'limit', '20') ?? '20', 10);
+            await runCodegraphRuns(defaults.baseUrl, Number.isFinite(limit) && limit > 0 ? limit : 20);
+            return 0;
+        }
+        if (group === 'codegraph' && action === 'watch') {
+            await runCodegraphWatch(parsed);
+            return 0;
+        }
+        if (group === 'codegraph' && action === 'metrics') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            await runCodegraphMetrics(defaults.baseUrl);
+            return 0;
+        }
+        if (group === 'codegraph' && action === 'recover') {
+            await runCodegraphRecover(parsed);
+            return 0;
+        }
+        if (group === 'codegraph' && action === 'sync') {
+            await runCodegraphSync(parsed);
+            return 0;
+        }
+        if (group === 'docs' && action === 'get') {
+            await runDocsGet(parsed);
+            return 0;
+        }
+        if (group === 'mcp' && action === 'add') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            await runMcpAdd(parsed, defaults);
+            return 0;
+        }
+        if (group === 'skill' && action === 'install') {
+            const defaults = await loadRuntimeDefaults(parsed);
+            await runSkillInstall(parsed, defaults);
+            return 0;
+        }
+        if (group === 'eval' && action === 'run') {
+            return runEval(parsed);
+        }
+        if (group === 'update' && action === 'setup') {
+            await runUpdateSetup(parsed);
+            return 0;
+        }
+        if (group === 'version') {
+            process.stdout.write('sp-rag 0.3.0\n');
+            return 0;
+        }
+        process.stdout.write(helpText());
+        return 1;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+const exitCode = await runCli(process.argv.slice(2));
+process.exitCode = exitCode;

package/dist/lib/config-store.js

@@ -0,0 +1,39 @@
+import os from 'node:os';
+import path from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function resolveCliHomeDir(homeDir) {
+    const override = homeDir?.trim() || process.env['SP_RAG_HOME_DIR']?.trim();
+    return path.resolve(override || os.homedir());
+}
+export function resolveCliConfigDir(homeDir) {
+    return path.join(resolveCliHomeDir(homeDir), '.sp-rag');
+}
+export function resolveCliConfigPath(homeDir) {
+    return path.join(resolveCliConfigDir(homeDir), 'config.json');
+}
+export async function loadCliConfig(homeDir) {
+    const filePath = resolveCliConfigPath(homeDir);
+    const content = await readFile(filePath, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    });
+    if (!content) {
+        return null;
+    }
+    return JSON.parse(content);
+}
+export async function saveCliConfig(config, homeDir) {
+    const filePath = resolveCliConfigPath(homeDir);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const normalized = stripUndefined({
+        ...config,
+        updatedAt: new Date().toISOString(),
+    });
+    await writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+    return filePath;
+}

package/dist/lib/eval.js

@@ -0,0 +1,149 @@
+function parseJsonIfPossible(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+        return trimmed;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+}
+function extractDocText(payload) {
+    if (typeof payload === 'string') {
+        return payload;
+    }
+    if (payload && typeof payload === 'object') {
+        const record = payload;
+        if (typeof record['markdown'] === 'string') {
+            return record['markdown'];
+        }
+        if (typeof record['html'] === 'string') {
+            return record['html'];
+        }
+        if (typeof record['text'] === 'string') {
+            return record['text'];
+        }
+    }
+    return JSON.stringify(payload);
+}
+async function runQueryContextCase(baseUrl, testCase, fetchImpl) {
+    const startedAt = Date.now();
+    const response = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/api/v1/query/context`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            query_text: testCase.queryText,
+        }),
+    });
+    const bodyText = await response.text();
+    if (!response.ok) {
+        return {
+            id: testCase.id,
+            type: testCase.type,
+            ok: false,
+            durationMs: Date.now() - startedAt,
+            assertions: [],
+            errors: [`Query context thất bại (${response.status}): ${bodyText}`],
+        };
+    }
+    const payload = parseJsonIfPossible(bodyText);
+    const entityNames = new Set((payload.entities ?? []).map((entity) => entity.name).filter(Boolean));
+    const citationLabels = new Set((payload.citations ?? []).map((citation) => citation.label).filter(Boolean));
+    const relationCount = payload.relations?.length ?? 0;
+    const assertions = [];
+    const errors = [];
+    for (const expected of testCase.expectedEntityNames ?? []) {
+        if (entityNames.has(expected)) {
+            assertions.push(`Có entity ${expected}`);
+        }
+        else {
+            errors.push(`Thiếu entity ${expected}`);
+        }
+    }
+    for (const expected of testCase.expectedCitationLabels ?? []) {
+        if (citationLabels.has(expected)) {
+            assertions.push(`Có citation ${expected}`);
+        }
+        else {
+            errors.push(`Thiếu citation ${expected}`);
+        }
+    }
+    if (typeof testCase.minRelationCount === 'number') {
+        if (relationCount >= testCase.minRelationCount) {
+            assertions.push(`Số relation đạt ngưỡng ${testCase.minRelationCount}`);
+        }
+        else {
+            errors.push(`Số relation chỉ có ${relationCount}, thấp hơn ngưỡng ${testCase.minRelationCount}`);
+        }
+    }
+    return {
+        id: testCase.id,
+        type: testCase.type,
+        ok: errors.length === 0,
+        durationMs: Date.now() - startedAt,
+        assertions,
+        errors,
+    };
+}
+async function runRenderedDocsCase(baseUrl, testCase, fetchImpl) {
+    const startedAt = Date.now();
+    const query = new URLSearchParams({
+        format: testCase.format ?? 'md',
+    });
+    const response = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/codegraph/docs/${encodeURIComponent(testCase.docType)}?${query.toString()}`, { method: 'GET' });
+    const bodyText = await response.text();
+    if (!response.ok) {
+        return {
+            id: testCase.id,
+            type: testCase.type,
+            ok: false,
+            durationMs: Date.now() - startedAt,
+            assertions: [],
+            errors: [`Rendered docs thất bại (${response.status}): ${bodyText}`],
+        };
+    }
+    const payload = parseJsonIfPossible(bodyText);
+    const docText = extractDocText(payload);
+    const assertions = [];
+    const errors = [];
+    for (const expected of testCase.mustContainText ?? []) {
+        if (docText.includes(expected)) {
+            assertions.push(`Docs chứa "${expected}"`);
+        }
+        else {
+            errors.push(`Docs không chứa "${expected}"`);
+        }
+    }
+    return {
+        id: testCase.id,
+        type: testCase.type,
+        ok: errors.length === 0,
+        durationMs: Date.now() - startedAt,
+        assertions,
+        errors,
+    };
+}
+export async function runEvaluationSuite(options, fetchImpl = fetch) {
+    const startedAt = new Date().toISOString();
+    const results = [];
+    for (const testCase of options.cases) {
+        if (testCase.type === 'query_context') {
+            results.push(await runQueryContextCase(options.baseUrl, testCase, fetchImpl));
+            continue;
+        }
+        results.push(await runRenderedDocsCase(options.baseUrl, testCase, fetchImpl));
+    }
+    const passed = results.filter((entry) => entry.ok).length;
+    return {
+        total: results.length,
+        passed,
+        failed: results.length - passed,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        results,
+    };
+}

package/dist/lib/http.js

@@ -0,0 +1,50 @@
+import { defaultBaseUrl } from './mcp-config.js';
+export async function fetchJson(url, init, fetchImpl = fetch) {
+    const response = await fetchImpl(url, init);
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new Error(`Yêu cầu thất bại (${response.status}) tại ${url}: ${bodyText}`);
+    }
+    return bodyText.trim() ? JSON.parse(bodyText) : {};
+}
+export async function fetchText(url, init, fetchImpl = fetch) {
+    const response = await fetchImpl(url, init);
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new Error(`Yêu cầu thất bại (${response.status}) tại ${url}: ${bodyText}`);
+    }
+    return bodyText;
+}
+export async function runDoctor(options = {}) {
+    const baseUrl = (options.baseUrl?.trim() || defaultBaseUrl()).replace(/\/+$/, '');
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const checks = [
+        { name: 'api', url: `${baseUrl}/api/healthz` },
+        { name: 'mcp', url: `${baseUrl}/mcp/healthz` },
+        { name: 'codegraph', url: `${baseUrl}/codegraph/healthz` },
+        { name: 'codegraph-sync-status', url: `${baseUrl}/codegraph/sync-status` },
+    ];
+    const results = await Promise.all(checks.map(async (check) => {
+        try {
+            const response = await fetchImpl(check.url, { method: 'GET' });
+            const bodyText = await response.text();
+            return {
+                name: check.name,
+                url: check.url,
+                ok: response.ok,
+                status: response.status,
+                summary: bodyText.trim() || '(empty)',
+            };
+        }
+        catch (error) {
+            return {
+                name: check.name,
+                url: check.url,
+                ok: false,
+                status: 0,
+                summary: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }));
+    return results;
+}

package/dist/lib/mcp-config.js

@@ -0,0 +1,129 @@
+import os from 'node:os';
+import path from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function quotedTomlKey(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+export function defaultMcpServerAlias() {
+    return 'sp-rag';
+}
+export function defaultMcpUrl() {
+    return process.env['SP_RAG_MCP_URL']?.trim() || 'https://sp-rag.secomapp.com/mcp';
+}
+export function defaultBaseUrl() {
+    return process.env['SP_RAG_BASE_URL']?.trim() || 'https://sp-rag.secomapp.com';
+}
+export function upsertCodexConfig(existing, options) {
+    const alias = options.serverAlias.trim();
+    const aliasPattern = escapeRegex(alias);
+    const cleaned = existing
+        .replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\.headers\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), '')
+        .replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), '')
+        .trimEnd();
+    const lines = [
+        `[mcp_servers.${quotedTomlKey(alias)}]`,
+        `url = "${options.url}"`,
+    ];
+    const authToken = options.authToken?.trim();
+    const authEnvVar = options.authEnvVar?.trim();
+    if (authToken) {
+        lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.headers]`);
+        lines.push(`Authorization = "Bearer ${authToken.replace(/"/g, '\\"')}"`);
+    }
+    else if (authEnvVar) {
+        lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.headers]`);
+        lines.push(`Authorization = "Bearer \${${authEnvVar}}"`);
+    }
+    return `${cleaned ? `${cleaned}\n\n` : ''}${lines.join('\n')}\n`;
+}
+export function upsertJsonMcpConfig(existing, options) {
+    const base = existing?.trim()
+        ? JSON.parse(existing)
+        : {};
+    const mcpServers = base['mcpServers'] && typeof base['mcpServers'] === 'object'
+        ? { ...base['mcpServers'] }
+        : {};
+    const serverConfig = {
+        url: options.url,
+    };
+    if (options.includeTypeHttp) {
+        serverConfig['type'] = 'http';
+    }
+    const authToken = options.authToken?.trim();
+    const authEnvVar = options.authEnvVar?.trim();
+    if (authToken) {
+        serverConfig['headers'] = {
+            Authorization: `Bearer ${authToken}`,
+        };
+    }
+    else if (authEnvVar) {
+        serverConfig['headers'] = {
+            Authorization: `Bearer \${${authEnvVar}}`,
+        };
+    }
+    mcpServers[options.serverAlias] = serverConfig;
+    return `${JSON.stringify({
+        ...base,
+        mcpServers,
+    }, null, 2)}\n`;
+}
+export function resolveMcpConfigPath(options) {
+    const scope = options.scope ??
+        (options.client === 'codex' ? 'global' : 'project');
+    if (options.client === 'codex' && scope !== 'global') {
+        throw new Error('Codex hiện chỉ hỗ trợ scope global trong CLI này.');
+    }
+    if (options.client === 'claude-code' && scope !== 'project') {
+        throw new Error('Claude Code hiện chỉ hỗ trợ scope project trong CLI này.');
+    }
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const home = os.homedir();
+    switch (options.client) {
+        case 'codex':
+            return {
+                client: options.client,
+                scope,
+                path: path.join(home, '.codex', 'config.toml'),
+            };
+        case 'cursor':
+            return {
+                client: options.client,
+                scope,
+                path: scope === 'global'
+                    ? path.join(home, '.cursor', 'mcp.json')
+                    : path.join(cwd, '.cursor', 'mcp.json'),
+            };
+        case 'claude-code':
+            return {
+                client: options.client,
+                scope,
+                path: path.join(cwd, '.mcp.json'),
+            };
+    }
+}
+export async function installMcpConfig(options) {
+    const resolved = resolveMcpConfigPath(options);
+    const existing = await readFile(resolved.path, 'utf8').catch(() => '');
+    const alias = options.serverAlias?.trim() || defaultMcpServerAlias();
+    const url = options.url.trim();
+    const content = resolved.client === 'codex'
+        ? upsertCodexConfig(existing, {
+            serverAlias: alias,
+            url,
+            authEnvVar: options.authEnvVar,
+            authToken: options.authToken,
+        })
+        : upsertJsonMcpConfig(existing, {
+            serverAlias: alias,
+            url,
+            authEnvVar: options.authEnvVar,
+            authToken: options.authToken,
+            includeTypeHttp: resolved.client === 'claude-code',
+        });
+    await mkdir(path.dirname(resolved.path), { recursive: true });
+    await writeFile(resolved.path, content, 'utf8');
+    return resolved;
+}

package/dist/lib/skill.js

@@ -0,0 +1,51 @@
+import os from 'node:os';
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+export function defaultSkillDir() {
+    return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
+}
+export function renderCodexSkill(options) {
+    return `---
+name: sp-rag
+description: Dùng RAG nội bộ qua MCP để trả lời câu hỏi về codebase, domain, docs và vận hành trước khi dựa vào trí nhớ.
+---
+
+# SP-RAG
+
+MCP server alias mặc định: \`${options.serverAlias}\`
+MCP URL: \`${options.mcpUrl}\`
+Docs URL: \`${options.docsUrl}\`
+
+## Khi nào dùng
+
+- Khi câu hỏi liên quan đến codebase nội bộ, domain nghiệp vụ, docs đã render, trạng thái sync hoặc inventory import.
+- Khi cần câu trả lời có evidence thay vì suy đoán theo trí nhớ.
+
+## Luồng dùng khuyến nghị
+
+1. Gọi \`healthz\` nếu nghi server đang lỗi hoặc vừa kết nối lần đầu.
+2. Dùng \`query_context\` cho câu hỏi về kiến trúc, domain, flow nghiệp vụ, entities, relations.
+3. Dùng \`get_rendered_docs\` cho public docs, function docs hoặc dev docs đã render sẵn.
+4. Dùng \`get_sync_status\`, \`get_sync_runs\` hoặc \`get_sync_metrics\` khi cần kiểm tra code graph đang ở commit nào, sync có lỗi không, hay muốn đọc lịch sử và metrics vận hành.
+5. Chỉ dùng \`trigger_code_graph_sync\` khi user yêu cầu làm mới index hoặc code graph.
+
+## Nguyên tắc trả lời
+
+- Ưu tiên câu trả lời grounded từ MCP/RAG trước.
+- Nếu evidence có dấu hiệu stale, nói rõ dữ liệu có thể chưa được sync mới nhất.
+- Không tự kích hoạt sync/index nếu user chưa yêu cầu hoặc chưa thật sự cần.
+- Khi docs đã đủ, ưu tiên trích từ docs đã render thay vì tự diễn giải dài dòng.
+`;
+}
+export async function installCodexSkill(options = {}) {
+    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir());
+    const filePath = path.join(targetDir, 'SKILL.md');
+    const content = renderCodexSkill({
+        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',
+    });
+    await mkdir(targetDir, { recursive: true });
+    await writeFile(filePath, content, 'utf8');
+    return { path: filePath };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "sp-rag",
+  "version": "0.3.0",
+  "description": "CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "sp-rag": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "rag",
+    "mcp",
+    "gitnexus",
+    "cli",
+    "sp-rag"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.7"
+  }
+}