@duytransipher/gitnexus 1.4.6-sipher.0

package/dist/storage/repo-manager.js

@@ -0,0 +1,299 @@
+/**
+ * Repository Manager
+ *
+ * Manages GitNexus index storage in .gitnexus/ at repo root.
+ * Also maintains a global registry at ~/.gitnexus/registry.json
+ * so the MCP server can discover indexed repos from any cwd.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+const GITNEXUS_DIR = '.gitnexus';
+// ─── Local Storage Helpers ─────────────────────────────────────────────
+/**
+ * Get the .gitnexus storage path for a repository
+ */
+export const getStoragePath = (repoPath) => {
+    return path.join(path.resolve(repoPath), GITNEXUS_DIR);
+};
+/**
+ * Get paths to key storage files
+ */
+export const getStoragePaths = (repoPath) => {
+    const storagePath = getStoragePath(repoPath);
+    return {
+        storagePath,
+        lbugPath: path.join(storagePath, 'lbug'),
+        metaPath: path.join(storagePath, 'meta.json'),
+    };
+};
+/**
+ * Check whether a KuzuDB index exists in the given storage path.
+ * Non-destructive — safe to call from status commands.
+ */
+export const hasKuzuIndex = async (storagePath) => {
+    try {
+        await fs.stat(path.join(storagePath, 'kuzu'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Clean up stale KuzuDB files after migration to LadybugDB.
+ *
+ * Returns:
+ *   found        — true if .gitnexus/kuzu existed and was deleted
+ *   needsReindex — true if kuzu existed but lbug does not (re-analyze required)
+ *
+ * Callers own the user-facing messaging; this function only deletes files.
+ */
+export const cleanupOldKuzuFiles = async (storagePath) => {
+    const oldPath = path.join(storagePath, 'kuzu');
+    const newPath = path.join(storagePath, 'lbug');
+    try {
+        await fs.stat(oldPath);
+        // Old kuzu file/dir exists — determine if lbug is already present
+        let needsReindex = false;
+        try {
+            await fs.stat(newPath);
+        }
+        catch {
+            needsReindex = true;
+        }
+        // Delete kuzu database file and its sidecars (.wal, .lock)
+        for (const suffix of ['', '.wal', '.lock']) {
+            try {
+                await fs.unlink(oldPath + suffix);
+            }
+            catch { }
+        }
+        // Also handle the case where kuzu was stored as a directory
+        try {
+            await fs.rm(oldPath, { recursive: true, force: true });
+        }
+        catch { }
+        return { found: true, needsReindex };
+    }
+    catch {
+        // Old path doesn't exist — nothing to do
+        return { found: false, needsReindex: false };
+    }
+};
+/**
+ * Load metadata from an indexed repo
+ */
+export const loadMeta = async (storagePath) => {
+    try {
+        const metaPath = path.join(storagePath, 'meta.json');
+        const raw = await fs.readFile(metaPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Save metadata to storage
+ */
+export const saveMeta = async (storagePath, meta) => {
+    await fs.mkdir(storagePath, { recursive: true });
+    const metaPath = path.join(storagePath, 'meta.json');
+    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+};
+/**
+ * Check if a path has a GitNexus index
+ */
+export const hasIndex = async (repoPath) => {
+    const { metaPath } = getStoragePaths(repoPath);
+    try {
+        await fs.access(metaPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Load an indexed repo from a path
+ */
+export const loadRepo = async (repoPath) => {
+    const paths = getStoragePaths(repoPath);
+    const meta = await loadMeta(paths.storagePath);
+    if (!meta)
+        return null;
+    return {
+        repoPath: path.resolve(repoPath),
+        ...paths,
+        meta,
+    };
+};
+/**
+ * Find .gitnexus by walking up from a starting path
+ */
+export const findRepo = async (startPath) => {
+    let current = path.resolve(startPath);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        const repo = await loadRepo(current);
+        if (repo)
+            return repo;
+        current = path.dirname(current);
+    }
+    return null;
+};
+/**
+ * Add .gitnexus to .gitignore if not already present
+ */
+export const addToGitignore = async (repoPath) => {
+    const gitignorePath = path.join(repoPath, '.gitignore');
+    try {
+        const content = await fs.readFile(gitignorePath, 'utf-8');
+        if (content.includes(GITNEXUS_DIR))
+            return;
+        const newContent = content.endsWith('\n')
+            ? `${content}${GITNEXUS_DIR}\n`
+            : `${content}\n${GITNEXUS_DIR}\n`;
+        await fs.writeFile(gitignorePath, newContent, 'utf-8');
+    }
+    catch {
+        // .gitignore doesn't exist, create it
+        await fs.writeFile(gitignorePath, `${GITNEXUS_DIR}\n`, 'utf-8');
+    }
+};
+// ─── Global Registry (~/.gitnexus/registry.json) ───────────────────────
+/**
+ * Get the path to the global GitNexus directory
+ */
+export const getGlobalDir = () => {
+    return path.join(os.homedir(), '.gitnexus');
+};
+/**
+ * Get the path to the global registry file
+ */
+export const getGlobalRegistryPath = () => {
+    return path.join(getGlobalDir(), 'registry.json');
+};
+/**
+ * Read the global registry. Returns empty array if not found.
+ */
+export const readRegistry = async () => {
+    try {
+        const raw = await fs.readFile(getGlobalRegistryPath(), 'utf-8');
+        const data = JSON.parse(raw);
+        return Array.isArray(data) ? data : [];
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Write the global registry to disk
+ */
+const writeRegistry = async (entries) => {
+    const dir = getGlobalDir();
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(getGlobalRegistryPath(), JSON.stringify(entries, null, 2), 'utf-8');
+};
+/**
+ * Register (add or update) a repo in the global registry.
+ * Called after `gitnexus analyze` completes.
+ */
+export const registerRepo = async (repoPath, meta) => {
+    const resolved = path.resolve(repoPath);
+    const name = path.basename(resolved);
+    const { storagePath } = getStoragePaths(resolved);
+    const entries = await readRegistry();
+    const existing = entries.findIndex((e) => {
+        const a = path.resolve(e.path);
+        const b = resolved;
+        return process.platform === 'win32'
+            ? a.toLowerCase() === b.toLowerCase()
+            : a === b;
+    });
+    const entry = {
+        name,
+        path: resolved,
+        storagePath,
+        indexedAt: meta.indexedAt,
+        lastCommit: meta.lastCommit,
+        stats: meta.stats,
+    };
+    if (existing >= 0) {
+        entries[existing] = entry;
+    }
+    else {
+        entries.push(entry);
+    }
+    await writeRegistry(entries);
+};
+/**
+ * Remove a repo from the global registry.
+ * Called after `gitnexus clean`.
+ */
+export const unregisterRepo = async (repoPath) => {
+    const resolved = path.resolve(repoPath);
+    const entries = await readRegistry();
+    const filtered = entries.filter((e) => path.resolve(e.path) !== resolved);
+    await writeRegistry(filtered);
+};
+/**
+ * List all registered repos from the global registry.
+ * Optionally validates that each entry's .gitnexus/ still exists.
+ */
+export const listRegisteredRepos = async (opts) => {
+    const entries = await readRegistry();
+    if (!opts?.validate)
+        return entries;
+    // Validate each entry still has a .gitnexus/ directory
+    const valid = [];
+    for (const entry of entries) {
+        try {
+            await fs.access(path.join(entry.storagePath, 'meta.json'));
+            valid.push(entry);
+        }
+        catch {
+            // Index no longer exists — skip
+        }
+    }
+    // If we pruned any entries, save the cleaned registry
+    if (valid.length !== entries.length) {
+        await writeRegistry(valid);
+    }
+    return valid;
+};
+/**
+ * Get the path to the global CLI config file
+ */
+export const getGlobalConfigPath = () => {
+    return path.join(getGlobalDir(), 'config.json');
+};
+/**
+ * Load CLI config from ~/.gitnexus/config.json
+ */
+export const loadCLIConfig = async () => {
+    try {
+        const raw = await fs.readFile(getGlobalConfigPath(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * Save CLI config to ~/.gitnexus/config.json
+ */
+export const saveCLIConfig = async (config) => {
+    const dir = getGlobalDir();
+    await fs.mkdir(dir, { recursive: true });
+    const configPath = getGlobalConfigPath();
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    // Restrict file permissions on Unix (config may contain API keys)
+    if (process.platform !== 'win32') {
+        try {
+            await fs.chmod(configPath, 0o600);
+        }
+        catch { /* best-effort */ }
+    }
+};

package/dist/types/pipeline.d.ts

@@ -0,0 +1,32 @@
+import { GraphNode, GraphRelationship, KnowledgeGraph } from '../core/graph/types.js';
+import { CommunityDetectionResult } from '../core/ingestion/community-processor.js';
+import { ProcessDetectionResult } from '../core/ingestion/process-processor.js';
+export type PipelinePhase = 'idle' | 'extracting' | 'structure' | 'parsing' | 'imports' | 'calls' | 'heritage' | 'communities' | 'processes' | 'enriching' | 'complete' | 'error';
+export interface PipelineProgress {
+    phase: PipelinePhase;
+    percent: number;
+    message: string;
+    detail?: string;
+    stats?: {
+        filesProcessed: number;
+        totalFiles: number;
+        nodesCreated: number;
+    };
+}
+export interface PipelineResult {
+    graph: KnowledgeGraph;
+    /** Absolute path to the repo root — used for lazy file reads during LadybugDB loading */
+    repoPath: string;
+    /** Total files scanned (for stats) */
+    totalFileCount: number;
+    communityResult?: CommunityDetectionResult;
+    processResult?: ProcessDetectionResult;
+}
+export interface SerializablePipelineResult {
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    repoPath: string;
+    totalFileCount: number;
+}
+export declare const serializePipelineResult: (result: PipelineResult) => SerializablePipelineResult;
+export declare const deserializePipelineResult: (serialized: SerializablePipelineResult, createGraph: () => KnowledgeGraph) => PipelineResult;

package/dist/types/pipeline.js

@@ -0,0 +1,18 @@
+// Helper to convert PipelineResult to serializable format
+export const serializePipelineResult = (result) => ({
+    nodes: [...result.graph.iterNodes()],
+    relationships: [...result.graph.iterRelationships()],
+    repoPath: result.repoPath,
+    totalFileCount: result.totalFileCount,
+});
+// Helper to reconstruct from serializable format (used in main thread)
+export const deserializePipelineResult = (serialized, createGraph) => {
+    const graph = createGraph();
+    serialized.nodes.forEach(node => graph.addNode(node));
+    serialized.relationships.forEach(rel => graph.addRelationship(rel));
+    return {
+        graph,
+        repoPath: serialized.repoPath,
+        totalFileCount: serialized.totalFileCount,
+    };
+};

package/dist/unreal/bridge.d.ts

@@ -0,0 +1,4 @@
+import type { ExpandBlueprintChainResult, FindNativeBlueprintReferencesResult, NativeFunctionTarget, SyncUnrealAssetManifestResult, UnrealBlueprintCandidate, UnrealConfig } from './types.js';
+export declare function syncUnrealAssetManifest(storagePath: string, config: UnrealConfig): Promise<SyncUnrealAssetManifestResult>;
+export declare function findNativeBlueprintReferences(storagePath: string, config: UnrealConfig, target: NativeFunctionTarget, candidateAssets: UnrealBlueprintCandidate[], manifestPath?: string): Promise<FindNativeBlueprintReferencesResult>;
+export declare function expandBlueprintChain(storagePath: string, config: UnrealConfig, assetPath: string, chainAnchorId: string, direction: 'upstream' | 'downstream', maxDepth: number): Promise<ExpandBlueprintChainResult>;

package/dist/unreal/bridge.js

@@ -0,0 +1,113 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { ensureUnrealStorage, saveUnrealAssetManifest } from './config.js';
+const execFileAsync = promisify(execFile);
+function buildBaseArgs(config, operation, outputPath) {
+    return [
+        config.project_path,
+        `-run=${config.commandlet || 'GitNexusBlueprintAnalyzer'}`,
+        `-Operation=${operation}`,
+        `-OutputJson=${outputPath}`,
+        '-unattended',
+        '-nop4',
+        '-nosplash',
+        '-nullrhi',
+        ...(config.extra_args || []),
+    ];
+}
+function requestPaths(paths) {
+    const requestId = randomUUID();
+    return {
+        requestPath: path.join(paths.requests_dir, `${requestId}.json`),
+        outputPath: path.join(paths.outputs_dir, `${requestId}.json`),
+    };
+}
+async function runCommand(config, operation, args) {
+    return execFileAsync(config.editor_cmd, args, {
+        cwd: config.working_directory,
+        timeout: config.timeout_ms || 300000,
+        windowsHide: true,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+}
+async function readOutputJson(outputPath, stdout) {
+    try {
+        const raw = await fs.readFile(outputPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return JSON.parse(stdout);
+    }
+}
+export async function syncUnrealAssetManifest(storagePath, config) {
+    const unrealPaths = await ensureUnrealStorage(storagePath);
+    const { outputPath } = requestPaths(unrealPaths);
+    const args = buildBaseArgs(config, 'SyncAssets', outputPath);
+    try {
+        const { stdout } = await runCommand(config, 'SyncAssets', args);
+        const response = await readOutputJson(outputPath, stdout);
+        const manifestPath = await saveUnrealAssetManifest(storagePath, response.manifest);
+        return {
+            status: 'success',
+            manifest_path: manifestPath,
+            asset_count: response.manifest.assets.length,
+            generated_at: response.manifest.generated_at,
+            warnings: response.warnings || [],
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function findNativeBlueprintReferences(storagePath, config, target, candidateAssets, manifestPath) {
+    const unrealPaths = await ensureUnrealStorage(storagePath);
+    const { requestPath, outputPath } = requestPaths(unrealPaths);
+    await fs.writeFile(requestPath, JSON.stringify({ candidate_assets: candidateAssets }, null, 2), 'utf-8');
+    const args = [
+        ...buildBaseArgs(config, 'FindNativeBlueprintReferences', outputPath),
+        `-TargetSymbolKey=${target.symbol_key}`,
+        `-TargetFunction=${target.symbol_name}`,
+        ...(target.class_name ? [`-TargetClass=${target.class_name}`] : []),
+        `-CandidatesJson=${requestPath}`,
+    ];
+    const { stdout } = await runCommand(config, 'FindNativeBlueprintReferences', args);
+    const response = await readOutputJson(outputPath, stdout);
+    return {
+        target_function: {
+            ...target,
+            ...(response.target_function || {}),
+        },
+        candidates_scanned: response.candidates_scanned ?? candidateAssets.length,
+        candidate_assets: candidateAssets,
+        confirmed_references: response.confirmed_references || [],
+        manifest_path: manifestPath,
+        warnings: response.warnings || [],
+    };
+}
+export async function expandBlueprintChain(storagePath, config, assetPath, chainAnchorId, direction, maxDepth) {
+    const unrealPaths = await ensureUnrealStorage(storagePath);
+    const { outputPath } = requestPaths(unrealPaths);
+    const args = [
+        ...buildBaseArgs(config, 'ExpandBlueprintChain', outputPath),
+        `-AssetPath=${assetPath}`,
+        `-ChainAnchorId=${chainAnchorId}`,
+        `-Direction=${direction}`,
+        `-MaxDepth=${maxDepth}`,
+    ];
+    const { stdout } = await runCommand(config, 'ExpandBlueprintChain', args);
+    const response = await readOutputJson(outputPath, stdout);
+    return {
+        asset_path: assetPath,
+        chain_anchor_id: chainAnchorId,
+        direction,
+        max_depth: maxDepth,
+        nodes: response.nodes || [],
+        warnings: response.warnings || [],
+    };
+}

package/dist/unreal/config.d.ts

@@ -0,0 +1,6 @@
+import type { UnrealAssetManifest, UnrealConfig, UnrealStoragePaths } from './types.js';
+export declare function getUnrealStoragePaths(storagePath: string): UnrealStoragePaths;
+export declare function ensureUnrealStorage(storagePath: string): Promise<UnrealStoragePaths>;
+export declare function loadUnrealConfig(storagePath: string): Promise<UnrealConfig | null>;
+export declare function loadUnrealAssetManifest(storagePath: string): Promise<UnrealAssetManifest | null>;
+export declare function saveUnrealAssetManifest(storagePath: string, manifest: UnrealAssetManifest): Promise<string>;

package/dist/unreal/config.js

@@ -0,0 +1,55 @@
+import fs from 'fs/promises';
+import path from 'path';
+export function getUnrealStoragePaths(storagePath) {
+    const rootDir = path.join(storagePath, 'unreal');
+    return {
+        root_dir: rootDir,
+        config_path: path.join(rootDir, 'config.json'),
+        manifest_path: path.join(rootDir, 'asset-manifest.json'),
+        requests_dir: path.join(rootDir, 'requests'),
+        outputs_dir: path.join(rootDir, 'outputs'),
+    };
+}
+export async function ensureUnrealStorage(storagePath) {
+    const paths = getUnrealStoragePaths(storagePath);
+    await fs.mkdir(paths.requests_dir, { recursive: true });
+    await fs.mkdir(paths.outputs_dir, { recursive: true });
+    return paths;
+}
+export async function loadUnrealConfig(storagePath) {
+    try {
+        const paths = getUnrealStoragePaths(storagePath);
+        const raw = await fs.readFile(paths.config_path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.editor_cmd || !parsed.project_path) {
+            return null;
+        }
+        return {
+            commandlet: 'GitNexusBlueprintAnalyzer',
+            timeout_ms: 300000,
+            ...parsed,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadUnrealAssetManifest(storagePath) {
+    try {
+        const paths = getUnrealStoragePaths(storagePath);
+        const raw = await fs.readFile(paths.manifest_path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.assets)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveUnrealAssetManifest(storagePath, manifest) {
+    const paths = await ensureUnrealStorage(storagePath);
+    await fs.writeFile(paths.manifest_path, JSON.stringify(manifest, null, 2), 'utf-8');
+    return paths.manifest_path;
+}

package/dist/unreal/types.d.ts

@@ -0,0 +1,105 @@
+export interface UnrealAssetManifestAsset {
+    asset_path: string;
+    generated_class?: string;
+    parent_class?: string;
+    native_parents?: string[];
+    native_function_refs?: string[];
+    dependencies?: string[];
+}
+export interface UnrealAssetManifest {
+    version: number;
+    generated_at: string;
+    project_path?: string;
+    assets: UnrealAssetManifestAsset[];
+}
+export interface UnrealConfig {
+    editor_cmd: string;
+    project_path: string;
+    commandlet?: string;
+    timeout_ms?: number;
+    working_directory?: string;
+    extra_args?: string[];
+}
+export interface UnrealStoragePaths {
+    root_dir: string;
+    config_path: string;
+    manifest_path: string;
+    requests_dir: string;
+    outputs_dir: string;
+}
+export interface NativeFunctionTarget {
+    symbol_id: string;
+    symbol_name: string;
+    symbol_type: string;
+    symbol_key: string;
+    qualified_name: string;
+    class_name?: string;
+    file_path?: string;
+    start_line?: number;
+}
+export interface UnrealBlueprintCandidate {
+    asset_path: string;
+    generated_class?: string;
+    parent_class?: string;
+    reason: 'native_parent' | 'native_function_ref' | 'dependency' | 'manifest';
+}
+export interface UnrealConfirmedReference {
+    asset_path: string;
+    graph_name?: string;
+    node_kind: string;
+    node_title?: string;
+    blueprint_owner_function?: string;
+    chain_anchor_id: string;
+    source: 'editor_confirmed';
+}
+export interface UnrealChainNode {
+    node_id: string;
+    graph_name?: string;
+    node_kind: string;
+    node_title?: string;
+    depth: number;
+}
+export interface SyncUnrealAssetManifestResult {
+    status: 'success' | 'error';
+    manifest_path?: string;
+    asset_count?: number;
+    generated_at?: string;
+    warnings?: string[];
+    error?: string;
+}
+export interface FindNativeBlueprintReferencesResult {
+    target_function: NativeFunctionTarget;
+    candidates_scanned: number;
+    candidate_assets: UnrealBlueprintCandidate[];
+    confirmed_references: UnrealConfirmedReference[];
+    manifest_path?: string;
+    manifest_refreshed?: boolean;
+    warnings?: string[];
+}
+export interface ExpandBlueprintChainResult {
+    asset_path: string;
+    chain_anchor_id: string;
+    direction: 'upstream' | 'downstream';
+    max_depth: number;
+    nodes: UnrealChainNode[];
+    warnings?: string[];
+}
+export interface DerivedBlueprintResult {
+    class_name: string;
+    manifest_path: string;
+    blueprints: UnrealBlueprintCandidate[];
+}
+export interface UnrealAnalyzerSyncResponse {
+    manifest: UnrealAssetManifest;
+    warnings?: string[];
+}
+export interface UnrealAnalyzerFindRefsResponse {
+    target_function?: Partial<NativeFunctionTarget>;
+    candidates_scanned?: number;
+    confirmed_references?: UnrealConfirmedReference[];
+    warnings?: string[];
+}
+export interface UnrealAnalyzerExpandChainResponse {
+    nodes?: UnrealChainNode[];
+    warnings?: string[];
+}

package/dist/unreal/types.js

@@ -0,0 +1 @@
+export {};