gitnexushub 0.3.0 → 0.4.1

package/dist/api.d.ts

@@ -50,6 +50,28 @@ export interface RepoDetail {
         phase: string;
     } | null;
 }
+export interface RepoMeta {
+    full_name: string;
+    last_commit: string | null;
+    indexed_at: string | null;
+    graph_epoch: number;
+    stats: Record<string, number>;
+}
+export interface SyncMetadata {
+    local_head: string;
+    local_branch?: string;
+    dirty?: boolean;
+}
+export interface SyncResult {
+    status: 'queued' | 'already_fresh';
+    job_id: string | null;
+}
+export interface SyncJobStatus {
+    status: string;
+    progress: number;
+    phase: string | null;
+    error: string | null;
+}
 export declare class HubAPI {
     private hubUrl;
     private token;
@@ -64,4 +86,10 @@ export declare class HubAPI {
     getConnectContext(repoFullName: string): Promise<ConnectContext>;
     indexRepo(fullName: string): Promise<IndexResult>;
     getRepo(repoId: string): Promise<RepoDetail>;
+    meta(repoId: string): Promise<RepoMeta>;
+    sync(repoId: string, params: {
+        metadata: SyncMetadata;
+        tarball: NodeJS.ReadableStream;
+    }): Promise<SyncResult>;
+    syncStatus(repoId: string, jobId: string): Promise<SyncJobStatus>;
 }

package/dist/api.js

@@ -64,4 +64,43 @@ export class HubAPI {
     async getRepo(repoId) {
         return this.request(`/api/repos/${repoId}`);
     }
+    async meta(repoId) {
+        return this.request(`/api/repos/${repoId}/meta`);
+    }
+    async sync(repoId, params) {
+        // Gzip the tarball stream into a Buffer. For now, buffer in memory —
+        // typical repo size is <200MB. Streaming multipart via fetch is nontrivial
+        // in Node and not worth the complexity for the first cut.
+        const { createGzip } = await import('zlib');
+        const gz = params.tarball.pipe(createGzip());
+        const chunks = [];
+        for await (const chunk of gz) {
+            chunks.push(chunk);
+        }
+        const gzBuf = Buffer.concat(chunks);
+        const form = new FormData();
+        form.append('metadata', JSON.stringify(params.metadata));
+        // Blob + filename triggers fetch to set up the file-part headers correctly
+        form.append('tarball', new Blob([gzBuf]), 'tarball.tar.gz');
+        const url = `${this.hubUrl}/api/repos/${repoId}/sync`;
+        const res = await fetch(url, {
+            method: 'POST',
+            // IMPORTANT: do NOT set Content-Type — fetch sets it with the multipart boundary
+            headers: this.authHeaders,
+            body: form,
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ error: res.statusText }));
+            // Preserve the HTTP status so the CLI can branch on 503/409
+            // (at-capacity / conflict) and present friendlier hints rather
+            // than a generic "Sync failed" line.
+            const err = new Error(body.error || `HTTP ${res.status}`);
+            err.statusCode = res.status;
+            throw err;
+        }
+        return res.json();
+    }
+    async syncStatus(repoId, jobId) {
+        return this.request(`/api/repos/${repoId}/sync/${jobId}`);
+    }
 }

package/dist/cli-helpers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared CLI helpers — log output and auth resolution.
+ *
+ * Extracted from index.ts so the individual command-flow files
+ * (connect-command.ts, etc.) can be imported and unit-tested without
+ * pulling in commander's top-level program.parse() side effect.
+ */
+import { HubAPI } from './api.js';
+import type { EditorId, EditorConfig } from './editors/types.js';
+export declare const EDITORS: Record<EditorId, EditorConfig>;
+export declare const ok: (msg: string) => void;
+export declare const info: (msg: string) => void;
+export declare const warn: (msg: string) => void;
+export declare const fail: (msg: string) => void;
+export declare const DEFAULT_HUB_URL: string;
+/**
+ * Resolve token + Hub URL from args/config. Exits on failure.
+ */
+export declare function resolveAuth(tokenArg?: string, hubOpt?: string): Promise<{
+    api: HubAPI;
+    hubUrl: string;
+    token: string;
+}>;

package/dist/cli-helpers.js

@@ -0,0 +1,57 @@
+/**
+ * Shared CLI helpers — log output and auth resolution.
+ *
+ * Extracted from index.ts so the individual command-flow files
+ * (connect-command.ts, etc.) can be imported and unit-tested without
+ * pulling in commander's top-level program.parse() side effect.
+ */
+import pc from 'picocolors';
+import { loadConfig, saveConfig } from './config.js';
+import { HubAPI } from './api.js';
+import { claudeCodeEditor } from './editors/claude-code.js';
+import { cursorEditor } from './editors/cursor.js';
+import { windsurfEditor } from './editors/windsurf.js';
+import { opencodeEditor } from './editors/opencode.js';
+export const EDITORS = {
+    'claude-code': claudeCodeEditor,
+    cursor: cursorEditor,
+    windsurf: windsurfEditor,
+    opencode: opencodeEditor,
+};
+export const ok = (msg) => console.log(`  ${pc.green('✔')} ${msg}`);
+export const info = (msg) => console.log(`  ${pc.cyan('ℹ')} ${msg}`);
+export const warn = (msg) => console.log(`  ${pc.yellow('⚠')} ${msg}`);
+export const fail = (msg) => console.error(`  ${pc.red('✗')} ${msg}`);
+export const DEFAULT_HUB_URL = process.env.GITNEXUS_HUB_URL || 'https://gitnexus-enterprise-production.up.railway.app';
+/**
+ * Resolve token + Hub URL from args/config. Exits on failure.
+ */
+export async function resolveAuth(tokenArg, hubOpt) {
+    const config = await loadConfig();
+    const token = tokenArg || config.hubToken;
+    const hubUrl = hubOpt || config.hubUrl || DEFAULT_HUB_URL;
+    if (!token) {
+        fail('No API token provided.');
+        console.error('');
+        console.error(`    Usage: ${pc.cyan('npx gitnexushub gnx_YOUR_TOKEN --editor cursor')}`);
+        console.error(`    Generate a token at: ${pc.cyan(hubUrl + '/settings/tokens')}`);
+        console.error('');
+        process.exit(1);
+    }
+    if (!token.startsWith('gnx_')) {
+        fail(`Invalid token format. Tokens must start with ${pc.bold('gnx_')}`);
+        console.error('');
+        process.exit(1);
+    }
+    const api = new HubAPI(hubUrl, token);
+    const user = await api.getMe().catch((err) => {
+        fail(`Authentication failed: ${err.message}`);
+        console.error(`    Check your token and try again.`);
+        console.error('');
+        process.exit(1);
+    });
+    ok(`Hello, ${pc.bold(user.name)}!`);
+    console.log('');
+    await saveConfig({ hubToken: token, hubUrl });
+    return { api, hubUrl, token };
+}

package/dist/connect-command.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `gnx connect` flow — register Hub MCP, install skills, install hooks,
+ * and write project context files.
+ *
+ * Extracted from index.ts so it can be imported (and unit-tested) without
+ * triggering commander's top-level program.parse() side effect.
+ */
+/**
+ * Resolve the path to the shipped hook script (`gitnexus-enterprise-hook.cjs`).
+ *
+ * Lives at `hooks/` in the package root, sibling to `dist/` and `src/`:
+ *   npm install → <npm-prefix>/lib/node_modules/gitnexushub/hooks/gitnexus-enterprise-hook.cjs
+ *   dev (tsx)   → <repo>/gitnexus-connect/hooks/gitnexus-enterprise-hook.cjs
+ *
+ * Both resolve via `..` from the file's own location. For the dev case,
+ * `import.meta.url` points at `src/connect-command.ts`, so `..` from `src/` →
+ * package root. For the dist case, `import.meta.url` points at
+ * `dist/connect-command.js`, so `..` from `dist/` → package root.
+ */
+export declare function resolveHookScriptPath(): string;
+/**
+ * Connect flow entry point — called from `gnx connect` CLI action and
+ * (for testability) directly from unit tests.
+ */
+export declare function runConnect(tokenArg: string | undefined, opts: {
+    editor?: string;
+    hub?: string;
+    skipProject?: boolean;
+}): Promise<undefined>;

package/dist/connect-command.js

@@ -0,0 +1,169 @@
+/**
+ * `gnx connect` flow — register Hub MCP, install skills, install hooks,
+ * and write project context files.
+ *
+ * Extracted from index.ts so it can be imported (and unit-tested) without
+ * triggering commander's top-level program.parse() side effect.
+ */
+import path from 'path';
+import { fileURLToPath } from 'url';
+import pc from 'picocolors';
+import { loadConfig } from './config.js';
+import { generateConnectContext } from './content.js';
+import { isGitRepo, getGitRemoteUrl, parseGitRemote, matchRepo } from './project.js';
+import { writeProjectContext } from './context.js';
+import { detectInstalledEditors } from './editors/detect.js';
+import { installClaudeCodeHook, installCursorHook, installOpenCodeHook, } from './hooks-installer.js';
+import { ok, info, warn, fail, resolveAuth, EDITORS } from './cli-helpers.js';
+/**
+ * Resolve the path to the shipped hook script (`gitnexus-enterprise-hook.cjs`).
+ *
+ * Lives at `hooks/` in the package root, sibling to `dist/` and `src/`:
+ *   npm install → <npm-prefix>/lib/node_modules/gitnexushub/hooks/gitnexus-enterprise-hook.cjs
+ *   dev (tsx)   → <repo>/gitnexus-connect/hooks/gitnexus-enterprise-hook.cjs
+ *
+ * Both resolve via `..` from the file's own location. For the dev case,
+ * `import.meta.url` points at `src/connect-command.ts`, so `..` from `src/` →
+ * package root. For the dist case, `import.meta.url` points at
+ * `dist/connect-command.js`, so `..` from `dist/` → package root.
+ */
+export function resolveHookScriptPath() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '..', 'hooks', 'gitnexus-enterprise-hook.cjs');
+}
+/**
+ * Connect flow entry point — called from `gnx connect` CLI action and
+ * (for testability) directly from unit tests.
+ */
+export async function runConnect(tokenArg, opts) {
+    const { api, hubUrl, token } = await resolveAuth(tokenArg, opts.hub);
+    // ── Resolve editor ─────────────────────────────────────────────
+    const config = await loadConfig();
+    let editorId;
+    if (opts.editor) {
+        if (!(opts.editor in EDITORS)) {
+            fail(`Unknown editor: ${pc.bold(opts.editor)}`);
+            console.error(`    Supported: ${pc.cyan(Object.keys(EDITORS).join(', '))}`);
+            console.error('');
+            return process.exit(1);
+        }
+        editorId = opts.editor;
+    }
+    else if (!config.hubToken) {
+        const detected = await detectInstalledEditors();
+        if (detected.length === 1) {
+            editorId = detected[0];
+            info(`Auto-detected editor: ${pc.bold(EDITORS[editorId].name)}`);
+        }
+        else if (detected.length > 1) {
+            warn('Multiple editors detected. Please specify one:');
+            for (const id of detected) {
+                console.error(`      ${pc.cyan('--editor ' + id)}`);
+            }
+            console.error('');
+            return process.exit(1);
+        }
+        else {
+            fail('No editor detected. Please specify one:');
+            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode')}`);
+            console.error('');
+            return process.exit(1);
+        }
+    }
+    // ── Configure editor MCP ────────────────────────────────────────
+    let skills = [];
+    if (editorId) {
+        const editor = EDITORS[editorId];
+        info(`Configuring ${pc.bold(editor.name)}...`);
+        const result = await editor.configure(hubUrl, token);
+        if (result.success) {
+            ok(result.message);
+            if (result.overrodeCli) {
+                console.log('');
+                console.log(`  ${pc.cyan('⬆')} ${pc.bold('GitNexus open-source detected — upgraded to Hub')}`);
+                console.log(`     ${pc.dim('Remote indexing. Deeper analysis. PR blast radius. Auto-reindex on push.')}`);
+                console.log(`     ${pc.dim('Your tools (query, context, impact) are unchanged — just faster and smarter.')}`);
+            }
+        }
+        else {
+            fail(result.message);
+        }
+        try {
+            const bundled = await generateConnectContext('_', {});
+            skills = bundled.skills;
+        }
+        catch {
+            // Skills load failed — continue without
+        }
+        if (editor.installSkills && skills.length > 0) {
+            const count = await editor.installSkills(skills);
+            if (count > 0) {
+                ok(`${count} skills installed`);
+            }
+        }
+        // ── Install editor hooks (PreToolUse augmentation + PostToolUse staleness) ──
+        try {
+            const hookScriptPath = resolveHookScriptPath();
+            if (editorId === 'claude-code') {
+                await installClaudeCodeHook({ hookScriptPath });
+                ok('Hooks installed');
+            }
+            else if (editorId === 'cursor') {
+                await installCursorHook({ hookScriptPath });
+                ok('Hooks installed');
+            }
+            else if (editorId === 'opencode') {
+                await installOpenCodeHook({ hookScriptPath });
+                ok('Hooks installed');
+            }
+            // windsurf: no hook system, skip silently
+        }
+        catch (err) {
+            warn(`Hook install failed: ${err.message}`);
+        }
+    }
+    // ── Write project context ───────────────────────────────────────
+    if (!opts.skipProject && isGitRepo()) {
+        const remoteUrl = getGitRemoteUrl();
+        const remoteFullName = remoteUrl ? parseGitRemote(remoteUrl) : null;
+        if (remoteFullName) {
+            console.log('');
+            info(`Project: ${pc.bold(remoteFullName)}`);
+            try {
+                const repos = await api.listRepos();
+                const matched = matchRepo(remoteFullName, repos);
+                if (matched) {
+                    if (matched.status === 'ready') {
+                        const ctx = await generateConnectContext(matched.fullName, matched.stats || {});
+                        const result = await writeProjectContext(process.cwd(), ctx);
+                        for (const file of result.files) {
+                            ok(file);
+                        }
+                    }
+                    else {
+                        warn(`Repo status: ${pc.yellow(matched.status)} ${pc.dim('(waiting for indexing)')}`);
+                    }
+                }
+                else {
+                    warn('Repo not indexed on Hub yet');
+                    console.log(`      Add it at: ${pc.cyan(hubUrl)}`);
+                }
+            }
+            catch (err) {
+                fail(`Failed to fetch project context: ${err.message}`);
+            }
+        }
+        else {
+            console.log('');
+            warn('No GitHub remote found — skipping project context');
+        }
+    }
+    else if (!opts.skipProject) {
+        console.log('');
+        info('Not inside a git repo — skipping project context');
+    }
+    // ── Summary ────────────────────────────────────────────────────
+    console.log('');
+    console.log(`  ${pc.green('✔')} ${pc.bold('Done!')} Open your editor — GitNexus MCP is ready.`);
+    console.log('');
+}

package/dist/editors/claude-code.js

@@ -19,6 +19,14 @@ async function configure(hubUrl, token) {
             existing.mcpServers = {};
         }
         const overrodeCli = !!(existing.mcpServers.gitnexus && 'command' in existing.mcpServers.gitnexus);
+        // Claude Code's `~/.claude.json` accepts `type: "http"` for
+        // remote HTTP MCP servers. This is the shape that
+        // `claude mcp add --transport http <url>` writes and the format
+        // documented in the official docs (e.g. Stripe + Notion remote
+        // examples). The MCP registry spec uses `"streamable-http"`
+        // internally, but the CLI config format uses the short `"http"`
+        // alias — commit c602f2e crossed the wires and used the registry
+        // value, which silently breaks on current Claude Code versions.
         existing.mcpServers.gitnexus = {
             type: 'http',
             url: mcpUrl,

package/dist/editors/cursor.js

@@ -11,8 +11,12 @@ import { readJsonFile, writeJsonFile } from '../utils.js';
 import { HUB_SKILLS } from '../content.js';
 import { computeFingerprint, getDeviceName } from '../fingerprint.js';
 function getMcpConfig(hubUrl, token) {
+    // Cursor's `~/.cursor/mcp.json` identifies remote HTTP servers by
+    // the presence of `url` — the docs at cursor.com/docs/context/mcp
+    // do NOT document a `type` field for remote entries, so we omit
+    // it rather than send a registry-shape value that Cursor may
+    // start validating later.
     return {
-        type: 'streamable-http',
         url: `${hubUrl}/mcp`,
         headers: {
             Authorization: `Bearer ${token}`,

package/dist/hooks-installer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-editor hook installers.
+ *
+ * Writes idempotent editor-specific hook config files that point at
+ * the shipped gitnexus-enterprise-hook.cjs script. Called from the
+ * `gnx connect` flow after the MCP config is written.
+ */
+export interface InstallOptions {
+    /** Defaults to os.homedir(). Injectable for tests. */
+    homeDir?: string;
+    /** Absolute path to the shipped hook script. */
+    hookScriptPath: string;
+}
+/**
+ * Install the Claude Code PreToolUse + PostToolUse hooks.
+ * Returns the absolute path to the written hooks.json.
+ */
+export declare function installClaudeCodeHook(opts: InstallOptions): Promise<string>;
+/**
+ * Install the Cursor beforeShellExecution hook.
+ * Returns the absolute path to the written hooks.json.
+ */
+export declare function installCursorHook(opts: InstallOptions): Promise<string>;
+/**
+ * Install the OpenCode plugin stub.
+ * Returns the absolute path to the written TypeScript file.
+ *
+ * The plugin is currently a stub — the actual tool.before / tool.after
+ * wiring delegating to gitnexus-enterprise-hook.cjs will be filled in
+ * when we have concrete users on OpenCode. For M4.2 we write the file
+ * so gnx connect reports success and the user has a template to extend.
+ */
+export declare function installOpenCodeHook(opts: InstallOptions): Promise<string>;

package/dist/hooks-installer.js

@@ -0,0 +1,114 @@
+/**
+ * Per-editor hook installers.
+ *
+ * Writes idempotent editor-specific hook config files that point at
+ * the shipped gitnexus-enterprise-hook.cjs script. Called from the
+ * `gnx connect` flow after the MCP config is written.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+function getHome(opts) {
+    return opts.homeDir ?? os.homedir();
+}
+async function writeJsonIdempotent(filePath, obj) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const body = JSON.stringify(obj, null, 2) + '\n';
+    await fs.writeFile(filePath, body);
+}
+/**
+ * Install the Claude Code PreToolUse + PostToolUse hooks.
+ * Returns the absolute path to the written hooks.json.
+ */
+export async function installClaudeCodeHook(opts) {
+    const home = getHome(opts);
+    const hooksDir = path.join(home, '.claude', 'plugins', 'gitnexus-enterprise', 'hooks');
+    const hooksJsonPath = path.join(hooksDir, 'hooks.json');
+    // Double-quote the absolute path so shell splitting doesn't break
+    // when the install dir contains a space (e.g. Windows profiles at
+    // `C:\Users\John Doe\...`). The hook spec is a shell-style command
+    // string, not an argv array, so quoting is the only knob available.
+    const quotedScriptPath = `"${opts.hookScriptPath}"`;
+    const config = {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: 'Grep|Glob|Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: `node ${quotedScriptPath}`,
+                            timeout: 5,
+                        },
+                    ],
+                },
+            ],
+            PostToolUse: [
+                {
+                    matcher: 'Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: `node ${quotedScriptPath}`,
+                            timeout: 5,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    await writeJsonIdempotent(hooksJsonPath, config);
+    return hooksJsonPath;
+}
+/**
+ * Install the Cursor beforeShellExecution hook.
+ * Returns the absolute path to the written hooks.json.
+ */
+export async function installCursorHook(opts) {
+    const home = getHome(opts);
+    const hooksJsonPath = path.join(home, '.cursor', 'hooks.json');
+    // Same shell-quoting rationale as installClaudeCodeHook — the
+    // command is a shell string, not argv, so the absolute path must
+    // be quoted to survive spaces.
+    const config = {
+        beforeShellExecution: {
+            command: `node "${opts.hookScriptPath}"`,
+            timeout: 5000,
+        },
+    };
+    await writeJsonIdempotent(hooksJsonPath, config);
+    return hooksJsonPath;
+}
+/**
+ * Install the OpenCode plugin stub.
+ * Returns the absolute path to the written TypeScript file.
+ *
+ * The plugin is currently a stub — the actual tool.before / tool.after
+ * wiring delegating to gitnexus-enterprise-hook.cjs will be filled in
+ * when we have concrete users on OpenCode. For M4.2 we write the file
+ * so gnx connect reports success and the user has a template to extend.
+ */
+export async function installOpenCodeHook(opts) {
+    const home = getHome(opts);
+    const pluginDir = path.join(home, '.opencode', 'plugin');
+    const pluginPath = path.join(pluginDir, 'gitnexus-enterprise.ts');
+    const content = `// GitNexus Enterprise OpenCode plugin
+// Stub — delegates to gitnexus-enterprise-hook.cjs via child process.
+// Hook script: ${opts.hookScriptPath}
+
+export default {
+  async toolBefore(ctx: { tool: string }) {
+    if (!['Grep', 'Glob', 'Bash'].includes(ctx.tool)) return;
+    // TODO: spawn gitnexus-enterprise-hook.cjs with the tool context on stdin
+    //       and forward additionalContext from stdout.
+  },
+  async toolAfter(ctx: { tool: string }) {
+    if (ctx.tool !== 'Bash') return;
+    // TODO: spawn gitnexus-enterprise-hook.cjs for PostToolUse staleness check
+  },
+};
+`;
+    await fs.mkdir(pluginDir, { recursive: true });
+    await fs.writeFile(pluginPath, content);
+    return pluginPath;
+}