@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/gateway/config.js

@@ -0,0 +1,49 @@
+/**
+ * Gateway Config
+ * ==============
+ * Environment variable resolution for Prime gateway registration.
+ *
+ * Activation: Set MUSU_PRIME_URL to enable gateway registration.
+ * If not set, all gateway functions gracefully no-op.
+ *
+ * @module gateway/config
+ */
+import * as os from 'node:os';
+// ============================================================================
+// Environment Variable Names
+// ============================================================================
+export const GW_ENV = {
+    /** Prime gateway base URL. If unset, gateway is disabled. */
+    PRIME_URL: 'MUSU_PRIME_URL',
+    /** Override node ID (default: vibe-pm-<hostname>) */
+    NODE_ID: 'VIBE_GATEWAY_NODE_ID',
+    /** Heartbeat interval in seconds (default: 30) */
+    HEARTBEAT_SECS: 'VIBE_GATEWAY_HEARTBEAT_SECS',
+    /** HTTP request timeout in ms (default: 5000) */
+    TIMEOUT_MS: 'VIBE_GATEWAY_TIMEOUT_MS',
+    /** Bearer token for gateway auth (optional) */
+    AUTH_TOKEN: 'MUSU_SHARED_SECRET',
+};
+// ============================================================================
+// Functions
+// ============================================================================
+/**
+ * Returns true if gateway registration is enabled (MUSU_PRIME_URL is set).
+ */
+export function isGatewayEnabled() {
+    const url = process.env[GW_ENV.PRIME_URL]?.trim();
+    return !!url && url.length > 0;
+}
+/**
+ * Build gateway config from environment.
+ * Only call after checking `isGatewayEnabled()`.
+ */
+export function getGatewayConfig(hubUrl, hubPort) {
+    const primeUrl = process.env[GW_ENV.PRIME_URL]?.trim() ?? 'http://127.0.0.1:8791';
+    const nodeId = process.env[GW_ENV.NODE_ID]?.trim()
+        || `vibe-pm-${os.hostname()}`;
+    const heartbeatSecs = parseInt(process.env[GW_ENV.HEARTBEAT_SECS] ?? '30', 10);
+    const timeoutMs = parseInt(process.env[GW_ENV.TIMEOUT_MS] ?? '5000', 10);
+    const authToken = process.env[GW_ENV.AUTH_TOKEN]?.trim() || null;
+    return { primeUrl, nodeId, heartbeatSecs, timeoutMs, authToken, hubUrl, hubPort };
+}

package/build/gateway/dispatch_handler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gateway Dispatch Handler
+ * ========================
+ * Fastify route that receives dispatch jobs from Prime gateway.
+ *
+ * Prime can push jobs to Vibe PM when it needs code_inspection, gate, or
+ * briefing capabilities. This handler receives those jobs and returns results.
+ *
+ * Route: POST /v1/callback/dispatch
+ *
+ * @module gateway/dispatch_handler
+ */
+import type { FastifyInstance } from 'fastify';
+/**
+ * Register the gateway dispatch callback route on a Fastify instance.
+ */
+export declare function registerDispatchRoute(app: FastifyInstance): void;

package/build/gateway/dispatch_handler.js

@@ -0,0 +1,95 @@
+/**
+ * Gateway Dispatch Handler
+ * ========================
+ * Fastify route that receives dispatch jobs from Prime gateway.
+ *
+ * Prime can push jobs to Vibe PM when it needs code_inspection, gate, or
+ * briefing capabilities. This handler receives those jobs and returns results.
+ *
+ * Route: POST /v1/callback/dispatch
+ *
+ * @module gateway/dispatch_handler
+ */
+import { inspectCode } from '../mcp/tools/vibe_pm/inspect_code/index.js';
+import { briefing } from '../mcp/tools/vibe_pm/briefing.js';
+// ============================================================================
+// Route Registration
+// ============================================================================
+/**
+ * Register the gateway dispatch callback route on a Fastify instance.
+ */
+export function registerDispatchRoute(app) {
+    app.post('/v1/callback/dispatch', async (req, reply) => {
+        const { job_id, capability, payload } = req.body ?? {};
+        if (!job_id || !capability) {
+            return reply.status(400).send({
+                ok: false,
+                error: 'job_id and capability are required',
+            });
+        }
+        try {
+            const result = await handleDispatch(capability, payload ?? {});
+            const response = { ok: true, job_id, result };
+            return reply.status(200).send(response);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const response = { ok: false, job_id, error: msg };
+            return reply.status(500).send(response);
+        }
+    });
+}
+// ============================================================================
+// Dispatch Logic
+// ============================================================================
+/**
+ * Route a dispatch job to the appropriate handler based on capability.
+ * Calls the actual MCP tool internals for each capability.
+ */
+async function handleDispatch(capability, payload) {
+    switch (capability) {
+        case 'code_inspection':
+            return handleCodeInspection(payload);
+        case 'gate':
+            // Gate evaluation is performed within inspect_code (cockpitd or local).
+            // A standalone gate dispatch re-uses inspect_code with gate-only mode.
+            return handleCodeInspection({ ...payload, mode: 'gate' });
+        case 'briefing':
+            return handleBriefing(payload);
+        default:
+            throw new Error(`Unsupported capability: ${capability}`);
+    }
+}
+async function handleCodeInspection(payload) {
+    const mode = asOptionalString(payload['mode']);
+    const reviewStage = asOptionalString(payload['review_stage']);
+    const input = {
+        target_paths: asStringArray(payload['target_paths']),
+        project_id: asOptionalString(payload['project_id']),
+        ...(mode === 'quick' || mode === 'thorough' ? { mode } : {}),
+        ...(reviewStage === 'full' || reviewStage === 'spec_compliance' || reviewStage === 'code_quality'
+            ? { review_stage: reviewStage } : {}),
+    };
+    return inspectCode(input);
+}
+async function handleBriefing(payload) {
+    const input = {
+        project_brief: typeof payload['project_brief'] === 'string'
+            ? payload['project_brief']
+            : JSON.stringify(payload),
+        mode: asOptionalString(payload['mode']),
+        project_id: asOptionalString(payload['project_id']),
+    };
+    return briefing(input);
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function asStringArray(val) {
+    if (Array.isArray(val))
+        return val.filter((v) => typeof v === 'string');
+    return undefined;
+}
+function asOptionalString(val) {
+    return typeof val === 'string' ? val : undefined;
+}

package/build/gateway/heartbeat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gateway Heartbeat Loop
+ * ======================
+ * Periodic heartbeat to keep the registration alive.
+ * Auto re-registers if heartbeat fails (node evicted as stale).
+ *
+ * @module gateway/heartbeat
+ */
+import type { GatewayConfig } from './config.js';
+export interface HeartbeatHandle {
+    /** Stop the heartbeat loop and deregister. */
+    stop: () => Promise<void>;
+}
+/**
+ * Start the gateway registration + heartbeat loop.
+ *
+ * 1. Attempts initial registration (with retry backoff).
+ * 2. Once registered, sends periodic heartbeats.
+ * 3. If heartbeat fails, re-registers automatically.
+ *
+ * Returns a handle to stop the loop.
+ */
+export declare function startGatewayHeartbeat(config: GatewayConfig): Promise<HeartbeatHandle>;

package/build/gateway/heartbeat.js

@@ -0,0 +1,78 @@
+/**
+ * Gateway Heartbeat Loop
+ * ======================
+ * Periodic heartbeat to keep the registration alive.
+ * Auto re-registers if heartbeat fails (node evicted as stale).
+ *
+ * @module gateway/heartbeat
+ */
+import { registerWithGateway, sendHeartbeat, deregisterFromGateway } from './client.js';
+import { logger } from '../shared/logger.js';
+const debug = process.env.VIBECODE_DEBUG === '1';
+// ============================================================================
+// Functions
+// ============================================================================
+/**
+ * Start the gateway registration + heartbeat loop.
+ *
+ * 1. Attempts initial registration (with retry backoff).
+ * 2. Once registered, sends periodic heartbeats.
+ * 3. If heartbeat fails, re-registers automatically.
+ *
+ * Returns a handle to stop the loop.
+ */
+export async function startGatewayHeartbeat(config) {
+    let stopped = false;
+    let timer = null;
+    // --- Initial registration with backoff ---
+    let registered = false;
+    let backoffMs = 2_000;
+    const maxBackoffMs = 60_000;
+    while (!registered && !stopped) {
+        const result = await registerWithGateway(config);
+        if (result.ok) {
+            registered = true;
+            logger.error(`[gateway] Registered as ${config.nodeId}`);
+            break;
+        }
+        // Wait before retry
+        await new Promise(resolve => {
+            const t = setTimeout(resolve, backoffMs);
+            // Allow stop() to break out of wait
+            if (stopped) {
+                clearTimeout(t);
+                resolve();
+            }
+        });
+        backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+    }
+    // --- Heartbeat loop ---
+    if (registered && !stopped) {
+        const intervalMs = config.heartbeatSecs * 1000;
+        timer = setInterval(async () => {
+            if (stopped)
+                return;
+            const hb = await sendHeartbeat(config);
+            if (!hb.ok) {
+                if (debug)
+                    logger.error('[gateway] Heartbeat failed, re-registering...');
+                const re = await registerWithGateway(config);
+                if (!re.ok && debug) {
+                    logger.error('[gateway] Re-registration failed, will retry next interval');
+                }
+            }
+        }, intervalMs);
+    }
+    return {
+        stop: async () => {
+            stopped = true;
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            await deregisterFromGateway(config);
+            if (debug)
+                logger.error('[gateway] Heartbeat stopped, deregistered');
+        },
+    };
+}

package/build/gateway/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Gateway Module
+ * ==============
+ * Prime gateway registration client for Vibe PM.
+ *
+ * Activation: Set MUSU_PRIME_URL environment variable.
+ *
+ * @module gateway
+ */
+export { isGatewayEnabled, getGatewayConfig, GW_ENV } from './config.js';
+export type { GatewayConfig } from './config.js';
+export { registerWithGateway, sendHeartbeat, deregisterFromGateway } from './client.js';
+export type { RegistrationResult, HeartbeatResult } from './client.js';
+export { startGatewayHeartbeat } from './heartbeat.js';
+export type { HeartbeatHandle } from './heartbeat.js';
+export { registerDispatchRoute } from './dispatch_handler.js';
+export { dispatchViaPrime, pollJobResult } from './prime_dispatch.js';
+export type { DispatchResult } from './prime_dispatch.js';

package/build/gateway/index.js

@@ -0,0 +1,14 @@
+/**
+ * Gateway Module
+ * ==============
+ * Prime gateway registration client for Vibe PM.
+ *
+ * Activation: Set MUSU_PRIME_URL environment variable.
+ *
+ * @module gateway
+ */
+export { isGatewayEnabled, getGatewayConfig, GW_ENV } from './config.js';
+export { registerWithGateway, sendHeartbeat, deregisterFromGateway } from './client.js';
+export { startGatewayHeartbeat } from './heartbeat.js';
+export { registerDispatchRoute } from './dispatch_handler.js';
+export { dispatchViaPrime, pollJobResult } from './prime_dispatch.js';

package/build/gateway/prime_dispatch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Prime Dispatch Client
+ * =====================
+ * Submit work to Musu Prime gateway and poll for results.
+ *
+ * Used by MusuAdapter.submitWork() when MUSU_PRIME_URL is set, routing
+ * work through Prime instead of directly to a Worker node.
+ *
+ * @module gateway/prime_dispatch
+ */
+import type { GatewayConfig } from './config.js';
+export interface DispatchResult {
+    jobId: string;
+    routedTo: string | null;
+}
+/**
+ * Dispatch a work request through Prime gateway.
+ *
+ * Prime creates a PendingJob and returns a job_id. A capable node will
+ * pick up the job via its pull_job loop.
+ */
+export declare function dispatchViaPrime(config: GatewayConfig, capability: string, payload: Record<string, unknown>): Promise<DispatchResult>;
+/**
+ * Poll Prime for a completed job result.
+ *
+ * Uses exponential backoff (100ms initial, 2x, cap 2s).
+ * Returns the result payload when ready, throws on timeout.
+ */
+export declare function pollJobResult(config: GatewayConfig, jobId: string, maxWaitMs?: number): Promise<unknown>;

package/build/gateway/prime_dispatch.js

@@ -0,0 +1,80 @@
+/**
+ * Prime Dispatch Client
+ * =====================
+ * Submit work to Musu Prime gateway and poll for results.
+ *
+ * Used by MusuAdapter.submitWork() when MUSU_PRIME_URL is set, routing
+ * work through Prime instead of directly to a Worker node.
+ *
+ * @module gateway/prime_dispatch
+ */
+import { fetchWithTimeout } from '../shared/http_client.js';
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+function authHeaders(config) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.authToken) {
+        headers['Authorization'] = `Bearer ${config.authToken}`;
+    }
+    return headers;
+}
+// ============================================================================
+// API Functions
+// ============================================================================
+/**
+ * Dispatch a work request through Prime gateway.
+ *
+ * Prime creates a PendingJob and returns a job_id. A capable node will
+ * pick up the job via its pull_job loop.
+ */
+export async function dispatchViaPrime(config, capability, payload) {
+    const url = `${config.primeUrl}/v1/gateway/dispatch`;
+    const body = JSON.stringify({ capability, payload });
+    const resp = await fetchWithTimeout(url, {
+        method: 'POST',
+        headers: authHeaders(config),
+        body,
+    }, config.timeoutMs);
+    if (!resp.ok && resp.status !== 202) {
+        const text = await resp.text().catch(() => '');
+        throw new Error(`Prime dispatch failed: ${resp.status} ${text}`);
+    }
+    const envelope = await resp.json();
+    const jobId = envelope.data?.job_id;
+    if (!jobId) {
+        throw new Error('Prime dispatch response missing job_id');
+    }
+    return {
+        jobId,
+        routedTo: envelope.data?.routed_to ?? null,
+    };
+}
+/**
+ * Poll Prime for a completed job result.
+ *
+ * Uses exponential backoff (100ms initial, 2x, cap 2s).
+ * Returns the result payload when ready, throws on timeout.
+ */
+export async function pollJobResult(config, jobId, maxWaitMs = 30_000) {
+    const url = `${config.primeUrl}/v1/gateway/result/${encodeURIComponent(jobId)}`;
+    const start = Date.now();
+    let backoff = 100;
+    while (Date.now() - start < maxWaitMs) {
+        const resp = await fetchWithTimeout(url, {
+            method: 'GET',
+            headers: authHeaders(config),
+        }, config.timeoutMs);
+        if (!resp.ok) {
+            throw new Error(`Prime result poll failed: ${resp.status}`);
+        }
+        const envelope = await resp.json();
+        if (envelope.signal === 'GO') {
+            return envelope.data?.result ?? null;
+        }
+        // WAIT — sleep with backoff
+        await new Promise(resolve => setTimeout(resolve, backoff));
+        backoff = Math.min(backoff * 2, 2000);
+    }
+    throw new Error(`Job ${jobId} result not ready after ${maxWaitMs}ms`);
+}

package/build/health/readiness.d.ts

@@ -46,6 +46,11 @@ export declare function serverRunningChecker(): ReadinessChecker;
  * Returns true if git is available on the system.
  */
 export declare function gitAvailableChecker(): ReadinessChecker;
+/**
+ * Wrap a readiness checker with a timeout.
+ * If the checker doesn't resolve within `ms`, return not-ready.
+ */
+export declare function withTimeout(checker: ReadinessChecker, ms?: number): ReadinessChecker;
 /**
  * Create a custom readiness checker.
  *

package/build/health/readiness.js

@@ -105,11 +105,34 @@ export function serverRunningChecker() {
  * Returns true if git is available on the system.
  */
 export function gitAvailableChecker() {
-    return () => ({
-        name: CheckNames.GIT_AVAILABLE,
-        ready: true, // Assume git is available if we got this far
-        message: "Git available",
-    });
+    return async () => {
+        try {
+            const { execFileSync } = await import("node:child_process");
+            execFileSync("git", ["--version"], { timeout: 3000, stdio: "ignore" });
+            return { name: CheckNames.GIT_AVAILABLE, ready: true, message: "Git available" };
+        }
+        catch {
+            return { name: CheckNames.GIT_AVAILABLE, ready: false, message: "Git not found or timed out" };
+        }
+    };
+}
+/**
+ * Wrap a readiness checker with a timeout.
+ * If the checker doesn't resolve within `ms`, return not-ready.
+ */
+export function withTimeout(checker, ms = 5000) {
+    return async () => {
+        try {
+            const result = await Promise.race([
+                Promise.resolve(checker()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Health check timeout")), ms)),
+            ]);
+            return result;
+        }
+        catch {
+            return { name: "timeout", ready: false, message: `Check timed out after ${ms}ms` };
+        }
+    };
 }
 /**
  * Create a custom readiness checker.

package/build/hub/autostart.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Hub Autostart
+ * =============
+ *
+ * Singleton autostart for the unified Hub server.
+ * Backward-compatible with VIBE_DASHBOARD=1 and MUSU_COMPANION_ENABLED=1.
+ *
+ * Environment:
+ *   MUSU_HUB_ENABLED=1           — Enable Hub server
+ *   MUSU_HUB_PORT=3100           — Server port
+ *   MUSU_HUB_HOST=127.0.0.1     — Server host
+ *   VIBE_DASHBOARD=1             — Enable Hub (backward compat)
+ *   MUSU_COMPANION_ENABLED=1     — Enable Hub (backward compat)
+ *
+ * @module hub/autostart
+ */
+import type { HubHandle } from './types.js';
+export declare function isHubEnabled(): boolean;
+export declare function startHubIfEnabled(): Promise<HubHandle | null>;
+export declare function shutdownHub(): Promise<void>;
+export declare function getHubHandle(): HubHandle | null;
+export declare function isHubRunning(): boolean;
+export declare function getHubUrl(): string | null;

package/build/hub/autostart.js

@@ -0,0 +1,137 @@
+/**
+ * Hub Autostart
+ * =============
+ *
+ * Singleton autostart for the unified Hub server.
+ * Backward-compatible with VIBE_DASHBOARD=1 and MUSU_COMPANION_ENABLED=1.
+ *
+ * Environment:
+ *   MUSU_HUB_ENABLED=1           — Enable Hub server
+ *   MUSU_HUB_PORT=3100           — Server port
+ *   MUSU_HUB_HOST=127.0.0.1     — Server host
+ *   VIBE_DASHBOARD=1             — Enable Hub (backward compat)
+ *   MUSU_COMPANION_ENABLED=1     — Enable Hub (backward compat)
+ *
+ * @module hub/autostart
+ */
+import { createHubServer } from './server.js';
+import { MusuAdapter } from '../kernel/musu_adapter.js';
+import { logger } from '../shared/logger.js';
+// ============================================================
+// Singleton State
+// ============================================================
+let _handle = null;
+let _startPromise = null;
+let _adapter = null;
+// ============================================================
+// Environment Helpers
+// ============================================================
+export function isHubEnabled() {
+    return (process.env.MUSU_HUB_ENABLED === '1' ||
+        process.env.MUSU_COMPANION_ENABLED === '1' ||
+        process.env.VIBE_DASHBOARD === '1');
+}
+// ============================================================
+// Autostart Functions
+// ============================================================
+export async function startHubIfEnabled() {
+    if (_handle)
+        return _handle;
+    if (_startPromise)
+        return _startPromise;
+    if (!isHubEnabled())
+        return null;
+    _startPromise = (async () => {
+        try {
+            const host = process.env.MUSU_HUB_HOST
+                ?? process.env.MUSU_COMPANION_HOST
+                ?? '127.0.0.1';
+            const port = parseInt(process.env.MUSU_HUB_PORT
+                ?? process.env.MUSU_COMPANION_PORT
+                ?? process.env.VIBE_DASHBOARD_PORT
+                ?? '3100', 10);
+            // Resolve adapter: auto-spawn, connect, or undefined
+            let adapter;
+            if (process.env.MUSU_AUTO_WORKER === '1') {
+                const workerPort = parseInt(process.env.MUSU_WORKER_PORT ?? '8080', 10);
+                adapter = new MusuAdapter(workerPort);
+                try {
+                    await adapter.startWithEphemeral();
+                    _adapter = adapter;
+                    logger.error(`[Hub] Auto-spawned Worker on port ${workerPort}`);
+                }
+                catch (e) {
+                    logger.error(`[Hub] Worker auto-start failed: ${e instanceof Error ? e.message : String(e)}`);
+                    adapter = undefined;
+                }
+            }
+            else if (process.env.MUSU_WORKER_URL) {
+                adapter = MusuAdapter.connectTo(process.env.MUSU_WORKER_URL);
+                _adapter = adapter;
+            }
+            if (!adapter) {
+                logger.warn('[Hub] Worker delegation unavailable — running in stub mode');
+                logger.warn('[Hub] Set MUSU_AUTO_WORKER=1 or MUSU_WORKER_URL=<url> to enable');
+            }
+            _handle = await createHubServer({
+                host,
+                port,
+                storageDir: process.env.VIBE_DASHBOARD_DIR,
+                workspaceRoot: process.env.VIBE_WORKSPACE_ROOT ?? process.cwd(),
+                authToken: process.env.VIBE_CLOUD_SYNC_TOKEN ?? null,
+                bitnetUrl: process.env.MUSU_WORKER_URL,
+                mcpUrl: process.env.MUSU_MCP_URL ??
+                    process.env.MCP_BASE_URL ??
+                    "http://127.0.0.1:3000",
+                bitnetModel: process.env.MUSU_BITNET_MODEL,
+                maxSteps: process.env.MUSU_COMPANION_MAX_STEPS
+                    ? parseInt(process.env.MUSU_COMPANION_MAX_STEPS, 10)
+                    : undefined,
+                adapter,
+            });
+            logger.error(`[Hub] Started on ${_handle.url}`);
+            // First-run profile tip (once per session)
+            if (!process.env.VIBE_PROFILE) {
+                logger.error('[vibe-pm] Tip: Set VIBE_PROFILE=mvp for minimal tools (8), =coding for dev tools (19)');
+            }
+            return _handle;
+        }
+        catch (e) {
+            logger.error(`[Hub] Failed to start: ${e instanceof Error ? e.message : String(e)}`);
+            return null;
+        }
+        finally {
+            _startPromise = null;
+        }
+    })();
+    return _startPromise;
+}
+export async function shutdownHub() {
+    if (_startPromise)
+        await _startPromise;
+    if (!_handle)
+        return;
+    try {
+        await _handle.close();
+        if (_adapter) {
+            await _adapter.stop();
+            _adapter = null;
+        }
+        logger.error(`[Hub] Shutdown complete`);
+    }
+    catch (e) {
+        logger.error(`[Hub] Shutdown error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        _handle = null;
+    }
+}
+export function getHubHandle() {
+    return _handle;
+}
+export function isHubRunning() {
+    return _handle !== null;
+}
+export function getHubUrl() {
+    return _handle?.url ?? null;
+}

package/build/hub/dashboard_routes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dashboard Routes — Fastify plugin porting Dashboard's native HTTP routes.
+ *
+ * Migrated from dashboard/server.ts (native http.createServer)
+ * to Fastify plugin for Hub unification.
+ */
+import type { FastifyInstance } from 'fastify';
+export interface DashboardRoutesOptions {
+    storageDir?: string;
+    workspaceRoot?: string;
+    authToken?: string | null;
+    secretKey?: string | null;
+    maxBodyBytes?: number;
+}
+export declare function registerDashboardRoutes(app: FastifyInstance, opts?: DashboardRoutesOptions): Promise<{
+    signalCleanup: () => void;
+}>;