npm - @jagilber-org/index-server - Versions diffs - 1.26.4 → 1.26.11 - Mend

@jagilber-org/index-server 1.26.4 → 1.26.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/CHANGELOG.md +34 -0
package/dist/config/runtimeConfig.js +4 -1
package/dist/dashboard/client/admin.html +26 -26
package/dist/lib/mcpStdioLogging.d.ts +12 -0
package/dist/lib/mcpStdioLogging.js +39 -0
package/dist/services/logger.js +45 -16
package/dist/services/mcpLogBridge.d.ts +4 -1
package/dist/services/mcpLogBridge.js +26 -4
package/package.json +2 -1
package/scripts/setup-wizard.mjs +268 -16
package/server.json +2 -2

package/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,26 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 ## [Unreleased]
+## [1.26.11] - 2026-04-30
+### Fixed
+- **Release**: `server.json` now ends with exactly one trailing LF. The v1.26.10 release was published with two trailing LFs (artefact of an earlier `Set-Content -NoNewline` pipeline), which caused the mirror PR to fail CI on the `end-of-file-fixer` framework hook.
+- **Pre-commit (prevention)**: `scripts/pre-commit.mjs` now invokes the `pre-commit` framework on staged files for an explicit fast-hook allowlist (`end-of-file-fixer`, `trailing-whitespace`, `check-json`, `check-yaml`, `check-merge-conflict`, `detect-private-key`). Previously these framework hooks only ran in CI, so auto-fixable formatting issues silently passed local commits and broke PR builds. Slow security hooks (`gitleaks`, `semgrep`, `ggshield`, `detect-secrets`) deliberately remain in their own CI workflows / pre-push stage. Honours `SKIP_PRE_COMMIT_FRAMEWORK=1` and skips gracefully when `pre-commit` is not on PATH (#266).
+## [1.26.10] - 2026-04-30
+### Fixed
+- **CI**: `.github/workflows/precommit.yml` checkout now uses `fetch-depth: 0` so `pre-commit run --from-ref BASE --to-ref HEAD` (diff-only mode introduced in v1.26.9) can resolve the PR base SHA. Previous default `fetch-depth: 1` caused `git diff BASE..HEAD` to exit 3 with `CalledProcessError` on every PR (#264).
+- **Tests**: `skippedTestsAudit.spec.ts` env-check allowlist now recognizes platform identifiers (`isWindows`, `isLinux`, `isMac`, `isDarwin`, `process.platform`) so the new `ggshieldWithRetry.spec.ts` Windows-skip from v1.26.9 passes the audit (#264).
+## [1.26.6] - 2026-04-28
+### Fixed
+- **Setup Wizard**: Resolve server entry point for `npx` installs so the wizard can locate and launch the server correctly.
 ## [1.26.1] - 2026-04-27
 ### Fixed
@@ -1441,3 +1461,17 @@ No client changes required. Enable `INDEX_SERVER_MEMOIZE=1` (and optionally `IND
 ## [1.26.2] - 2026-04-27
 ## [1.26.4] - 2026-04-28
+## [1.26.5] - 2026-04-28
+## [1.26.7] - 2026-04-30
+### Added
+- fix(wizard): correct Build prompt logic
+## [1.26.8] - 2026-04-30
+### Added
+- Test stability + version parity tooling (PR #261)

package/dist/config/runtimeConfig.js CHANGED Viewed

@@ -266,8 +266,11 @@ function applyProfileDefaults(profile) {
         if (process.env[key] === undefined)
             process.env[key] = value;
     };
-    // All profiles enable dashboard by default
+    // All profiles enable dashboard and file logging by default.
+    // File logging uses the sentinel value '1' which resolves to logs/mcp-server.log.
+    // This ensures logs are always available on disk without requiring mcp.json changes.
     setDefault('INDEX_SERVER_DASHBOARD', '1');
+    setDefault('INDEX_SERVER_LOG_FILE', '1');
     if (profile === 'enhanced') {
         setDefault('INDEX_SERVER_SEMANTIC_ENABLED', '1');
         setDefault('INDEX_SERVER_SEMANTIC_LOCAL_ONLY', '0');

package/dist/dashboard/client/admin.html CHANGED Viewed

@@ -1,29 +1,29 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta name="dashboard-build-version" content="1.26.4-9badd8dd">
+    <meta name="dashboard-build-version" content="1.26.11-9badd8dd">
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Index Server Admin</title>
-    <link rel="stylesheet" href="css/admin.css?v=1.26.4-9badd8dd">
-    <script defer src="js/admin.utils.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.auth.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.overview.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.sessions.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.monitor.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.graph.js?v=1.26.4-9badd8dd"></script>
+    <link rel="stylesheet" href="css/admin.css?v=1.26.11-9badd8dd">
+    <script defer src="js/admin.utils.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.auth.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.overview.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.sessions.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.monitor.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.graph.js?v=1.26.11-9badd8dd"></script>
     <script defer src="js/marked.umd.js"></script>
-    <script defer src="js/admin.instructions.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.logs.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.maintenance.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.config.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.performance.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.instances.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.embeddings.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.messaging.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.sqlite.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.boot.js?v=1.26.4-9badd8dd"></script>
-    <script defer src="js/admin.feedback.js?v=1.26.4-9badd8dd"></script>
+    <script defer src="js/admin.instructions.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.logs.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.maintenance.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.config.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.performance.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.instances.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.embeddings.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.messaging.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.sqlite.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.boot.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.feedback.js?v=1.26.11-9badd8dd"></script>
 </head>
 <body>
     <div class="admin-container admin-root">
@@ -879,10 +879,10 @@
             }
         }
-        // Graph logic was extracted to js/admin.graph.js?v=1.26.4-9badd8dd
+        // Graph logic was extracted to js/admin.graph.js?v=1.26.11-9badd8dd
         // Functions available globally: reloadGraphMermaid, initGraphScopeDefaults, copyMermaidSource, toggleGraphEdit, applyGraphEdit, cancelGraphEdit, refreshDrillCategories, loadDrillInstructions, clearSelections
-        <!-- overview functions moved to js/admin.overview.js?v=1.26.4-9badd8dd -->
+        <!-- overview functions moved to js/admin.overview.js?v=1.26.11-9badd8dd -->
         // Lightweight overview-level maintenance display (optional)
         // Intentionally minimal to avoid blocking overview rendering.
@@ -1067,7 +1067,7 @@
         }
         // --- Backup / Restore ---
-        // Extracted to js/admin.maintenance.js?v=1.26.4-9badd8dd
+        // Extracted to js/admin.maintenance.js?v=1.26.11-9badd8dd
         async function performBackup() {
             try {
@@ -1133,7 +1133,7 @@
         }
                 async function loadConfiguration() {
-                    // Primary implementation in js/admin.config.js?v=1.26.4-9badd8dd (loaded via defer).
+                    // Primary implementation in js/admin.config.js?v=1.26.11-9badd8dd (loaded via defer).
                     // This inline fallback only fires if the external script failed to load.
                     if (window.__configExternalLoaded) return;
                     try {
@@ -1193,10 +1193,10 @@
                         return false;
                 }
-        // Monitoring functions moved to js/admin.monitor.js?v=1.26.4-9badd8dd
+        // Monitoring functions moved to js/admin.monitor.js?v=1.26.11-9badd8dd
         // ===== Log Viewer =====
-        // Extracted to js/admin.logs.js?v=1.26.4-9badd8dd
+        // Extracted to js/admin.logs.js?v=1.26.11-9badd8dd
         // ===== Instruction Management =====
         let instructionEditing = null;
@@ -1693,7 +1693,7 @@
             setInterval(fetchResourceTrends, 10000);
         })();
-        // Instruction management logic extracted to js/admin.instructions.js?v=1.26.4-9badd8dd
+        // Instruction management logic extracted to js/admin.instructions.js?v=1.26.11-9badd8dd
         // Functions exposed globally: loadInstructions, renderInstructionList, editInstruction, saveInstruction, deleteInstruction, etc.
         function startAutoRefresh() {

package/dist/lib/mcpStdioLogging.d.ts CHANGED Viewed

@@ -112,6 +112,7 @@ export declare class McpStdioLogger {
     private readonly _serverName;
     private readonly _maxBufferSize;
     private readonly _inferLevel;
+    private readonly _exitHandler;
     constructor(options?: McpStdioLoggerOptions);
     /**
      * Start intercepting process.stderr.write.
@@ -152,6 +153,17 @@ export declare class McpStdioLogger {
      * without triggering the MCP routing/buffering pipeline.
      */
     writeOriginalStderr(data: string): void;
+    /**
+     * Drain the pre-handshake buffer to the ORIGINAL stderr without requiring
+     * an MCP server activation. Used when the process is about to exit before
+     * the MCP handshake completes (e.g., `--help`, `--init-cert`, or a fatal
+     * startup error). Without this, buffered diagnostic lines would be silently
+     * discarded — see issue #234.
+     *
+     * Safe to call repeatedly; a no-op when the buffer is empty. Does not change
+     * `isActive` and does not require a registered server.
+     */
+    flushToStderr(): void;
     /**
      * Restore original stderr and deactivate the bridge.
      * Useful for testing cleanup or graceful shutdown.

package/dist/lib/mcpStdioLogging.js CHANGED Viewed

@@ -115,6 +115,7 @@ class McpStdioLogger {
     _serverName;
     _maxBufferSize;
     _inferLevel;
+    _exitHandler;
     constructor(options = {}) {
         this._serverName = options.serverName ?? 'mcp-server';
         this._maxBufferSize = options.maxBufferSize ?? 500;
@@ -123,6 +124,16 @@ class McpStdioLogger {
         if (options.interceptImmediately !== false) {
             this.interceptStderr();
         }
+        // Issue #234: if the process exits before the MCP handshake completes
+        // (e.g. --help, --init-cert, fatal startup error), drain buffered stderr
+        // so the user actually sees what was logged. Inactive bridge only —
+        // once activated, the buffer is already replayed via sendLoggingMessage.
+        this._exitHandler = () => {
+            if (!this._active && this._buffer.length > 0) {
+                this.flushToStderr();
+            }
+        };
+        process.on('exit', this._exitHandler);
     }
     // -----------------------------------------------------------------------
     // Public API
@@ -241,6 +252,30 @@ class McpStdioLogger {
         }
         catch { /* ignore */ }
     }
+    /**
+     * Drain the pre-handshake buffer to the ORIGINAL stderr without requiring
+     * an MCP server activation. Used when the process is about to exit before
+     * the MCP handshake completes (e.g., `--help`, `--init-cert`, or a fatal
+     * startup error). Without this, buffered diagnostic lines would be silently
+     * discarded — see issue #234.
+     *
+     * Safe to call repeatedly; a no-op when the buffer is empty. Does not change
+     * `isActive` and does not require a registered server.
+     */
+    flushToStderr() {
+        if (this._buffer.length === 0)
+            return;
+        for (const entry of this._buffer) {
+            const data = entry.data;
+            try {
+                this._originalStderrWrite(data.endsWith('\n') ? data : data + '\n');
+            }
+            catch {
+                /* ignore — best-effort drain */
+            }
+        }
+        this._buffer.length = 0;
+    }
     /**
      * Restore original stderr and deactivate the bridge.
      * Useful for testing cleanup or graceful shutdown.
@@ -250,6 +285,10 @@ class McpStdioLogger {
         this._active = false;
         this._intercepting = false;
         this._buffer.length = 0;
+        try {
+            process.removeListener('exit', this._exitHandler);
+        }
+        catch { /* ignore */ }
     }
     /**
      * Get the number of currently buffered lines (pre-handshake).

package/dist/services/logger.js CHANGED Viewed

@@ -26,6 +26,7 @@ const LEVEL_PRIORITY = {
  */
 function newCorrelationId() { return crypto_1.default.randomBytes(8).toString('hex'); }
 let logFileHandle = null;
+let logFilePath;
 function loggingCfg() {
     return (0, runtimeConfig_1.getRuntimeConfig)().logging;
 }
@@ -59,12 +60,25 @@ function shouldEmit(level) {
     const recordPriority = LEVEL_PRIORITY[level] ?? LEVEL_PRIORITY.INFO;
     return recordPriority >= threshold;
 }
+// Single exit handler — registered once to avoid listener accumulation on re-init
+let exitHandlerRegistered = false;
 // Initialize file logging if INDEX_SERVER_LOG_FILE is specified
 function initializeFileLogging() {
     const cfg = loggingCfg();
     const logFile = cfg.file;
-    if (!logFile || logFileHandle)
-        return; // Already initialized or not requested
+    if (!logFile)
+        return;
+    // If file handle exists but path changed (e.g., test reconfiguration), close old and reopen
+    if (logFileHandle && logFilePath !== logFile) {
+        try {
+            logFileHandle.end();
+        }
+        catch { /* ignore */ }
+        logFileHandle = null;
+        logFilePath = undefined;
+    }
+    if (logFileHandle)
+        return; // Already initialized for this path
     try {
         // Ensure log directory exists
         const logDir = path_1.default.dirname(logFile);
@@ -76,6 +90,17 @@ function initializeFileLogging() {
             flags: 'a',
             encoding: 'utf8'
         });
+        logFilePath = logFile;
+        // Graceful fallback: if the stream hits EPERM/EACCES, disable file logging
+        logFileHandle.on('error', (err) => {
+            process.stderr.write(`[logger] File logging error (${err.code ?? err.message}), falling back to stderr-only\n`);
+            try {
+                logFileHandle?.end();
+            }
+            catch { /* ignore */ }
+            logFileHandle = null;
+            logFilePath = undefined;
+        });
         // NDJSON session start record
         const sessionStart = {
             ts: new Date().toISOString(),
@@ -85,19 +110,22 @@ function initializeFileLogging() {
         };
         const startLine = JSON.stringify(sessionStart);
         logFileHandle.write(startLine + '\n');
-        // Cleanup on process exit
-        process.on('exit', () => {
-            if (logFileHandle && !logFileHandle.destroyed) {
-                const sessionEnd = {
-                    ts: new Date().toISOString(),
-                    level: 'INFO',
-                    msg: '[logger] Session ended',
-                    pid: process.pid,
-                };
-                logFileHandle.write(JSON.stringify(sessionEnd) + '\n');
-                logFileHandle.end();
-            }
-        });
+        // Cleanup on process exit — register only once
+        if (!exitHandlerRegistered) {
+            exitHandlerRegistered = true;
+            process.on('exit', () => {
+                if (logFileHandle && !logFileHandle.destroyed) {
+                    const sessionEnd = {
+                        ts: new Date().toISOString(),
+                        level: 'INFO',
+                        msg: '[logger] Session ended',
+                        pid: process.pid,
+                    };
+                    logFileHandle.write(JSON.stringify(sessionEnd) + '\n');
+                    logFileHandle.end();
+                }
+            });
+        }
         // Emit NDJSON init diagnostic
         try {
             const stats = fs_1.default.existsSync(logFile) ? fs_1.default.statSync(logFile) : null;
@@ -153,8 +181,9 @@ function emit(rec) {
     if (!shouldEmit(rec.level))
         return;
     // Initialize file logging on first emit (lazy initialization)
+    // or reinitialize if the configured path has changed (e.g., test reconfiguration)
     const cfg = loggingCfg();
-    if (!logFileHandle && cfg.file) {
+    if (cfg.file && (!logFileHandle || logFilePath !== cfg.file)) {
         initializeFileLogging();
     }
     // Always include pid for multi-process identification

package/dist/services/mcpLogBridge.d.ts CHANGED Viewed

@@ -23,15 +23,18 @@ export declare function registerMcpServer(server: any): void;
  * Activate the bridge so subsequent log calls are routed via MCP protocol.
  * Replays any buffered pre-handshake stderr lines through the protocol.
  * Called from `emitReadyGlobal()` after the handshake completes.
+ *
+ * No-op when STDERR_BRIDGE_ENABLED is false (default).
  */
 export declare function activateMcpLogBridge(): void;
 /**
  * Returns true if the bridge is active and logs will be sent via MCP protocol.
+ * Always false when STDERR_BRIDGE_ENABLED is false (default).
  */
 export declare function isMcpLogBridgeActive(): boolean;
 /**
  * Send a log message through the MCP `notifications/message` protocol.
- * No-op if the bridge is not yet active.
+ * No-op if the bridge is not yet active or not enabled.
  *
  * @param level - The index-server log level (TRACE, DEBUG, INFO, WARN, ERROR)
  * @param data  - The log payload (typically the NDJSON string)

package/dist/services/mcpLogBridge.js CHANGED Viewed

@@ -29,10 +29,25 @@ const LEVEL_MAP = {
     WARN: 'warning',
     ERROR: 'error',
 };
-// Singleton instance — intercepts stderr immediately on module load.
+// Bridge default: DISABLED.
+//
+// History: enabling-by-default routed all logs through MCP `notifications/message`
+// and suppressed raw stderr. VS Code Insiders does not surface those notifications
+// in any visible output channel, so the net effect for that client was complete
+// log silence (regression first observed after commit 5de6662 / v1.26.4).
+//
+// Default is now off: stderr flows raw, which every MCP-aware client (including
+// VS Code Insiders' `[server stderr]` rendering) handles. Set
+// INDEX_SERVER_ENABLE_STDERR_BRIDGE=1 to opt in to the protocol-level routing
+// (preferred for clients that render `notifications/message` with proper severity).
+//
+// The legacy INDEX_SERVER_DISABLE_STDERR_BRIDGE variable is now a no-op (the
+// new default already matches what setting it did).
+const STDERR_BRIDGE_ENABLED = process.env.INDEX_SERVER_ENABLE_STDERR_BRIDGE === '1';
+// Singleton instance — intercepts stderr only when the bridge is opted in.
 const _logger = new mcpStdioLogging_1.McpStdioLogger({
     serverName: 'index-server',
-    interceptImmediately: process.env.INDEX_SERVER_DISABLE_STDERR_BRIDGE !== '1',
+    interceptImmediately: STDERR_BRIDGE_ENABLED,
     maxBufferSize: 500,
 });
 /**
@@ -47,24 +62,31 @@ function registerMcpServer(server) {
  * Activate the bridge so subsequent log calls are routed via MCP protocol.
  * Replays any buffered pre-handshake stderr lines through the protocol.
  * Called from `emitReadyGlobal()` after the handshake completes.
+ *
+ * No-op when STDERR_BRIDGE_ENABLED is false (default).
  */
 function activateMcpLogBridge() {
+    if (!STDERR_BRIDGE_ENABLED)
+        return;
     _logger.activate();
 }
 /**
  * Returns true if the bridge is active and logs will be sent via MCP protocol.
+ * Always false when STDERR_BRIDGE_ENABLED is false (default).
  */
 function isMcpLogBridgeActive() {
-    return _logger.isActive;
+    return STDERR_BRIDGE_ENABLED && _logger.isActive;
 }
 /**
  * Send a log message through the MCP `notifications/message` protocol.
- * No-op if the bridge is not yet active.
+ * No-op if the bridge is not yet active or not enabled.
  *
  * @param level - The index-server log level (TRACE, DEBUG, INFO, WARN, ERROR)
  * @param data  - The log payload (typically the NDJSON string)
  */
 function sendMcpLog(level, data) {
+    if (!STDERR_BRIDGE_ENABLED)
+        return;
     _logger.log(LEVEL_MAP[level] ?? 'info', data);
 }
 /**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jagilber-org/index-server",
-  "version": "1.26.4",
+  "version": "1.26.11",
   "mcpName": "io.github.jagilber-org/index-server",
   "description": "MCP instruction indexing server for AI assistant governance — search, CRUD, schema validation, usage tracking, and cross-repo knowledge promotion.",
   "publishConfig": {
@@ -50,6 +50,7 @@
     "manifest:generate": "node scripts/generate-manifest.mjs",
     "contract:tools": "node scripts/generate-tools-snapshot.mjs",
     "verify:manifest": "node scripts/verify-manifest.mjs",
+    "check:version-parity": "node scripts/check-version-parity.mjs",
     "test": "npm run test:fast",
     "test:all": "vitest run",
     "test:watch": "vitest",

package/scripts/setup-wizard.mjs CHANGED Viewed

@@ -20,6 +20,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { select, input, confirm, checkbox } from '@inquirer/prompts';
@@ -27,12 +28,90 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
 const IS_WINDOWS = process.platform === 'win32';
+// --------------------------------------------------------------------------
+// Launch spec resolver — determines how to invoke index-server at runtime.
+//
+// Returns { command, args, cwd, source } where source indicates the mode:
+//   'local'    — dist/ found at config.root (dev checkout)
+//   'packaged' — dist/ found in the package ROOT but not config.root (npx install)
+//   'npx'      — fallback when no dist/ found anywhere
+// --------------------------------------------------------------------------
+function resolveServerLaunch(config) {
+  const entryRelative = 'dist/server/index-server.js';
+  const localEntry = path.join(config.root, entryRelative);
+  const packagedEntry = path.join(ROOT, entryRelative);
+  // Case 1: config.root is the repo checkout with dist/ present
+  if (fs.existsSync(localEntry)) {
+    return {
+      command: 'node',
+      args: [entryRelative],
+      cwd: config.root,
+      source: 'local',
+    };
+  }
+  // Case 2: dist/ exists in the package root (npx cache) but not in config.root
+  if (fs.existsSync(packagedEntry)) {
+    return {
+      command: 'node',
+      args: [fwd(packagedEntry)],
+      cwd: config.root,
+      source: 'packaged',
+    };
+  }
+  // Case 3: no dist/ anywhere — use npx as last resort
+  let pkgName = '@jagilber-org/index-server';
+  let pkgVersion = '';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+    if (pkg.name) pkgName = pkg.name;
+    if (pkg.version) pkgVersion = `@${pkg.version}`;
+  } catch {
+    console.warn('⚠ Could not read package.json — npx will use latest published version');
+  }
+  return {
+    command: 'npx',
+    args: ['-y', `${pkgName}${pkgVersion}`],
+    cwd: config.root,
+    source: 'npx',
+  };
+}
 // --------------------------------------------------------------------------
 // Path helpers
 // --------------------------------------------------------------------------
 /** Normalize to forward slashes for mcp.json compatibility. */
 function fwd(p) { return p.replace(/\\/g, '/'); }
+/** Locate the npm CLI script for execFileSync(node, [npmCli, ...]). Returns null if not found. */
+function findNpmCli() {
+  // npm_execpath is set when running via npm/npx
+  if (process.env.npm_execpath) return process.env.npm_execpath;
+  // Resolve npm relative to the Node.js installation
+  const candidates = [
+    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+/** Run an npm command. Uses npm CLI script if found, otherwise shells out to `npm` on PATH. */
+function runNpm(args, opts = {}) {
+  const npmCli = findNpmCli();
+  if (npmCli) {
+    return execFileSync(process.execPath, [npmCli, ...args], opts);
+  }
+  // Fallback: invoke `npm` directly via execFileSync (uses npm.cmd on Windows).
+  const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return execFileSync(npmBin, args, opts);
+}
 /** Resolve a sub-path under a root, always absolute and forward-slashed. */
 function resolveUnder(root, ...segments) { return fwd(path.resolve(root, ...segments)); }
@@ -120,6 +199,7 @@ function parseNonInteractiveArgs() {
     scope: 'repo',           // 'global' or 'repo'
     write: false,            // write to real config files
     preview: true,           // show preview before writing
+    deploy: true,            // deploy runtime to root when needed
   };
   for (let i = 0; i < args.length; i++) {
@@ -136,6 +216,7 @@ function parseNonInteractiveArgs() {
     else if (args[i] === '--scope' && args[i + 1]) config.scope = args[++i];
     else if (args[i] === '--write') config.write = true;
     else if (args[i] === '--no-preview') config.preview = false;
+    else if (args[i] === '--no-deploy') config.deploy = false;
   }
   // Profile overrides
@@ -253,7 +334,7 @@ async function runInteractiveWizard() {
     default: 'repo',
   });
-  return { profile, root, serverName, port, host, mutation, logLevel, generateCerts, targets, scope, write: true, preview: true };
+  return { profile, root, serverName, port, host, mutation, logLevel, generateCerts, targets, scope, write: true, preview: true, deploy: true };
 }
 // --------------------------------------------------------------------------
@@ -362,15 +443,17 @@ function getEnvCatalog(config, paths) {
 function generateMcpJson(config, paths) {
   const catalog = getEnvCatalog(config, paths);
   const indent = '\t\t\t\t';
+  const launch = resolveServerLaunch(config);
+  const argsJson = JSON.stringify(launch.args);
   const lines = [
     '{',
     '\t"servers": {',
     `\t\t"${config.serverName}": {`,
     '\t\t\t"type": "stdio",',
-    `\t\t\t"cwd": "${fwd(config.root)}",`,
-    '\t\t\t"command": "node",',
-    '\t\t\t"args": ["dist/server/index-server.js"],',
+    `\t\t\t"cwd": "${fwd(launch.cwd)}",`,
+    `\t\t\t"command": "${launch.command}",`,
+    `\t\t\t"args": ${argsJson},`,
     '\t\t\t"env": {',
   ];
@@ -412,11 +495,16 @@ function generateCopilotCliJson(config, paths) {
     if (entry.section) continue;
     if (entry.active) env[entry.key] = entry.value;
   }
+  const launch = resolveServerLaunch(config);
+  // copilot-cli doesn't reliably inherit cwd — use absolute args for local/packaged
+  const args = launch.source === 'local'
+    ? [fwd(path.resolve(launch.cwd, launch.args[0]))]
+    : launch.args;
   const obj = {
     mcpServers: {
       [config.serverName]: {
-        command: 'node',
-        args: [path.join(fwd(config.root), 'dist/server/index-server.js')],
+        command: launch.command,
+        args,
         env,
       },
     },
@@ -434,11 +522,16 @@ function generateClaudeDesktopJson(config, paths) {
     if (entry.section) continue;
     if (entry.active) env[entry.key] = entry.value;
   }
+  const launch = resolveServerLaunch(config);
+  // Claude Desktop doesn't support cwd — use absolute args for local/packaged
+  const args = launch.source === 'local'
+    ? [fwd(path.resolve(launch.cwd, launch.args[0]))]
+    : launch.args;
   const obj = {
     mcpServers: {
       [config.serverName]: {
-        command: 'node',
-        args: [path.join(fwd(config.root), 'dist/server/index-server.js')],
+        command: launch.command,
+        args,
         env,
       },
     },
@@ -620,6 +713,143 @@ function printFolderSummary(paths, profile) {
   console.log('└────────────────────┴────────────────────────────────────────────────┘');
 }
+// --------------------------------------------------------------------------
+// Deploy runtime to target root (when different from package root)
+// --------------------------------------------------------------------------
+async function deployRuntime(config) {
+  if (config.deploy === false) return;
+  let sourceRoot, targetRoot;
+  try {
+    sourceRoot = fs.realpathSync(ROOT);
+    targetRoot = fs.realpathSync(config.root);
+  } catch {
+    sourceRoot = path.resolve(ROOT);
+    targetRoot = path.resolve(config.root);
+  }
+  // Skip when running from the target directory (dev clone / already deployed)
+  if (sourceRoot.toLowerCase() === targetRoot.toLowerCase()) return;
+  const entryPoint = path.join(targetRoot, 'dist', 'server', 'index-server.js');
+  const targetPkg = path.join(targetRoot, 'package.json');
+  // Read source version for comparison
+  let sourceVersion = 'unknown';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+    sourceVersion = pkg.version || 'unknown';
+  } catch { /* ok */ }
+  // Check if already deployed at this version
+  if (fs.existsSync(entryPoint) && fs.existsSync(targetPkg)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(targetPkg, 'utf8'));
+      if (existing.version === sourceVersion) {
+        console.log(`\n✅ Runtime v${sourceVersion} already deployed at ${config.root}`);
+        return;
+      }
+      console.log(`\n📦 Upgrading runtime: ${existing.version} → ${sourceVersion}`);
+    } catch { /* ok - redeploy */ }
+  } else {
+    console.log(`\n📦 Deploying runtime v${sourceVersion} to ${config.root}...`);
+  }
+  const pkgName = '@jagilber-org/index-server';
+  // Strategy: npm install the exact package version into the target directory
+  // This gives a proper node_modules tree regardless of npx cache layout
+  try {
+    fs.mkdirSync(targetRoot, { recursive: true });
+    // Write a minimal package.json if none exists (npm install needs it)
+    if (!fs.existsSync(targetPkg)) {
+      const minPkg = {
+        name: 'index-server-runtime',
+        version: '1.0.0',
+        private: true,
+        type: 'commonjs',
+        scripts: { start: 'node node_modules/@jagilber-org/index-server/dist/server/index-server.js' },
+      };
+      fs.writeFileSync(targetPkg, JSON.stringify(minPkg, null, 2), 'utf8');
+    }
+    console.log('   Installing package (this may take a moment)...');
+    // Strategy: pack the current package into a tarball, then install it.
+    // This works regardless of whether the version is published to npm,
+    // and produces a proper self-contained node_modules tree.
+    const packOutput = runNpm(
+      ['pack', '--pack-destination', targetRoot],
+      { cwd: ROOT, stdio: ['pipe', 'pipe', 'inherit'], timeout: 30_000 }
+    ).toString().trim();
+    const tarballName = packOutput.split('\n').pop();
+    const tarballPath = path.join(targetRoot, tarballName);
+    try {
+      // Install from the local tarball
+      runNpm(
+        ['install', tarballPath, '--omit=dev', '--no-fund', '--no-audit'],
+        { cwd: targetRoot, stdio: 'inherit', timeout: 120_000 }
+      );
+    } finally {
+      // Clean up tarball
+      try { fs.unlinkSync(tarballPath); } catch { /* ok */ }
+    }
+    // Create convenience symlinks/junctions so "dist/" at root resolves
+    const installedDist = path.join(targetRoot, 'node_modules', pkgName, 'dist');
+    const targetDist = path.join(targetRoot, 'dist');
+    if (fs.existsSync(installedDist)) {
+      // Remove stale junction/directory before (re)creating — handles broken junctions on Windows
+      try { fs.rmSync(targetDist, { recursive: true, force: true }); } catch { /* ok if absent */ }
+      try {
+        // On Windows, directory junctions don't require elevated privileges
+        fs.symlinkSync(installedDist, targetDist, 'junction');
+      } catch {
+        // Fallback: copy dist recursively
+        fs.cpSync(installedDist, targetDist, { recursive: true });
+      }
+    }
+    // Copy schemas — refresh on redeploy/upgrade
+    const installedSchemas = path.join(targetRoot, 'node_modules', pkgName, 'schemas');
+    const targetSchemas = path.join(targetRoot, 'schemas');
+    if (fs.existsSync(installedSchemas)) {
+      try { fs.rmSync(targetSchemas, { recursive: true, force: true }); } catch { /* ok if absent */ }
+      fs.cpSync(installedSchemas, targetSchemas, { recursive: true });
+    }
+    // Update the runtime package.json with correct version/start script
+    try {
+      const runtimePkg = JSON.parse(fs.readFileSync(targetPkg, 'utf8'));
+      runtimePkg.version = sourceVersion;
+      runtimePkg.scripts = runtimePkg.scripts || {};
+      runtimePkg.scripts.start = 'node dist/server/index-server.js';
+      fs.writeFileSync(targetPkg, JSON.stringify(runtimePkg, null, 2) + '\n', 'utf8');
+    } catch { /* ok */ }
+    // Verify the deployed server is actually runnable
+    const deployedEntry = path.join(targetRoot, 'dist', 'server', 'index-server.js');
+    if (!fs.existsSync(deployedEntry)) {
+      throw new Error(
+        `dist/server/index-server.js not found after deployment. ` +
+        `Build the project first: cd "${ROOT}" && npm run build`
+      );
+    }
+    console.log(`   ✅ Runtime deployed to ${config.root}`);
+  } catch (err) {
+    console.error(`\n❌ Runtime deployment failed: ${err.message}`);
+    console.error('   To deploy manually, run:');
+    console.error(`   cd "${config.root}" && npm install ${pkgName}@${sourceVersion}`);
+    console.error('   Then create a symlink: dist -> node_modules/@jagilber-org/index-server/dist');
+    // Exit with error so CI can detect deployment failures
+    process.exitCode = 1;
+  }
+}
 // --------------------------------------------------------------------------
 // Main
 // --------------------------------------------------------------------------
@@ -646,7 +876,8 @@ Non-interactive mode:
     --target <list>     Comma-separated targets: vscode,copilot-cli,claude
     --scope <s>         global | repo (default: repo)
     --write             Write directly to real config files (with backup)
-    --no-preview        Skip config preview in non-interactive mode`);
+    --no-preview        Skip config preview in non-interactive mode
+    --no-deploy         Skip runtime deployment to target root`);
     process.exit(0);
   }
@@ -718,11 +949,13 @@ Non-interactive mode:
     }
   }
+  // ── Deploy runtime if target root differs from package root ─────────
+  await deployRuntime(config);
   // ── Generate TLS certs ──────────────────────────────────────────────
   if (config.generateCerts) {
     console.log('\n🔐 Generating TLS certificates...');
     try {
-      const { execFileSync } = await import('child_process');
       const certDir = path.join(config.root, 'certs');
       execFileSync(
         process.execPath,
@@ -737,16 +970,27 @@ Non-interactive mode:
   // ── Next steps ──────────────────────────────────────────────────────
   const proto = (config.profile === 'enhanced' || config.profile === 'experimental') ? 'https' : 'http';
+  const launch = resolveServerLaunch(config);
   console.log('\n╔════════════════════════════════════════════════════════════════╗');
   console.log('║                         Next Steps                            ║');
   console.log('╚════════════════════════════════════════════════════════════════╝\n');
-  console.log('  1. Build the server:');
-  console.log('     npm run build\n');
+  let step = 1;
+  // Note: `packaged` source means dist/ ships with the wizard package — nothing to
+  // build. The packaged-runtime info banner below covers it. Issue #260: do NOT
+  // print "npm run build" here because config.root is typically a data-only
+  // directory with no package.json (npm run build → ENOENT).
+  if (launch.source === 'npx') {
+    console.log(`  ${step}. The server will be fetched via npx on first start.\n`);
+    step++;
+  }
   if (config.write) {
-    console.log('  2. Config files have been written. Restart your MCP client.\n');
+    console.log(`  ${step}. Config files have been written. Restart your MCP client.\n`);
+    step++;
   } else {
-    console.log('  2. Copy generated config into your MCP client settings.');
+    console.log(`  ${step}. Copy generated config into your MCP client settings.`);
     for (const ct of configTargets) {
       const genPath = ct.format === 'vscode' || ct.format === 'vscode-global'
         ? path.join(config.root, '.vscode', 'mcp.json.generated')
@@ -754,15 +998,18 @@ Non-interactive mode:
       console.log(`     ${ct.target}: ${genPath}`);
     }
     console.log('');
+    step++;
   }
-  console.log(`  3. Open the dashboard:`);
+  console.log(`  ${step}. Open the dashboard:`);
   console.log(`     ${proto}://localhost:${config.port}\n`);
+  step++;
   if (config.profile === 'enhanced' || config.profile === 'experimental') {
-    console.log('  4. First-time semantic search:');
+    console.log(`  ${step}. First-time semantic search:`);
     console.log('     The MiniLM model (~90MB) will download on first query.');
     console.log(`     Model cache: ${paths.modelCache}\n`);
+    step++;
   }
   if (config.profile === 'experimental') {
@@ -770,6 +1017,11 @@ Non-interactive mode:
     console.log(`     ${paths.sqliteDb}\n`);
   }
+  if (launch.source === 'packaged') {
+    console.log('  ℹ️  Using packaged runtime from current installation.');
+    console.log('     Rerun without --no-deploy for a self-contained install.\n');
+  }
   console.log(`  Targets: ${(config.targets || ['vscode']).join(', ')} | Scope: ${config.scope || 'repo'}`);
   console.log(`  Profile: ${config.profile} | Root: ${fwd(config.root)}`);
   console.log('');

package/server.json CHANGED Viewed

@@ -6,12 +6,12 @@
     "url": "https://github.com/jagilber-org/index-server",
     "source": "github"
   },
-  "version": "1.26.4",
+  "version": "1.26.11",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@jagilber-org/index-server",
-      "version": "1.26.4",
+      "version": "1.26.11",
       "transport": {
         "type": "stdio"
       }