gitnexushub 0.2.1

package/dist/api.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hub API Client
+ *
+ * Fetch-based, zero-dependency API client for GitNexus Hub.
+ */
+export interface UserProfile {
+    id: string;
+    name: string;
+    email: string;
+}
+export interface HubRepo {
+    id: string;
+    name: string;
+    fullName: string;
+    status: string;
+    stats?: {
+        nodes?: number;
+        edges?: number;
+        processes?: number;
+    };
+}
+export interface ConnectContext {
+    claudeMd: string;
+    agentsMd: string;
+    skills: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+export interface IndexResult {
+    id: string;
+    name: string;
+    fullName: string;
+    status: string;
+}
+export interface RepoDetail {
+    id: string;
+    name: string;
+    fullName: string;
+    status: string;
+    stats?: {
+        nodes?: number;
+        edges?: number;
+        processes?: number;
+    };
+    error?: string;
+    job?: {
+        status: string;
+        progress: number;
+        phase: string;
+    } | null;
+}
+export declare class HubAPI {
+    private hubUrl;
+    private token;
+    constructor(hubUrl: string, token: string);
+    private request;
+    private post;
+    getMe(): Promise<UserProfile>;
+    listRepos(): Promise<HubRepo[]>;
+    getConnectContext(repoFullName: string): Promise<ConnectContext>;
+    indexRepo(fullName: string): Promise<IndexResult>;
+    getRepo(repoId: string): Promise<RepoDetail>;
+}

package/dist/api.js

@@ -0,0 +1,55 @@
+/**
+ * Hub API Client
+ *
+ * Fetch-based, zero-dependency API client for GitNexus Hub.
+ */
+export class HubAPI {
+    hubUrl;
+    token;
+    constructor(hubUrl, token) {
+        this.hubUrl = hubUrl;
+        this.token = token;
+    }
+    async request(path) {
+        const url = `${this.hubUrl}${path}`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.token}` },
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(body.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
+    async post(path, body) {
+        const url = `${this.hubUrl}${path}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const data = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(data.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
+    async getMe() {
+        return this.request('/auth/me');
+    }
+    async listRepos() {
+        return this.request('/api/repos');
+    }
+    async getConnectContext(repoFullName) {
+        return this.request(`/api/connect/context?repo=${encodeURIComponent(repoFullName)}`);
+    }
+    async indexRepo(fullName) {
+        return this.post('/api/repos/public', { fullName });
+    }
+    async getRepo(repoId) {
+        return this.request(`/api/repos/${repoId}`);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Config Manager
+ *
+ * Persists Hub token and URL in ~/.gitnexus/config.json.
+ */
+interface ConnectConfig {
+    hubToken?: string;
+    hubUrl?: string;
+}
+export declare function loadConfig(): Promise<ConnectConfig>;
+export declare function saveConfig(updates: Partial<ConnectConfig>): Promise<void>;
+export declare function clearConfig(): Promise<void>;
+export declare function getConfigPath(): string;
+export {};

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * Config Manager
+ *
+ * Persists Hub token and URL in ~/.gitnexus/config.json.
+ */
+import os from 'os';
+import path from 'path';
+import { readJsonFile, writeJsonFile } from './utils.js';
+const CONFIG_DIR = path.join(os.homedir(), '.gitnexus');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+export async function loadConfig() {
+    const data = await readJsonFile(CONFIG_PATH);
+    return data || {};
+}
+export async function saveConfig(updates) {
+    const existing = await loadConfig();
+    const merged = { ...existing, ...updates };
+    await writeJsonFile(CONFIG_PATH, merged);
+}
+export async function clearConfig() {
+    try {
+        const fs = await import('fs/promises');
+        await fs.rm(CONFIG_DIR, { recursive: true, force: true });
+    }
+    catch {
+        // Already gone
+    }
+}
+export function getConfigPath() {
+    return CONFIG_PATH;
+}

package/dist/content.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Content Generator
+ *
+ * Generates CLAUDE.md, AGENTS.md content and loads bundled skills.
+ * Self-contained — no Hub API dependency for content generation.
+ */
+import type { ConnectContext } from './api.js';
+/** Skills to include for Hub users (excludes gitnexus-cli) */
+export declare const HUB_SKILLS: string[];
+interface RepoStats {
+    nodes?: number;
+    edges?: number;
+    processes?: number;
+}
+/**
+ * Generate full ConnectContext from repo stats + bundled skills.
+ * No Hub API round-trip needed.
+ */
+export declare function generateConnectContext(repoFullName: string, stats: RepoStats): Promise<ConnectContext>;
+export {};

package/dist/content.js

@@ -0,0 +1,137 @@
+/**
+ * Content Generator
+ *
+ * Generates CLAUDE.md, AGENTS.md content and loads bundled skills.
+ * Self-contained — no Hub API dependency for content generation.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
+const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
+/** Skills to include for Hub users (excludes gitnexus-cli) */
+export const HUB_SKILLS = [
+    'gitnexus-exploring',
+    'gitnexus-debugging',
+    'gitnexus-impact-analysis',
+    'gitnexus-refactoring',
+    'gitnexus-guide',
+    'gitnexus-pr-review',
+];
+/**
+ * Generate Hub-flavored CLAUDE.md / AGENTS.md content.
+ * No detect_changes or rename references (not available via Hub MCP).
+ */
+function generateHubContent(projectName, stats) {
+    return `${GITNEXUS_START_MARKER}
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Re-indexing is managed from the GitNexus Hub dashboard.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
+
+## When Debugging
+
+1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+
+## When Refactoring
+
+- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
+| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
+| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
+| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`gitnexus_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. All d=1 (WILL BREAK) dependents were updated
+
+${GITNEXUS_END_MARKER}`;
+}
+/**
+ * Replace CLI references with Hub dashboard instructions.
+ */
+function adaptSkillForHub(content) {
+    return content
+        .replace(/run `npx gitnexus analyze` in terminal\.?/g, 'trigger re-indexing from the Hub dashboard.')
+        .replace(/run `npx gitnexus analyze` in the terminal first\.?/g, 'trigger re-indexing from the Hub dashboard.')
+        .replace(/> If "Index is stale" → run `npx gitnexus analyze` in terminal\.?/g, '> If "Index is stale" → trigger re-indexing from the Hub dashboard.')
+        .replace(/> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal\.?/g, '> If step 2 says "Index is stale" → trigger re-indexing from the Hub dashboard.')
+        .replace(/> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first\.?/g, '> If step 1 warns the index is stale, trigger re-indexing from the Hub dashboard.')
+        .replace(/> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first\.?/g, '> Re-indexing is managed from the GitNexus Hub dashboard.');
+}
+/**
+ * Load bundled skills from the package's own skills/ directory.
+ * Skills ship with the npm package — no Hub API needed.
+ */
+async function loadBundledSkills() {
+    // Skills are at ../skills/ relative to dist/ (or ../../skills/ relative to src/)
+    const skillsDir = path.join(__dirname, '..', 'skills');
+    const skills = [];
+    for (const skillName of HUB_SKILLS) {
+        try {
+            const skillPath = path.join(skillsDir, `${skillName}.md`);
+            const raw = await fs.readFile(skillPath, 'utf-8');
+            skills.push({ name: skillName, content: adaptSkillForHub(raw) });
+        }
+        catch {
+            // Skill file not found — skip
+        }
+    }
+    return skills;
+}
+/**
+ * Generate full ConnectContext from repo stats + bundled skills.
+ * No Hub API round-trip needed.
+ */
+export async function generateConnectContext(repoFullName, stats) {
+    const projectName = repoFullName.split('/').pop() || repoFullName;
+    const content = generateHubContent(projectName, stats);
+    const skills = await loadBundledSkills();
+    return {
+        claudeMd: content,
+        agentsMd: content,
+        skills,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Project Context Writer
+ *
+ * Writes CLAUDE.md, AGENTS.md, and skills into the current project.
+ */
+import type { ConnectContext } from './api.js';
+export interface ContextResult {
+    files: string[];
+}
+export declare function writeProjectContext(projectDir: string, ctx: ConnectContext): Promise<ContextResult>;
+export declare function removeProjectContext(projectDir: string): Promise<string[]>;

package/dist/context.js

@@ -0,0 +1,50 @@
+/**
+ * Project Context Writer
+ *
+ * Writes CLAUDE.md, AGENTS.md, and skills into the current project.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { upsertMarkedSection, removeMarkedSection } from './utils.js';
+export async function writeProjectContext(projectDir, ctx) {
+    const files = [];
+    // Write CLAUDE.md
+    const claudePath = path.join(projectDir, 'CLAUDE.md');
+    const claudeResult = await upsertMarkedSection(claudePath, ctx.claudeMd);
+    files.push(`CLAUDE.md (${claudeResult})`);
+    // Write AGENTS.md
+    const agentsPath = path.join(projectDir, 'AGENTS.md');
+    const agentsResult = await upsertMarkedSection(agentsPath, ctx.agentsMd);
+    files.push(`AGENTS.md (${agentsResult})`);
+    // Write skills to .claude/skills/gitnexus/
+    if (ctx.skills.length > 0) {
+        const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
+        for (const skill of ctx.skills) {
+            const skillDir = path.join(skillsDir, skill.name);
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), skill.content, 'utf-8');
+        }
+        files.push(`.claude/skills/gitnexus/ (${ctx.skills.length} skills)`);
+    }
+    return { files };
+}
+export async function removeProjectContext(projectDir) {
+    const removed = [];
+    // Remove marked sections from CLAUDE.md and AGENTS.md
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+        const filePath = path.join(projectDir, name);
+        if (await removeMarkedSection(filePath)) {
+            removed.push(name);
+        }
+    }
+    // Remove .claude/skills/gitnexus/ directory
+    const skillsDir = path.join(projectDir, '.claude', 'skills', 'gitnexus');
+    try {
+        await fs.rm(skillsDir, { recursive: true, force: true });
+        removed.push('.claude/skills/gitnexus/');
+    }
+    catch {
+        // Already gone
+    }
+    return removed;
+}

package/dist/editors/claude-code.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Claude Code Editor Setup
+ *
+ * Runs `claude mcp add` CLI command, or falls back to writing ~/.claude.json.
+ * Skills are installed to ~/.claude/skills/.
+ */
+import type { EditorConfig } from './types.js';
+export declare const claudeCodeEditor: EditorConfig;

package/dist/editors/claude-code.js

@@ -0,0 +1,129 @@
+/**
+ * Claude Code Editor Setup
+ *
+ * Runs `claude mcp add` CLI command, or falls back to writing ~/.claude.json.
+ * Skills are installed to ~/.claude/skills/.
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs/promises';
+import { execSync } from 'child_process';
+import { readJsonFile, writeJsonFile } from '../utils.js';
+import { HUB_SKILLS } from '../content.js';
+const GITNEXUS_SKILL_NAMES = HUB_SKILLS;
+function isClaudeOnPath() {
+    try {
+        execSync('claude --version', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function configure(hubUrl, token) {
+    const mcpUrl = `${hubUrl}/mcp`;
+    const headerValue = `Authorization: Bearer ${token}`;
+    // Try `claude mcp add` first
+    if (isClaudeOnPath()) {
+        try {
+            const cmd = `claude mcp add gitnexus --transport streamable-http --url "${mcpUrl}" --header "${headerValue}"`;
+            if (process.platform === 'win32') {
+                execSync(`cmd /c ${cmd}`, { stdio: 'pipe' });
+            }
+            else {
+                execSync(cmd, { stdio: 'pipe' });
+            }
+            return { success: true, message: 'MCP configured via `claude mcp add`' };
+        }
+        catch {
+            // Fall through to file-based config
+        }
+    }
+    // Fallback: write ~/.claude.json
+    try {
+        const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+        const existing = (await readJsonFile(claudeJsonPath)) || {};
+        if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+            existing.mcpServers = {};
+        }
+        existing.mcpServers.gitnexus = {
+            type: 'streamable-http',
+            url: mcpUrl,
+            headers: { Authorization: `Bearer ${token}` },
+        };
+        await writeJsonFile(claudeJsonPath, existing);
+        return { success: true, message: 'MCP configured in ~/.claude.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function installSkills(skills) {
+    const skillsDir = path.join(os.homedir(), '.claude', 'skills');
+    let installed = 0;
+    for (const skill of skills) {
+        try {
+            const skillDir = path.join(skillsDir, skill.name);
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), skill.content, 'utf-8');
+            installed++;
+        }
+        catch {
+            // Skip on error
+        }
+    }
+    return installed;
+}
+async function unconfigure() {
+    // Try `claude mcp remove` first
+    if (isClaudeOnPath()) {
+        try {
+            const cmd = 'claude mcp remove gitnexus';
+            if (process.platform === 'win32') {
+                execSync(`cmd /c ${cmd}`, { stdio: 'pipe' });
+            }
+            else {
+                execSync(cmd, { stdio: 'pipe' });
+            }
+            return { success: true, message: 'MCP removed via `claude mcp remove`' };
+        }
+        catch {
+            // Fall through to file-based removal
+        }
+    }
+    // Fallback: remove from ~/.claude.json
+    try {
+        const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+        const existing = await readJsonFile(claudeJsonPath);
+        if (existing?.mcpServers?.gitnexus) {
+            delete existing.mcpServers.gitnexus;
+            await writeJsonFile(claudeJsonPath, existing);
+        }
+        return { success: true, message: 'MCP removed from ~/.claude.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function removeSkills() {
+    const skillsDir = path.join(os.homedir(), '.claude', 'skills');
+    let removed = 0;
+    for (const name of GITNEXUS_SKILL_NAMES) {
+        try {
+            await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Already gone
+        }
+    }
+    return removed;
+}
+export const claudeCodeEditor = {
+    id: 'claude-code',
+    name: 'Claude Code',
+    configure,
+    unconfigure,
+    installSkills,
+    removeSkills,
+};

package/dist/editors/cursor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cursor Editor Setup
+ *
+ * Writes MCP config to ~/.cursor/mcp.json
+ * Installs skills to ~/.cursor/skills/
+ */
+import type { EditorConfig } from './types.js';
+export declare const cursorEditor: EditorConfig;

package/dist/editors/cursor.js

@@ -0,0 +1,83 @@
+/**
+ * Cursor Editor Setup
+ *
+ * Writes MCP config to ~/.cursor/mcp.json
+ * Installs skills to ~/.cursor/skills/
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs/promises';
+import { readJsonFile, writeJsonFile } from '../utils.js';
+import { HUB_SKILLS } from '../content.js';
+function getMcpConfig(hubUrl, token) {
+    return {
+        type: 'streamable-http',
+        url: `${hubUrl}/mcp`,
+        headers: { Authorization: `Bearer ${token}` },
+    };
+}
+async function configure(hubUrl, token) {
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    try {
+        const existing = (await readJsonFile(mcpPath)) || {};
+        if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+            existing.mcpServers = {};
+        }
+        existing.mcpServers.gitnexus = getMcpConfig(hubUrl, token);
+        await writeJsonFile(mcpPath, existing);
+        return { success: true, message: 'MCP configured in ~/.cursor/mcp.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function installSkills(skills) {
+    const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
+    let installed = 0;
+    for (const skill of skills) {
+        try {
+            const skillDir = path.join(skillsDir, skill.name);
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(path.join(skillDir, 'SKILL.md'), skill.content, 'utf-8');
+            installed++;
+        }
+        catch {
+            // Skip on error
+        }
+    }
+    return installed;
+}
+async function unconfigure() {
+    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        if (existing?.mcpServers?.gitnexus) {
+            delete existing.mcpServers.gitnexus;
+            await writeJsonFile(mcpPath, existing);
+        }
+        return { success: true, message: 'MCP removed from ~/.cursor/mcp.json' };
+    }
+    catch (err) {
+        return { success: false, message: `Failed: ${err.message}` };
+    }
+}
+async function removeSkills() {
+    const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
+    let removed = 0;
+    for (const name of HUB_SKILLS) {
+        try {
+            await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
+            removed++;
+        }
+        catch { /* already gone */ }
+    }
+    return removed;
+}
+export const cursorEditor = {
+    id: 'cursor',
+    name: 'Cursor',
+    configure,
+    unconfigure,
+    installSkills,
+    removeSkills,
+};

package/dist/editors/detect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Editor Auto-Detection
+ *
+ * Probes well-known directories to detect which editors are installed.
+ */
+import type { EditorId } from './types.js';
+export declare function detectInstalledEditors(): Promise<EditorId[]>;

package/dist/editors/detect.js

@@ -0,0 +1,42 @@
+/**
+ * Editor Auto-Detection
+ *
+ * Probes well-known directories to detect which editors are installed.
+ */
+import os from 'os';
+import path from 'path';
+import { dirExists } from '../utils.js';
+const PROBES = [
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        dirs: [path.join(os.homedir(), '.cursor')],
+    },
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        dirs: [path.join(os.homedir(), '.claude')],
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        dirs: [path.join(os.homedir(), '.codeium', 'windsurf')],
+    },
+    {
+        id: 'opencode',
+        name: 'OpenCode',
+        dirs: [path.join(os.homedir(), '.config', 'opencode')],
+    },
+];
+export async function detectInstalledEditors() {
+    const found = [];
+    for (const probe of PROBES) {
+        for (const dir of probe.dirs) {
+            if (await dirExists(dir)) {
+                found.push(probe.id);
+                break;
+            }
+        }
+    }
+    return found;
+}

package/dist/editors/opencode.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OpenCode Editor Setup
+ *
+ * Writes MCP config to ~/.config/opencode/config.json (under `mcp` key)
+ * Installs skills to ~/.config/opencode/skill/
+ */
+import type { EditorConfig } from './types.js';
+export declare const opencodeEditor: EditorConfig;