@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/native/scout-wrapper.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Scout Dispatcher Wrapper
+ *
+ * Provides scout dispatch via native N-API binding when available.
+ * Returns null if native is unavailable, letting the caller fall back
+ * to HTTP-based Musu adapter delegation.
+ *
+ * @since v1.7.0
+ */
+/** Input trigger for scout dispatch (matches Rust ScoutTrigger serde format) */
+export type ScoutTriggerInput = {
+    trigger_type: 'dep_shift';
+    payload: {
+        crate_name: string;
+        from_version: string;
+        to_version: string;
+    };
+} | {
+    trigger_type: 'auth_touch';
+    payload: {
+        file_path: string;
+        diff_summary: string;
+    };
+} | {
+    trigger_type: 'gate_fix';
+    payload: {
+        issue_id: string;
+        code_diff: string;
+    };
+};
+/** Scout report output (matches Rust JsScoutReport) */
+export interface ScoutReportOutput {
+    scenario: string;
+    block_id: string;
+    root_hash: string;
+    analysis: string;
+    latency_ms: number;
+    tokens: number;
+    timestamp: number;
+}
+/**
+ * Initialize the Scout singleton (heavy resources loaded once).
+ * Safe to call multiple times — only the first call does real work.
+ */
+export declare function initScoutSingleton(workspaceRoot: string): boolean;
+/** Check if native scout singleton is initialized */
+export declare function isScoutAvailable(): boolean;
+/** Check if BitNet binary/model are available for inference */
+export declare function isBitNetAvailable(workspaceRoot: string): boolean;
+/**
+ * Build a scout prompt for a trigger (preview only, no inference).
+ * Falls back to a simple template if native is unavailable.
+ */
+export declare function buildScoutPrompt(trigger: ScoutTriggerInput, workspaceRoot: string): string;
+/**
+ * Dispatch a scout trigger via the native singleton.
+ *
+ * - First call lazily initializes the singleton (heavy init, once).
+ * - Subsequent calls reuse the warm engine (lightweight).
+ * - Returns null if native is unavailable or BitNet is not configured.
+ * - Caller should fall back to HTTP-based Musu adapter delegation on null.
+ */
+export declare function dispatchScout(trigger: ScoutTriggerInput, workspaceRoot: string): Promise<ScoutReportOutput | null>;
+/**
+ * Save a heuristic analysis result as a SemanticBlock via the native bridge.
+ *
+ * Requires the Scout singleton to be initialized (calls initScoutSingleton).
+ * Returns the block_id if saved, or null if native bridge is unavailable.
+ */
+export declare function saveScoutReport(analysisJson: string, scenario: string, workspaceRoot: string): string | null;

package/build/native/scout-wrapper.js

@@ -0,0 +1,166 @@
+/**
+ * Scout Dispatcher Wrapper
+ *
+ * Provides scout dispatch via native N-API binding when available.
+ * Returns null if native is unavailable, letting the caller fall back
+ * to HTTP-based Musu adapter delegation.
+ *
+ * @since v1.7.0
+ */
+import { loadNative } from './loader.js';
+// ============================================================================
+// Singleton Lifecycle
+// ============================================================================
+/** Tracks whether we've attempted singleton init */
+let singletonInitAttempted = false;
+/**
+ * Initialize the Scout singleton (heavy resources loaded once).
+ * Safe to call multiple times — only the first call does real work.
+ */
+export function initScoutSingleton(workspaceRoot) {
+    if (singletonInitAttempted)
+        return isScoutAvailable();
+    singletonInitAttempted = true;
+    const native = loadNative();
+    if (!native?.initScout)
+        return false;
+    try {
+        native.initScout(workspaceRoot);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Availability Checks
+// ============================================================================
+/** Check if native scout singleton is initialized */
+export function isScoutAvailable() {
+    const native = loadNative();
+    if (native?.isScoutInitialized) {
+        return native.isScoutInitialized();
+    }
+    // Fallback: check if class-based API exists
+    return !!(native && native.ScoutDispatcher);
+}
+/** Check if BitNet binary/model are available for inference */
+export function isBitNetAvailable(workspaceRoot) {
+    const native = loadNative();
+    // Singleton path (preferred)
+    if (native?.isBitnetReady) {
+        initScoutSingleton(workspaceRoot);
+        return native.isBitnetReady();
+    }
+    // Legacy class-based fallback
+    if (!native?.ScoutDispatcher)
+        return false;
+    try {
+        const dispatcher = new native.ScoutDispatcher(workspaceRoot);
+        return dispatcher.isAvailable();
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Prompt Preview
+// ============================================================================
+/**
+ * Build a scout prompt for a trigger (preview only, no inference).
+ * Falls back to a simple template if native is unavailable.
+ */
+export function buildScoutPrompt(trigger, workspaceRoot) {
+    const native = loadNative();
+    if (native?.ScoutDispatcher) {
+        try {
+            const dispatcher = new native.ScoutDispatcher(workspaceRoot);
+            return dispatcher.buildPrompt(JSON.stringify(trigger));
+        }
+        catch {
+            // Fall through to JS fallback
+        }
+    }
+    // JS fallback: basic prompt
+    return `Scout analysis for ${trigger.trigger_type}: ${JSON.stringify(trigger.payload)}`;
+}
+// ============================================================================
+// Dispatch (Singleton — async, non-blocking)
+// ============================================================================
+/**
+ * Dispatch a scout trigger via the native singleton.
+ *
+ * - First call lazily initializes the singleton (heavy init, once).
+ * - Subsequent calls reuse the warm engine (lightweight).
+ * - Returns null if native is unavailable or BitNet is not configured.
+ * - Caller should fall back to HTTP-based Musu adapter delegation on null.
+ */
+export async function dispatchScout(trigger, workspaceRoot) {
+    const native = loadNative();
+    // Singleton path (preferred — async, non-blocking)
+    if (native?.dispatchScoutAction) {
+        if (!initScoutSingleton(workspaceRoot))
+            return null;
+        if (native.isBitnetReady && !native.isBitnetReady())
+            return null;
+        try {
+            const raw = await native.dispatchScoutAction(JSON.stringify(trigger));
+            return {
+                scenario: raw.scenario,
+                block_id: raw.blockId,
+                root_hash: raw.rootHash,
+                analysis: raw.analysis,
+                latency_ms: raw.latencyMs,
+                tokens: raw.tokens,
+                timestamp: raw.timestamp,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Legacy class-based fallback (sync, blocking)
+    if (!native?.ScoutDispatcher)
+        return null;
+    try {
+        const dispatcher = new native.ScoutDispatcher(workspaceRoot);
+        if (!dispatcher.isAvailable())
+            return null;
+        const raw = dispatcher.dispatch(JSON.stringify(trigger));
+        return {
+            scenario: raw.scenario,
+            block_id: raw.blockId,
+            root_hash: raw.rootHash,
+            analysis: raw.analysis,
+            latency_ms: raw.latencyMs,
+            tokens: raw.tokens,
+            timestamp: raw.timestamp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Heuristic Report Persistence
+// ============================================================================
+/**
+ * Save a heuristic analysis result as a SemanticBlock via the native bridge.
+ *
+ * Requires the Scout singleton to be initialized (calls initScoutSingleton).
+ * Returns the block_id if saved, or null if native bridge is unavailable.
+ */
+export function saveScoutReport(analysisJson, scenario, workspaceRoot) {
+    const native = loadNative();
+    if (!native?.saveScoutReport)
+        return null;
+    // Ensure singleton is initialized
+    if (!initScoutSingleton(workspaceRoot))
+        return null;
+    try {
+        return native.saveScoutReport(analysisJson, scenario);
+    }
+    catch {
+        return null;
+    }
+}

package/build/native/utils-wrapper.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Utility Function Wrappers
+ *
+ * Provides hash and validation utilities with native fallback.
+ */
+/**
+ * Compute a block ID from content and source reference.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param content - The block content
+ * @param sourceRef - The source reference (e.g., "file.ts:1-10")
+ * @returns Block ID in format "blk_<16 hex chars>"
+ */
+export declare function computeBlockId(content: string, sourceRef: string): string;
+/**
+ * Compute a root hash from source path.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param sourcePath - The source file path
+ * @returns Root hash in format "doc_<16 hex chars>"
+ */
+export declare function computeRootHash(sourcePath: string): string;
+/**
+ * Compute SHA256 hash of a string and return as hex.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param input - The input string
+ * @returns SHA256 hash as hex string
+ */
+export declare function sha256Hex(input: string): string;
+/**
+ * Validate a block ID format.
+ * Valid format: "blk_" followed by 16 hex characters (20 total).
+ *
+ * @param blockId - The block ID to validate
+ * @returns true if the format is valid
+ */
+export declare function isValidBlockId(blockId: string): boolean;
+/**
+ * Validate a root hash format.
+ * Valid format: "doc_" followed by 16 hex characters (20 total).
+ *
+ * @param rootHash - The root hash to validate
+ * @returns true if the format is valid
+ */
+export declare function isValidRootHash(rootHash: string): boolean;

package/build/native/utils-wrapper.js

@@ -0,0 +1,100 @@
+/**
+ * Utility Function Wrappers
+ *
+ * Provides hash and validation utilities with native fallback.
+ */
+import * as crypto from 'crypto';
+import { loadNative } from './loader.js';
+/**
+ * Compute a block ID from content and source reference.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param content - The block content
+ * @param sourceRef - The source reference (e.g., "file.ts:1-10")
+ * @returns Block ID in format "blk_<16 hex chars>"
+ */
+export function computeBlockId(content, sourceRef) {
+    const native = loadNative();
+    if (native) {
+        return native.computeBlockId(content, sourceRef);
+    }
+    // JavaScript fallback
+    const hash = crypto
+        .createHash('sha256')
+        .update(content)
+        .update('|')
+        .update(sourceRef)
+        .digest('hex');
+    return `blk_${hash.slice(0, 16)}`;
+}
+/**
+ * Compute a root hash from source path.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param sourcePath - The source file path
+ * @returns Root hash in format "doc_<16 hex chars>"
+ */
+export function computeRootHash(sourcePath) {
+    const native = loadNative();
+    if (native) {
+        return native.computeRootHash(sourcePath);
+    }
+    // JavaScript fallback
+    const hash = crypto.createHash('sha256').update(sourcePath).digest('hex');
+    return `doc_${hash.slice(0, 16)}`;
+}
+/**
+ * Compute SHA256 hash of a string and return as hex.
+ * Uses native if available, otherwise JavaScript fallback.
+ *
+ * @param input - The input string
+ * @returns SHA256 hash as hex string
+ */
+export function sha256Hex(input) {
+    const native = loadNative();
+    if (native) {
+        return native.sha256Hex(input);
+    }
+    // JavaScript fallback
+    return crypto.createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Validate a block ID format.
+ * Valid format: "blk_" followed by 16 hex characters (20 total).
+ *
+ * @param blockId - The block ID to validate
+ * @returns true if the format is valid
+ */
+export function isValidBlockId(blockId) {
+    if (blockId.length !== 20)
+        return false;
+    if (!blockId.startsWith('blk_'))
+        return false;
+    if (!/^[0-9a-f]{16}$/.test(blockId.slice(4)))
+        return false;
+    const native = loadNative();
+    if (native) {
+        return native.isValidBlockId(blockId);
+    }
+    return true;
+}
+/**
+ * Validate a root hash format.
+ * Valid format: "doc_" followed by 16 hex characters (20 total).
+ *
+ * @param rootHash - The root hash to validate
+ * @returns true if the format is valid
+ */
+export function isValidRootHash(rootHash) {
+    if (rootHash.length !== 20)
+        return false;
+    if (!rootHash.startsWith('doc_'))
+        return false;
+    if (!/^[0-9a-f]{16}$/.test(rootHash.slice(4)))
+        return false;
+    const native = loadNative();
+    if (native) {
+        return native.isValidRootHash(rootHash);
+    }
+    return true;
+}

package/build/observability/otel.d.ts

@@ -0,0 +1,71 @@
+/**
+ * OpenTelemetry SDK Integration (Sprint N-1)
+ * ==========================================
+ *
+ * Opt-in OTel instrumentation activated by VIBE_OTEL=1.
+ * Uses dynamic imports so the code never crashes when OTel
+ * packages are not installed.  All OTel types are kept as
+ * opaque references (`unknown`) so tsc stays clean even when
+ * the packages are absent from node_modules.
+ *
+ * Exports:
+ *   initOtel()      - start SDK + Prometheus exporter
+ *   shutdownOtel()  - graceful teardown
+ *   getTracer()     - returns a real or no-op tracer
+ *   getMeter()      - returns a real or no-op meter
+ *   isOtelActive()  - runtime guard
+ */
+export interface VibeSpan {
+    end(): void;
+    recordException(err: unknown): void;
+    setStatus(s: {
+        code: number;
+        message?: string;
+    }): void;
+}
+export interface VibeTracer {
+    startActiveSpan<T>(name: string, fn: (span: VibeSpan) => T): T;
+}
+export interface VibeCounter {
+    add(value: number, attrs?: Record<string, string>): void;
+}
+export interface VibeHistogram {
+    record(value: number, attrs?: Record<string, string>): void;
+}
+export interface VibeUpDownCounter {
+    add(value: number, attrs?: Record<string, string>): void;
+}
+export interface VibeMeter {
+    createCounter(name: string, opts?: {
+        description?: string;
+    }): VibeCounter;
+    createHistogram(name: string, opts?: {
+        description?: string;
+        unit?: string;
+    }): VibeHistogram;
+    createUpDownCounter(name: string, opts?: {
+        description?: string;
+    }): VibeUpDownCounter;
+}
+export declare function isOtelActive(): boolean;
+/**
+ * Returns the OTel Tracer for vibe-pm.
+ * If OTel is inactive a no-op tracer is returned (zero overhead).
+ */
+export declare function getTracer(name?: string): VibeTracer;
+/**
+ * Returns the OTel Meter for vibe-pm.
+ * If OTel is inactive a no-op meter is returned (zero overhead).
+ */
+export declare function getMeter(name?: string): VibeMeter;
+/**
+ * Initialise the OpenTelemetry SDK with a Prometheus exporter.
+ * Only activates when `process.env.VIBE_OTEL === '1'`.
+ *
+ * Safe to call multiple times; subsequent calls are no-ops.
+ */
+export declare function initOtel(): Promise<boolean>;
+/**
+ * Graceful shutdown. Safe to call even if OTel was never started.
+ */
+export declare function shutdownOtel(): Promise<void>;

package/build/observability/otel.js

@@ -0,0 +1,124 @@
+/**
+ * OpenTelemetry SDK Integration (Sprint N-1)
+ * ==========================================
+ *
+ * Opt-in OTel instrumentation activated by VIBE_OTEL=1.
+ * Uses dynamic imports so the code never crashes when OTel
+ * packages are not installed.  All OTel types are kept as
+ * opaque references (`unknown`) so tsc stays clean even when
+ * the packages are absent from node_modules.
+ *
+ * Exports:
+ *   initOtel()      - start SDK + Prometheus exporter
+ *   shutdownOtel()  - graceful teardown
+ *   getTracer()     - returns a real or no-op tracer
+ *   getMeter()      - returns a real or no-op meter
+ *   isOtelActive()  - runtime guard
+ */
+import { logger } from '../shared/logger.js';
+// ---- lazy module references (populated by initOtel) ----
+// Kept as `unknown` so we never reference @opentelemetry/* types at compile time.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let otelApi = null;
+/** Whether the OTel SDK has been successfully initialised. */
+let active = false;
+/** Holds the NodeSDK instance so we can shut it down later. */
+let sdkInstance = null;
+// ---- public helpers ----
+export function isOtelActive() {
+    return active;
+}
+/**
+ * Returns the OTel Tracer for vibe-pm.
+ * If OTel is inactive a no-op tracer is returned (zero overhead).
+ */
+export function getTracer(name = 'vibe-pm') {
+    if (active && otelApi) {
+        // The real OTel tracer satisfies VibeTracer via structural typing.
+        return otelApi.trace.getTracer(name);
+    }
+    // No-op tracer: calls fn immediately with a stub span.
+    return {
+        startActiveSpan(_name, fn) {
+            return fn({ end() { }, recordException() { }, setStatus() { } });
+        },
+    };
+}
+/**
+ * Returns the OTel Meter for vibe-pm.
+ * If OTel is inactive a no-op meter is returned (zero overhead).
+ */
+export function getMeter(name = 'vibe-pm') {
+    if (active && otelApi) {
+        return otelApi.metrics.getMeter(name);
+    }
+    const noopCounter = { add() { } };
+    const noopHistogram = { record() { } };
+    const noopUpDown = { add() { } };
+    return {
+        createCounter: () => noopCounter,
+        createHistogram: () => noopHistogram,
+        createUpDownCounter: () => noopUpDown,
+    };
+}
+// ---- lifecycle ----
+/**
+ * Initialise the OpenTelemetry SDK with a Prometheus exporter.
+ * Only activates when `process.env.VIBE_OTEL === '1'`.
+ *
+ * Safe to call multiple times; subsequent calls are no-ops.
+ */
+export async function initOtel() {
+    if (active)
+        return true;
+    if (process.env.VIBE_OTEL !== '1')
+        return false;
+    try {
+        // Dynamic imports - these will throw if packages are not installed.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const [api, sdkNodeMod, promExporterMod, sdkMetricsMod] = await Promise.all([
+            import('@opentelemetry/api'),
+            import('@opentelemetry/sdk-node'),
+            import('@opentelemetry/exporter-prometheus'),
+            import('@opentelemetry/sdk-metrics'),
+        ]);
+        otelApi = api;
+        const prometheusExporter = new promExporterMod.PrometheusExporter({
+            preventServerStart: true, // we serve /metrics ourselves
+        });
+        const meterProvider = new sdkMetricsMod.MeterProvider({
+            readers: [prometheusExporter],
+        });
+        const sdk = new sdkNodeMod.NodeSDK({
+            metricReader: prometheusExporter,
+        });
+        sdk.start();
+        sdkInstance = sdk;
+        // Register the meter provider globally so getMeter() works.
+        api.metrics.setGlobalMeterProvider(meterProvider);
+        active = true;
+        logger.info('[otel] OpenTelemetry SDK initialised (Prometheus exporter ready)');
+        return true;
+    }
+    catch (err) {
+        // Packages not installed or init failed - stay inactive.
+        logger.warn('[otel] OpenTelemetry init skipped: %s', err.message ?? err);
+        return false;
+    }
+}
+/**
+ * Graceful shutdown. Safe to call even if OTel was never started.
+ */
+export async function shutdownOtel() {
+    if (!active || !sdkInstance)
+        return;
+    try {
+        await sdkInstance.shutdown();
+    }
+    catch {
+        // ignore shutdown errors
+    }
+    active = false;
+    sdkInstance = null;
+    otelApi = null;
+}

package/build/offline-queue.js

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
+import { logger } from './shared/logger.js';
 // ============================================================================
 // Defaults (SSOT-ish)
 // ============================================================================
@@ -219,7 +220,7 @@ export class OfflineQueue {
                 catch {
                     // ignore
                 }
-                console.error(`[offline-queue] Failed to process ${fileName}:`, error);
+                logger.error(`[offline-queue] Failed to process ${fileName}: ${error}`);
             }
             finally {
                 this.unlock(fileName);

package/build/pool-manager/bitnet-adapter.d.ts

@@ -5,9 +5,9 @@
  * Adapter for BitNet workers in unified pool manager.
  * Implements least-queue + p95 tie-breaker worker selection.
  */
-import { type ChildProcess } from "node:child_process";
-import { BaseWorkerAdapter } from "./adapter.js";
-import type { WorkerType, UnifiedWorker, UnifiedHealthResponse, UnifiedPoolConfig, PoolMetrics, AutoscaleConfig } from "./types.js";
+import { type ChildProcess } from 'node:child_process';
+import { BaseWorkerAdapter } from './adapter.js';
+import type { WorkerType, UnifiedWorker, UnifiedHealthResponse, UnifiedPoolConfig, PoolMetrics, AutoscaleConfig } from './types.js';
 /**
  * BitNet worker adapter
  *