@veewo/gitnexus 1.3.7 → 1.3.9

package/README.md

@@ -70,7 +70,7 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 ### Claude Code (full support — MCP + skills + hooks)
 
 ```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+claude mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ### Cursor / Windsurf
@@ -82,7 +82,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "gitnexus": {
       "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "args": ["-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -97,7 +97,7 @@ Add to `~/.config/opencode/opencode.json`:
   "mcp": {
     "gitnexus": {
       "type": "local",
-      "command": ["npx", "-y", "gitnexus@latest", "mcp"]
+      "command": ["npx", "-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -106,7 +106,7 @@ Add to `~/.config/opencode/opencode.json`:
 ### Codex
 
 ```bash
-codex mcp add gitnexus -- npx -y gitnexus@latest mcp
+codex mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ## How It Works
@@ -176,12 +176,17 @@ gitnexus clean                   # Delete index for current repo
 gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+gitnexus unity-bindings <symbol> --target-path <path> [--json]  # Experimental Unity C# <-> prefab/scene/asset cross-reference
+gitnexus context <symbol> --unity-resources on                   # Include graph-native Unity resource data (opt-in)
+gitnexus query <symbol> --unity-resources on                     # Enrich query symbol hits with Unity resource data (opt-in)
 gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile quick --target-path ../benchmarks/fixtures/unity-mini
 gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile full --target-path ../benchmarks/fixtures/unity-mini
 ```
 
 For scoped indexing, `analyze` logs scope overlap dedupe counts and any normalized path collisions to help diagnose multi-directory merge safety.
 
+Unity resource retrieval is opt-in on `query/context` via `unity_resources: off|on|auto` (default: `off`). Use `--unity-resources on` when you need `resourceBindings`, `serializedFields`, `resolvedReferences`, and `unityDiagnostics` in output.
+
 ## Unity Benchmark
 
 Run reproducible Unity/C# accuracy and regression checks:

package/dist/benchmark/runner.test.js

@@ -18,7 +18,7 @@ test('resolveBenchmarkRepoName falls back to repo alias', () => {
 });
 test('resolveBenchmarkRepoName uses target basename when no repo input exists', () => {
     const resolved = resolveBenchmarkRepoName({
-        targetPath: '/Volumes/Shuttle/unity-projects/neonspark',
+        targetPath: '/tmp/unity-projects/neonspark',
     });
     assert.equal(resolved, 'neonspark');
 });

package/dist/benchmark/u2-e2e/analyze-parser.d.ts

@@ -0,0 +1,22 @@
+export interface AnalyzeSummary {
+    totalSec: number;
+    kuzuSec: number;
+    ftsSec: number;
+    nodes?: number;
+    edges?: number;
+}
+export interface EstimateVerdict {
+    actualSec: number;
+    lower: number;
+    upper: number;
+    inRange: boolean;
+    status: 'below-range' | 'in-range' | 'above-range';
+    deltaSec: number;
+}
+interface EstimateRange {
+    lower: number;
+    upper: number;
+}
+export declare function parseAnalyzeSummary(logPath: string): Promise<AnalyzeSummary>;
+export declare function compareEstimate(actualSec: number, range: EstimateRange): EstimateVerdict;
+export {};

package/dist/benchmark/u2-e2e/analyze-parser.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+function round1(value) {
+    return Number(value.toFixed(1));
+}
+function parseNumber(raw) {
+    if (!raw)
+        return 0;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : 0;
+}
+function candidatePaths(inputPath) {
+    if (path.isAbsolute(inputPath)) {
+        return [inputPath];
+    }
+    return [
+        path.resolve(process.cwd(), inputPath),
+        path.resolve(process.cwd(), 'src/benchmark/u2-e2e', inputPath),
+        path.resolve(process.cwd(), 'gitnexus/src/benchmark/u2-e2e', inputPath),
+        path.resolve(process.cwd(), '..', inputPath),
+    ];
+}
+export async function parseAnalyzeSummary(logPath) {
+    let raw = '';
+    const tried = [];
+    for (const candidate of candidatePaths(logPath)) {
+        tried.push(candidate);
+        try {
+            raw = await fs.readFile(candidate, 'utf-8');
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    if (!raw) {
+        throw new Error(`Analyze log not found: ${logPath}. Tried: ${tried.join(', ')}`);
+    }
+    const totalMatch = raw.match(/Repository indexed successfully \(([\d.]+)s\)/i);
+    const kuzuFtsMatch = raw.match(/KuzuDB\s+([\d.]+)s\s*\|\s*FTS\s+([\d.]+)s/i);
+    const realMatch = raw.match(/^real\s+([\d.]+)$/m);
+    const nodesMatch = raw.match(/\bnodes?\D+(\d+)/i);
+    const edgesMatch = raw.match(/\bedges?\D+(\d+)/i);
+    const totalSec = parseNumber(totalMatch?.[1]) || parseNumber(realMatch?.[1]);
+    const kuzuSec = parseNumber(kuzuFtsMatch?.[1]);
+    const ftsSec = parseNumber(kuzuFtsMatch?.[2]);
+    if (!totalSec) {
+        throw new Error(`Failed to parse total duration from analyze log: ${logPath}`);
+    }
+    return {
+        totalSec: round1(totalSec),
+        kuzuSec: round1(kuzuSec),
+        ftsSec: round1(ftsSec),
+        nodes: nodesMatch ? parseNumber(nodesMatch[1]) : undefined,
+        edges: edgesMatch ? parseNumber(edgesMatch[1]) : undefined,
+    };
+}
+export function compareEstimate(actualSec, range) {
+    if (actualSec < range.lower) {
+        return {
+            actualSec: round1(actualSec),
+            lower: range.lower,
+            upper: range.upper,
+            inRange: false,
+            status: 'below-range',
+            deltaSec: round1(actualSec - range.lower),
+        };
+    }
+    if (actualSec > range.upper) {
+        return {
+            actualSec: round1(actualSec),
+            lower: range.lower,
+            upper: range.upper,
+            inRange: false,
+            status: 'above-range',
+            deltaSec: round1(actualSec - range.upper),
+        };
+    }
+    return {
+        actualSec: round1(actualSec),
+        lower: range.lower,
+        upper: range.upper,
+        inRange: true,
+        status: 'in-range',
+        deltaSec: 0,
+    };
+}

package/dist/benchmark/u2-e2e/analyze-parser.test.d.ts

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

package/dist/benchmark/u2-e2e/analyze-parser.test.js

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseAnalyzeSummary, compareEstimate } from './analyze-parser.js';
+test('parseAnalyzeSummary extracts totalSec and kuzu/fts sec', async () => {
+    const summary = await parseAnalyzeSummary('__fixtures__/analyze.log');
+    assert.equal(summary.totalSec, 114.8);
+    assert.equal(summary.kuzuSec, 73.5);
+    assert.equal(summary.ftsSec, 19.6);
+});
+test('compareEstimate marks in-range status', () => {
+    const verdict = compareEstimate(500, { lower: 322.6, upper: 540.1 });
+    assert.equal(verdict.status, 'in-range');
+});

package/dist/benchmark/u2-e2e/characterlist-assetref.d.ts

@@ -0,0 +1,19 @@
+export interface AssetRefPathInstance {
+    fieldName: string;
+    relativePath: string;
+    isEmpty: boolean;
+    isSprite: boolean;
+}
+export interface CharacterListAssetRefSpriteSummary {
+    extractedAssetRefInstances: number;
+    nonEmptyAssetRefInstances: number;
+    spriteAssetRefInstances: number;
+    spriteRatioInNonEmpty: number | null;
+    uniqueSpriteAssets: number;
+    byFieldAllNonEmpty: Record<string, number>;
+    byFieldSpriteOnly: Record<string, number>;
+    topSpritePaths: Record<string, number>;
+}
+export declare function isSpriteRelativePath(input: string): boolean;
+export declare function extractAssetRefPathInstances(bindings: Array<Record<string, any>>): AssetRefPathInstance[];
+export declare function summarizeCharacterListAssetRefSprite(bindings: Array<Record<string, any>>): CharacterListAssetRefSpriteSummary;

package/dist/benchmark/u2-e2e/characterlist-assetref.js

@@ -0,0 +1,80 @@
+function unquote(input) {
+    return input.replace(/^"|"$/g, '');
+}
+export function isSpriteRelativePath(input) {
+    const value = input.trim().toLowerCase();
+    if (!value)
+        return false;
+    if (value.includes('/sprites/'))
+        return true;
+    return /\.(png|jpg|jpeg|tga|psd|webp|spriteatlas|spriteatlasv2)$/.test(value);
+}
+function countBy(rows, keyFn) {
+    const counts = new Map();
+    for (const row of rows) {
+        const key = keyFn(row);
+        counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return Object.fromEntries([...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+}
+export function extractAssetRefPathInstances(bindings) {
+    const rows = [];
+    for (const binding of bindings) {
+        const structuredRows = Array.isArray(binding?.assetRefPaths) ? binding.assetRefPaths : [];
+        if (structuredRows.length > 0) {
+            for (const structured of structuredRows) {
+                const relativePath = String(structured.relativePath || '');
+                rows.push({
+                    fieldName: String(structured.fieldName || 'unknown'),
+                    relativePath,
+                    isEmpty: Boolean(structured.isEmpty ?? relativePath.length === 0),
+                    isSprite: Boolean(structured.isSprite ?? isSpriteRelativePath(relativePath)),
+                });
+            }
+            continue;
+        }
+        const scalarFields = Array.isArray(binding?.serializedFields?.scalarFields)
+            ? binding.serializedFields.scalarFields
+            : [];
+        for (const scalar of scalarFields) {
+            const text = String(scalar?.value || '');
+            if (!text)
+                continue;
+            const lines = text.split(/\r?\n/);
+            let currentFieldName = 'unknown';
+            for (const line of lines) {
+                const fieldMatch = line.match(/^\s*([A-Za-z0-9_]*Ref):\s*$/);
+                if (fieldMatch) {
+                    currentFieldName = fieldMatch[1];
+                    continue;
+                }
+                const relativePathMatch = line.match(/^\s*_relativePath:\s*(.*)$/);
+                if (!relativePathMatch)
+                    continue;
+                const relativePath = unquote((relativePathMatch[1] || '').trim());
+                rows.push({
+                    fieldName: currentFieldName,
+                    relativePath,
+                    isEmpty: relativePath.length === 0,
+                    isSprite: isSpriteRelativePath(relativePath),
+                });
+            }
+        }
+    }
+    return rows;
+}
+export function summarizeCharacterListAssetRefSprite(bindings) {
+    const extracted = extractAssetRefPathInstances(bindings);
+    const nonEmpty = extracted.filter((row) => !row.isEmpty);
+    const spriteOnly = nonEmpty.filter((row) => row.isSprite);
+    return {
+        extractedAssetRefInstances: extracted.length,
+        nonEmptyAssetRefInstances: nonEmpty.length,
+        spriteAssetRefInstances: spriteOnly.length,
+        spriteRatioInNonEmpty: nonEmpty.length === 0 ? null : Number((spriteOnly.length / nonEmpty.length).toFixed(4)),
+        uniqueSpriteAssets: new Set(spriteOnly.map((row) => row.relativePath)).size,
+        byFieldAllNonEmpty: countBy(nonEmpty, (row) => row.fieldName),
+        byFieldSpriteOnly: countBy(spriteOnly, (row) => row.fieldName),
+        topSpritePaths: countBy(spriteOnly, (row) => row.relativePath),
+    };
+}

package/dist/benchmark/u2-e2e/characterlist-assetref.test.d.ts

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

package/dist/benchmark/u2-e2e/characterlist-assetref.test.js

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { extractAssetRefPathInstances, summarizeCharacterListAssetRefSprite, } from './characterlist-assetref.js';
+const SAMPLE_BINDING = {
+    resourcePath: 'Assets/NEON/DataAssets/CharacterList.asset',
+    serializedFields: {
+        scalarFields: [
+            {
+                name: 'Values',
+                value: `
+_Head_Ref:
+  _assetBundleName: char_head
+  _relativePath: Assets/NEON/Art/Sprites/UI/0_pixle/ui_character_head/hero_head_Nik.png
+_actorPrefabRef:
+  _assetBundleName: char_nik_actor
+  _relativePath: Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab
+_lockedSprite_Ref:
+  _assetBundleName: char_nik_portrait
+  _relativePath: Assets/NEON/Art/Sprites/UI/4K/new_UI_character_choose/heroes_pic/hero_pic_nik.png
+_activeSkillPowerUp_Ref:
+  _assetBundleName:
+  _relativePath:
+`,
+            },
+        ],
+    },
+};
+test('extractAssetRefPathInstances parses _relativePath rows and preserves field names', () => {
+    const rows = extractAssetRefPathInstances([SAMPLE_BINDING]);
+    assert.equal(rows.length, 4);
+    const byField = new Map(rows.map((row) => [row.fieldName, row]));
+    assert.equal(byField.get('_Head_Ref')?.relativePath, 'Assets/NEON/Art/Sprites/UI/0_pixle/ui_character_head/hero_head_Nik.png');
+    assert.equal(byField.get('_actorPrefabRef')?.relativePath, 'Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab');
+    assert.equal(byField.get('_lockedSprite_Ref')?.relativePath, 'Assets/NEON/Art/Sprites/UI/4K/new_UI_character_choose/heroes_pic/hero_pic_nik.png');
+    assert.equal(byField.get('_activeSkillPowerUp_Ref')?.relativePath, '');
+});
+test('summarizeCharacterListAssetRefSprite counts non-empty and sprite instances', () => {
+    const summary = summarizeCharacterListAssetRefSprite([SAMPLE_BINDING]);
+    assert.equal(summary.extractedAssetRefInstances, 4);
+    assert.equal(summary.nonEmptyAssetRefInstances, 3);
+    assert.equal(summary.spriteAssetRefInstances, 2);
+    assert.equal(summary.uniqueSpriteAssets, 2);
+    assert.equal(summary.spriteRatioInNonEmpty, 0.6667);
+});
+test('summarizeCharacterListAssetRefSprite field histogram keeps only sprite fields for sprite map', () => {
+    const summary = summarizeCharacterListAssetRefSprite([SAMPLE_BINDING]);
+    assert.equal(summary.byFieldAllNonEmpty._Head_Ref, 1);
+    assert.equal(summary.byFieldAllNonEmpty._actorPrefabRef, 1);
+    assert.equal(summary.byFieldAllNonEmpty._lockedSprite_Ref, 1);
+    assert.equal(summary.byFieldSpriteOnly._Head_Ref, 1);
+    assert.equal(summary.byFieldSpriteOnly._lockedSprite_Ref, 1);
+    assert.equal(summary.byFieldSpriteOnly._actorPrefabRef, undefined);
+});
+test('extractAssetRefPathInstances marks sprite with extension or /Sprites/ path', () => {
+    const rows = extractAssetRefPathInstances([
+        {
+            serializedFields: {
+                scalarFields: [
+                    {
+                        value: `
+_icon_Ref:
+  _relativePath: Assets/Texture/icon.webp
+_atlas_Ref:
+  _relativePath: Assets/Atlas/UI.spriteatlasv2
+_folderSprite_Ref:
+  _relativePath: Assets/NEON/Art/Sprites/UI/hero_avatar
+`,
+                    },
+                ],
+            },
+        },
+    ]);
+    const spriteOnly = rows.filter((row) => row.isSprite).map((row) => row.fieldName);
+    assert.deepEqual(spriteOnly, ['_icon_Ref', '_atlas_Ref', '_folderSprite_Ref']);
+});
+test('extractAssetRefPathInstances prefers structured assetRefPaths when provided', () => {
+    const rows = extractAssetRefPathInstances([
+        {
+            assetRefPaths: [
+                {
+                    fieldName: '_Head_Ref',
+                    relativePath: 'Assets/NEON/Art/Sprites/UI/head.png',
+                    isEmpty: false,
+                    isSprite: true,
+                },
+                {
+                    fieldName: '_actorPrefabRef',
+                    relativePath: 'Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab',
+                    isEmpty: false,
+                    isSprite: false,
+                },
+            ],
+            serializedFields: {
+                scalarFields: [
+                    {
+                        value: `
+_Head_Ref:
+  _relativePath: Assets/THIS/SHOULD/NOT/BE/USED.png
+`,
+                    },
+                ],
+            },
+        },
+    ]);
+    assert.equal(rows.length, 2);
+    assert.equal(rows[0]?.relativePath, 'Assets/NEON/Art/Sprites/UI/head.png');
+    assert.equal(rows[1]?.relativePath, 'Assets/ActorPrefab/Actor_Nik/V_Actor_Nik.prefab');
+});

package/dist/benchmark/u2-e2e/config.d.ts

@@ -0,0 +1,25 @@
+export interface E2EConfig {
+    runIdPrefix: string;
+    targetPath: string;
+    repoAliasPrefix: string;
+    scope: {
+        scriptPrefixes: string[];
+        resourcePrefixes: string[];
+    };
+    estimateRangeSec: {
+        lower: number;
+        upper: number;
+    };
+    symbolScenarios: SymbolScenario[];
+}
+export interface SymbolScenario {
+    symbol: string;
+    kind: 'component' | 'scriptableobject' | 'serializable-class' | 'partial-component';
+    objectives: string[];
+    contextFileHint?: string;
+    deepDivePlan: Array<{
+        tool: 'query' | 'context' | 'impact' | 'cypher';
+        input: Record<string, unknown>;
+    }>;
+}
+export declare function loadE2EConfig(configPath: string, env?: NodeJS.ProcessEnv): Promise<E2EConfig>;

package/dist/benchmark/u2-e2e/config.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+function candidatePaths(inputPath) {
+    if (path.isAbsolute(inputPath)) {
+        return [inputPath];
+    }
+    return [
+        path.resolve(process.cwd(), inputPath),
+        path.resolve(process.cwd(), '..', inputPath),
+    ];
+}
+async function readJsonFile(inputPath) {
+    const tried = [];
+    for (const filePath of candidatePaths(inputPath)) {
+        tried.push(filePath);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    throw new Error(`File not found: ${inputPath}. Tried: ${tried.join(', ')}`);
+}
+function parseEnvNumber(raw, envName) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`${envName} must be a finite number, got "${raw}"`);
+    }
+    return parsed;
+}
+function loadEnvOverrides(env) {
+    const runIdPrefix = env.GITNEXUS_U2_E2E_RUN_ID_PREFIX?.trim();
+    const targetPath = env.GITNEXUS_U2_E2E_TARGET_PATH?.trim();
+    const repoAliasPrefix = env.GITNEXUS_U2_E2E_REPO_ALIAS_PREFIX?.trim();
+    const symbolScenariosPath = env.GITNEXUS_U2_E2E_SYMBOL_SCENARIOS_PATH?.trim();
+    const estimateLowerSec = parseEnvNumber(env.GITNEXUS_U2_E2E_ESTIMATE_LOWER_SEC, 'GITNEXUS_U2_E2E_ESTIMATE_LOWER_SEC');
+    const estimateUpperSec = parseEnvNumber(env.GITNEXUS_U2_E2E_ESTIMATE_UPPER_SEC, 'GITNEXUS_U2_E2E_ESTIMATE_UPPER_SEC');
+    const hasLower = estimateLowerSec !== undefined;
+    const hasUpper = estimateUpperSec !== undefined;
+    if (hasLower !== hasUpper) {
+        throw new Error('GITNEXUS_U2_E2E_ESTIMATE_LOWER_SEC and GITNEXUS_U2_E2E_ESTIMATE_UPPER_SEC must be set together');
+    }
+    return {
+        ...(runIdPrefix ? { runIdPrefix } : {}),
+        ...(targetPath ? { targetPath } : {}),
+        ...(repoAliasPrefix ? { repoAliasPrefix } : {}),
+        ...(symbolScenariosPath ? { symbolScenariosPath } : {}),
+        ...(hasLower && hasUpper
+            ? {
+                estimateLowerSec: estimateLowerSec,
+                estimateUpperSec: estimateUpperSec,
+            }
+            : {}),
+    };
+}
+export async function loadE2EConfig(configPath, env = process.env) {
+    const raw = await readJsonFile(configPath);
+    const overrides = loadEnvOverrides(env);
+    const symbolScenariosPath = overrides.symbolScenariosPath || raw.symbolScenariosPath;
+    let symbolScenarios = raw.symbolScenarios || [];
+    if (symbolScenariosPath) {
+        symbolScenarios = await readJsonFile(symbolScenariosPath);
+    }
+    return {
+        runIdPrefix: overrides.runIdPrefix || raw.runIdPrefix,
+        targetPath: overrides.targetPath || raw.targetPath,
+        repoAliasPrefix: overrides.repoAliasPrefix || raw.repoAliasPrefix,
+        scope: raw.scope,
+        estimateRangeSec: overrides.estimateLowerSec !== undefined && overrides.estimateUpperSec !== undefined
+            ? {
+                lower: overrides.estimateLowerSec,
+                upper: overrides.estimateUpperSec,
+            }
+            : raw.estimateRangeSec,
+        symbolScenarios,
+    };
+}

package/dist/benchmark/u2-e2e/config.test.d.ts

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

package/dist/benchmark/u2-e2e/config.test.js

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { loadE2EConfig } from './config.js';
+test('loadE2EConfig reads estimate range and 5 symbol scenarios', async () => {
+    const config = await loadE2EConfig('benchmarks/u2-e2e/neonspark-full-u2-e2e.config.json');
+    assert.equal(config.estimateRangeSec.lower, 322.6);
+    assert.equal(config.estimateRangeSec.upper, 540.1);
+    assert.equal(config.symbolScenarios.length, 5);
+    assert.deepEqual(config.symbolScenarios.map((s) => s.symbol), ['MainUIManager', 'CoinPowerUp', 'GlobalDataAssets', 'AssetRef', 'PlayerActor']);
+});
+test('loadE2EConfig applies env overrides for real-repo gate', async () => {
+    const config = await loadE2EConfig('benchmarks/u2-e2e/neonspark-full-u2-e2e.config.json', {
+        GITNEXUS_U2_E2E_TARGET_PATH: '/tmp/unity-repo',
+        GITNEXUS_U2_E2E_RUN_ID_PREFIX: 'nightly-u3-real',
+        GITNEXUS_U2_E2E_REPO_ALIAS_PREFIX: 'neonspark-nightly',
+        GITNEXUS_U2_E2E_ESTIMATE_LOWER_SEC: '10.5',
+        GITNEXUS_U2_E2E_ESTIMATE_UPPER_SEC: '20.5',
+    });
+    assert.equal(config.targetPath, '/tmp/unity-repo');
+    assert.equal(config.runIdPrefix, 'nightly-u3-real');
+    assert.equal(config.repoAliasPrefix, 'neonspark-nightly');
+    assert.equal(config.estimateRangeSec.lower, 10.5);
+    assert.equal(config.estimateRangeSec.upper, 20.5);
+});
+test('loadE2EConfig rejects half-configured estimate override', async () => {
+    await assert.rejects(loadE2EConfig('benchmarks/u2-e2e/neonspark-full-u2-e2e.config.json', {
+        GITNEXUS_U2_E2E_ESTIMATE_LOWER_SEC: '10.5',
+    }), /must be set together/);
+});

package/dist/benchmark/u2-e2e/metrics.d.ts

@@ -0,0 +1,20 @@
+export interface StepMetric {
+    stepId: string;
+    tool: string;
+    durationMs: number;
+    inputChars: number;
+    outputChars: number;
+    inputTokensEst: number;
+    outputTokensEst: number;
+    totalTokensEst: number;
+}
+export interface DurationSummary {
+    count: number;
+    minMs: number;
+    maxMs: number;
+    meanMs: number;
+    medianMs: number;
+    spreadMs: number;
+}
+export declare function estimateTokens(text: string): number;
+export declare function summarizeDurations(values: number[]): DurationSummary;

package/dist/benchmark/u2-e2e/metrics.js

@@ -0,0 +1,34 @@
+function round1(value) {
+    return Number(value.toFixed(1));
+}
+export function estimateTokens(text) {
+    return Math.ceil((text || '').length / 4);
+}
+export function summarizeDurations(values) {
+    if (values.length === 0) {
+        return {
+            count: 0,
+            minMs: 0,
+            maxMs: 0,
+            meanMs: 0,
+            medianMs: 0,
+            spreadMs: 0,
+        };
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const mean = sorted.reduce((sum, value) => sum + value, 0) / sorted.length;
+    return {
+        count: sorted.length,
+        minMs: round1(min),
+        maxMs: round1(max),
+        meanMs: round1(mean),
+        medianMs: round1(median),
+        spreadMs: round1(max - min),
+    };
+}

package/dist/benchmark/u2-e2e/metrics.test.d.ts

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

package/dist/benchmark/u2-e2e/metrics.test.js

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { estimateTokens, summarizeDurations } from './metrics.js';
+test('estimateTokens uses chars-per-token heuristic', () => {
+    assert.equal(estimateTokens('1234'), 1);
+    assert.equal(estimateTokens('12345'), 2);
+});
+test('summarizeDurations computes median/min/max', () => {
+    const out = summarizeDurations([50, 100, 150]);
+    assert.equal(out.medianMs, 100);
+    assert.equal(out.minMs, 50);
+    assert.equal(out.maxMs, 150);
+});

package/dist/benchmark/u2-e2e/neonspark-full-e2e.d.ts

@@ -0,0 +1,33 @@
+export type E2EGateName = 'preflight' | 'build' | 'pipeline-profile' | 'analyze' | 'estimate-compare' | 'retrieval' | 'final-report';
+export interface E2ERunFailure {
+    status: 'failed';
+    runId: string;
+    reportDir: string;
+    completedGates: E2EGateName[];
+    failedGate: E2EGateName;
+    error: string;
+    gateOutputs: Partial<Record<E2EGateName, unknown>>;
+}
+export interface E2ERunSuccess {
+    status: 'passed';
+    runId: string;
+    reportDir: string;
+    completedGates: E2EGateName[];
+    gateOutputs: Partial<Record<E2EGateName, unknown>>;
+}
+export type E2ERunResult = E2ERunFailure | E2ERunSuccess;
+export interface RunE2EOptions {
+    runId?: string;
+    reportDir?: string;
+    gates?: Partial<Record<E2EGateName, () => Promise<unknown>>>;
+    writeCheckpoint?: (reportDir: string, payload: Record<string, unknown>) => Promise<void>;
+}
+export interface RunNeonsparkU2E2EOptions {
+    configPath: string;
+    reportDir?: string;
+    runId?: string;
+}
+export declare function createRunId(prefix?: string): string;
+export declare function extractSingleCountFromCypherResult(result: unknown): number | null;
+export declare function runNeonsparkU2E2E(options: RunNeonsparkU2E2EOptions): Promise<E2ERunResult>;
+export declare function runE2E(options?: RunE2EOptions): Promise<E2ERunResult>;