@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/pool-manager/rust-engine-adapter.js

@@ -0,0 +1,122 @@
+/**
+ * Unified Pool Manager - Rust Engine Adapter
+ * ===========================================
+ *
+ * Adapter for Rust engine servers (vibecoding-helper, vpm-back) in unified pool.
+ *
+ * Key differences from BitNet/Mapper adapters:
+ * - Rust engines are externally managed (Podman Quadlet / systemd)
+ * - No process spawning — workers are always "external"
+ * - Health endpoint is /healthz (vibe-engine-http standard)
+ * - Simple round-robin worker selection (stateless engines)
+ */
+import { BaseWorkerAdapter } from "./adapter.js";
+import { getEngineHealthEndpoint, getHttpManagedEngineEndpoints, } from "../mcp/bootstrap/registry.js";
+/**
+ * Environment variable names for Rust engine pool configuration
+ */
+const RUST_ENGINE_ENV = {
+    HEALTH_POLL_MS: "VIBE_RUST_ENGINE_HEALTH_POLL_MS",
+    TIMEOUT_MS: "VIBE_RUST_ENGINE_TIMEOUT_MS",
+};
+/** Default endpoints derived from ENGINE_SPECS (SSOT) */
+const DEFAULT_ENDPOINTS = getHttpManagedEngineEndpoints();
+function getRustEngineEndpoints() {
+    return getHttpManagedEngineEndpoints();
+}
+function getEnvInt(key, fallback) {
+    const v = parseInt(process.env[key] ?? "", 10);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+/**
+ * Rust engine worker adapter
+ *
+ * Worker selection: simple round-robin (engines are stateless or externally balanced)
+ */
+export class RustEngineAdapter extends BaseWorkerAdapter {
+    type = "rust-engine";
+    rrIndex = 0;
+    getDefaultConfig() {
+        return {
+            type: "rust-engine",
+            minWorkers: 0, // externally managed, no spawning
+            maxWorkers: 0,
+            basePort: 9100,
+            healthPollMs: 10_000,
+            timeoutMs: 60_000,
+            fallbackEnabled: false,
+            externalEndpoints: DEFAULT_ENDPOINTS,
+        };
+    }
+    getConfigFromEnv() {
+        return {
+            healthPollMs: getEnvInt(RUST_ENGINE_ENV.HEALTH_POLL_MS, 10_000),
+            timeoutMs: getEnvInt(RUST_ENGINE_ENV.TIMEOUT_MS, 60_000),
+            externalEndpoints: getRustEngineEndpoints(),
+        };
+    }
+    /**
+     * Rust engines are externally managed — spawning is not supported.
+     * Throws if called (should never happen since minWorkers=0).
+     */
+    async spawnWorker(_port) {
+        throw new Error("RustEngineAdapter does not spawn workers. " +
+            "Rust engines are managed externally via Podman Quadlet / systemd.");
+    }
+    getWorkerBinaryPath() {
+        return "(externally-managed)";
+    }
+    /**
+     * Health endpoint: /healthz (vibe-engine-http standard)
+     */
+    getHealthEndpoint() {
+        return getEngineHealthEndpoint("vibecoding-helper");
+    }
+    /**
+     * Parse /healthz response from vibe-engine-http servers.
+     *
+     * Expected format:
+     * { "engine": "...", "version": "...", "status": "ok" }
+     */
+    parseHealthResponse(raw) {
+        if (typeof raw !== "object" || raw === null) {
+            return { ok: false, type: "rust-engine", metrics: { queue_len: 0, total_requests: 0, uptime_ms: 0 } };
+        }
+        const r = raw;
+        const ok = r.status === "ok" || r.ok === true;
+        return {
+            ok,
+            type: "rust-engine",
+            metrics: {
+                queue_len: typeof r.queue_len === "number" ? r.queue_len : 0,
+                total_requests: typeof r.total_requests === "number" ? r.total_requests : 0,
+                uptime_ms: typeof r.uptime_ms === "number" ? r.uptime_ms : 0,
+            },
+        };
+    }
+    /**
+     * Round-robin worker selection
+     */
+    selectBestWorker(healthy) {
+        if (healthy.length === 0)
+            return null;
+        const idx = this.rrIndex % healthy.length;
+        this.rrIndex = (this.rrIndex + 1) % healthy.length;
+        return healthy[idx];
+    }
+    /**
+     * Rust engines are externally scaled — always return false.
+     */
+    shouldScaleUp(_metrics, _config) {
+        return false;
+    }
+    shouldScaleDown(_metrics, _config) {
+        return false;
+    }
+}
+/**
+ * Factory function
+ */
+export function createRustEngineAdapter() {
+    return new RustEngineAdapter();
+}

package/build/pool-manager/types.d.ts

@@ -9,7 +9,7 @@ import type { ChildProcess } from "node:child_process";
 /**
  * Supported worker types
  */
-export type WorkerType = "bitnet" | "mapper";
+export type WorkerType = "bitnet" | "mapper" | "rust-engine";
 /**
  * Worker status in pool
  */

package/build/pool-manager/unified-pool.js

@@ -6,6 +6,7 @@
  * using adapter pattern for type-specific behavior.
  */
 import { getDefaultAutoscaleConfig, getDefaultCircuitBreakerConfig, isPoolDebugEnabled } from "./types.js";
+import { logger } from '../shared/logger.js';
 /**
  * Unified pool manager
  *
@@ -543,7 +544,7 @@ export class UnifiedPoolManager {
      */
     debug(msg) {
         if (isPoolDebugEnabled()) {
-            console.error(`[UnifiedPool:${this.type}] ${msg}`);
+            logger.debug(`[UnifiedPool:${this.type}] ${msg}`);
         }
     }
     /**

package/build/protocol/index.d.ts

@@ -0,0 +1 @@
+export { PacketTypeSchema, PacketMetaSchema, MusuPacketSchema, type PacketType, type PacketMeta, type MusuPacket, createUserInput, createThought, createToolCall, createToolResult, createFinalAnswer, createSysEvent, encodePacket, decodePacket, encodeSSE, } from './minp.js';

package/build/protocol/index.js

@@ -0,0 +1 @@
+export { PacketTypeSchema, PacketMetaSchema, MusuPacketSchema, createUserInput, createThought, createToolCall, createToolResult, createFinalAnswer, createSysEvent, encodePacket, decodePacket, encodeSSE, } from './minp.js';

package/build/protocol/minp.d.ts

@@ -0,0 +1,97 @@
+/**
+ * MINP — Musu Inter-Node Protocol
+ *
+ * Standard packet format for all Musu system communication:
+ * Companion ↔ Daemon, MCP ↔ Worker, Worker ↔ Worker.
+ *
+ * Design: Telegraphese JSON — keyword-only, no natural language overhead.
+ */
+import { z } from 'zod';
+export declare const PacketTypeSchema: z.ZodEnum<["USER_INPUT", "THOUGHT", "TOOL_CALL", "TOOL_RESULT", "FINAL_ANSWER", "SYS_EVENT", "DELEGATION"]>;
+export type PacketType = z.infer<typeof PacketTypeSchema>;
+export declare const PacketMetaSchema: z.ZodObject<{
+    latency: z.ZodOptional<z.ZodNumber>;
+    token_cost: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    timestamp?: string | undefined;
+    latency?: number | undefined;
+    token_cost?: number | undefined;
+    step?: number | undefined;
+}, {
+    timestamp?: string | undefined;
+    latency?: number | undefined;
+    token_cost?: number | undefined;
+    step?: number | undefined;
+}>;
+export type PacketMeta = z.infer<typeof PacketMetaSchema>;
+export declare const MusuPacketSchema: z.ZodObject<{
+    type: z.ZodEnum<["USER_INPUT", "THOUGHT", "TOOL_CALL", "TOOL_RESULT", "FINAL_ANSWER", "SYS_EVENT", "DELEGATION"]>;
+    head: z.ZodString;
+    body: z.ZodUnknown;
+    meta: z.ZodOptional<z.ZodObject<{
+        latency: z.ZodOptional<z.ZodNumber>;
+        token_cost: z.ZodOptional<z.ZodNumber>;
+        step: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        timestamp?: string | undefined;
+        latency?: number | undefined;
+        token_cost?: number | undefined;
+        step?: number | undefined;
+    }, {
+        timestamp?: string | undefined;
+        latency?: number | undefined;
+        token_cost?: number | undefined;
+        step?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "USER_INPUT" | "THOUGHT" | "TOOL_CALL" | "TOOL_RESULT" | "FINAL_ANSWER" | "SYS_EVENT" | "DELEGATION";
+    head: string;
+    meta?: {
+        timestamp?: string | undefined;
+        latency?: number | undefined;
+        token_cost?: number | undefined;
+        step?: number | undefined;
+    } | undefined;
+    body?: unknown;
+}, {
+    type: "USER_INPUT" | "THOUGHT" | "TOOL_CALL" | "TOOL_RESULT" | "FINAL_ANSWER" | "SYS_EVENT" | "DELEGATION";
+    head: string;
+    meta?: {
+        timestamp?: string | undefined;
+        latency?: number | undefined;
+        token_cost?: number | undefined;
+        step?: number | undefined;
+    } | undefined;
+    body?: unknown;
+}>;
+export type MusuPacket = z.infer<typeof MusuPacketSchema>;
+export declare function createUserInput(body: string): MusuPacket;
+export declare function createThought(head: string, body: unknown): MusuPacket;
+export declare function createToolCall(tool: string, args: unknown): MusuPacket;
+export declare function createToolResult(body: unknown, latency?: number): MusuPacket;
+export declare function createFinalAnswer(head: string, body: unknown, meta?: PacketMeta): MusuPacket;
+export declare function createSysEvent(head: string, body: unknown): MusuPacket;
+export declare function createDelegation(taskId: string, taskType: string, payload: unknown): MusuPacket;
+export declare function createDelegationResult(taskId: string, success: boolean, result: unknown): MusuPacket;
+/**
+ * Encode a MusuPacket to JSON string. Validates schema before encoding.
+ * @throws {z.ZodError} if packet is invalid
+ */
+export declare function encodePacket(packet: MusuPacket): string;
+/**
+ * Decode a JSON string to a MusuPacket. Returns result or error.
+ */
+export declare function decodePacket(raw: string): {
+    ok: true;
+    packet: MusuPacket;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Encode a MusuPacket as an SSE data line.
+ */
+export declare function encodeSSE(packet: MusuPacket): string;

package/build/protocol/minp.js

@@ -0,0 +1,103 @@
+/**
+ * MINP — Musu Inter-Node Protocol
+ *
+ * Standard packet format for all Musu system communication:
+ * Companion ↔ Daemon, MCP ↔ Worker, Worker ↔ Worker.
+ *
+ * Design: Telegraphese JSON — keyword-only, no natural language overhead.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+export const PacketTypeSchema = z.enum([
+    'USER_INPUT',
+    'THOUGHT',
+    'TOOL_CALL',
+    'TOOL_RESULT',
+    'FINAL_ANSWER',
+    'SYS_EVENT',
+    'DELEGATION',
+]);
+export const PacketMetaSchema = z.object({
+    latency: z.number().optional(),
+    token_cost: z.number().optional(),
+    step: z.number().int().optional(),
+    timestamp: z.string().datetime().optional(),
+});
+export const MusuPacketSchema = z.object({
+    type: PacketTypeSchema,
+    head: z.string().min(1),
+    body: z.unknown(),
+    meta: PacketMetaSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// Factory Functions
+// ---------------------------------------------------------------------------
+export function createUserInput(body) {
+    return { type: 'USER_INPUT', head: 'COMMAND', body };
+}
+export function createThought(head, body) {
+    return { type: 'THOUGHT', head, body };
+}
+export function createToolCall(tool, args) {
+    return { type: 'TOOL_CALL', head: 'EXECUTING', body: { tool, args } };
+}
+export function createToolResult(body, latency) {
+    return {
+        type: 'TOOL_RESULT',
+        head: 'OBSERVED',
+        body,
+        ...(latency != null ? { meta: { latency } } : {}),
+    };
+}
+export function createFinalAnswer(head, body, meta) {
+    return { type: 'FINAL_ANSWER', head, body, ...(meta ? { meta } : {}) };
+}
+export function createSysEvent(head, body) {
+    return { type: 'SYS_EVENT', head, body };
+}
+export function createDelegation(taskId, taskType, payload) {
+    return { type: 'DELEGATION', head: 'DELEGATING', body: { task_id: taskId, task_type: taskType, payload } };
+}
+export function createDelegationResult(taskId, success, result) {
+    return {
+        type: 'DELEGATION',
+        head: success ? 'DELEGATION_COMPLETE' : 'DELEGATION_FAILED',
+        body: { task_id: taskId, result },
+    };
+}
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+/**
+ * Encode a MusuPacket to JSON string. Validates schema before encoding.
+ * @throws {z.ZodError} if packet is invalid
+ */
+export function encodePacket(packet) {
+    MusuPacketSchema.parse(packet);
+    return JSON.stringify(packet);
+}
+/**
+ * Decode a JSON string to a MusuPacket. Returns result or error.
+ */
+export function decodePacket(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: 'Invalid JSON' };
+    }
+    const result = MusuPacketSchema.safeParse(parsed);
+    if (!result.success) {
+        return { ok: false, error: result.error.issues.map(i => i.message).join('; ') };
+    }
+    return { ok: true, packet: result.data };
+}
+/**
+ * Encode a MusuPacket as an SSE data line.
+ */
+export function encodeSSE(packet) {
+    return `data: ${JSON.stringify(packet)}\n\n`;
+}

package/build/report-generator.js

@@ -12,6 +12,8 @@
  */
 import * as fs from "fs";
 import * as path from "path";
+import { writeTextFileEnsured } from "./reporting/run_artifacts.js";
+import { logger } from './shared/logger.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -74,9 +76,9 @@ export class ReportGenerator {
         }
         catch (error) {
             // Puppeteer 없으면 HTML로 대체
-            console.warn("[ReportGenerator] Puppeteer not available, falling back to HTML");
+            logger.warn("[ReportGenerator] Puppeteer not available, falling back to HTML");
             const htmlPath = path.join(this.outputDir, `audit_${data.run_id}.html`);
-            fs.writeFileSync(htmlPath, html);
+            writeTextFileEnsured(htmlPath, html);
             return htmlPath;
         }
     }
@@ -516,7 +518,7 @@ _Generated by ${this.companyName}_
     saveHtml(data) {
         const html = this.generateHtml(data);
         const outputPath = path.join(this.outputDir, `audit_${data.run_id}.html`);
-        fs.writeFileSync(outputPath, html);
+        writeTextFileEnsured(outputPath, html);
         return outputPath;
     }
     /**
@@ -525,7 +527,7 @@ _Generated by ${this.companyName}_
     saveMarkdown(data) {
         const md = this.generateMarkdown(data);
         const outputPath = path.join(this.outputDir, `audit_${data.run_id}.md`);
-        fs.writeFileSync(outputPath, md);
+        writeTextFileEnsured(outputPath, md);
         return outputPath;
     }
 }
@@ -744,9 +746,7 @@ export function writeHtmlReportFromCiSummary(ciSummaryPath, opts = {}) {
     const outPath = opts.outputPath ??
         path.join(path.dirname(abs), "report.html"); // `.vibe/runs/<run_id>/ci/report.html`
     const html = generateHtmlFromCiSummary(summary, opts);
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, html, "utf-8");
-    return outPath;
+    return writeTextFileEnsured(outPath, html);
 }
 /**
  * ci_summary.json에서 HTML 리포트 생성 (FAIL-SAFE)
@@ -757,7 +757,7 @@ export function writeHtmlReportFromCiSummarySafe(ciSummaryPath, opts = {}) {
         return writeHtmlReportFromCiSummary(ciSummaryPath, opts);
     }
     catch (error) {
-        console.error(`[report-generator] Failed to generate HTML from ci_summary: ${error instanceof Error ? error.message : error}`);
+        logger.error(`[report-generator] Failed to generate HTML from ci_summary: ${error instanceof Error ? error.message : error}`);
         return null;
     }
 }

package/build/reporting/run_artifacts.d.ts

@@ -0,0 +1,14 @@
+export interface SkeletonSummary {
+    status: 'PRESENT' | 'MISSING' | 'ERROR';
+    artifact_path: string | null;
+    saved_by_skeleton?: number;
+    focus: string | null;
+}
+export interface RunDiagnostics<TSpec = unknown, TClinic = unknown> {
+    specGate: TSpec | null;
+    clinic: TClinic | null;
+}
+export declare function loadRunDiagnostics<TSpec = unknown, TClinic = unknown>(runDir: string): RunDiagnostics<TSpec, TClinic>;
+export declare function loadSkeletonSummary(runDir: string): SkeletonSummary;
+export declare function writeRunMarkdown(runDir: string, relativeOutputPath: string, content: string): string;
+export declare function writeTextFileEnsured(outputPath: string, content: string): string;

package/build/reporting/run_artifacts.js

@@ -0,0 +1,44 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+function safeReadJson(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadRunDiagnostics(runDir) {
+    return {
+        specGate: safeReadJson(path.join(runDir, 'gate', 'spec_gate_result.json')),
+        clinic: safeReadJson(path.join(runDir, 'clinic', 'clinic_result.json')),
+    };
+}
+export function loadSkeletonSummary(runDir) {
+    const skeletonPath = path.join(runDir, 'ci', 'skeleton_map_summary.json');
+    const rawSkeleton = safeReadJson(skeletonPath);
+    if (!rawSkeleton) {
+        return {
+            status: fs.existsSync(skeletonPath) ? 'ERROR' : 'MISSING',
+            artifact_path: null,
+            focus: null,
+        };
+    }
+    return {
+        status: 'PRESENT',
+        artifact_path: skeletonPath,
+        saved_by_skeleton: rawSkeleton.saved_by_skeleton,
+        focus: rawSkeleton.focus ?? null,
+    };
+}
+export function writeRunMarkdown(runDir, relativeOutputPath, content) {
+    const outputPath = path.join(runDir, relativeOutputPath);
+    return writeTextFileEnsured(outputPath, content);
+}
+export function writeTextFileEnsured(outputPath, content) {
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf-8');
+    return outputPath;
+}

package/build/scout/client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Scout Client — Dispatches ScoutTrigger to the Rust Worker HTTP endpoint.
+ *
+ * Usage:
+ *   const client = new ScoutClient('http://localhost:3000', 'my-bearer-token');
+ *   const report = await client.dispatch({ trigger_type: 'dep_shift', payload: { ... } });
+ */
+import type { ScoutTrigger, ScoutReport } from './types.js';
+export declare class ScoutClient {
+    private baseUrl;
+    private bearerToken;
+    constructor(baseUrl: string, bearerToken: string);
+    /**
+     * Dispatch a Scout trigger to the worker and return the analysis report.
+     */
+    dispatch(trigger: ScoutTrigger): Promise<ScoutReport>;
+}

package/build/scout/client.js

@@ -0,0 +1,33 @@
+/**
+ * Scout Client — Dispatches ScoutTrigger to the Rust Worker HTTP endpoint.
+ *
+ * Usage:
+ *   const client = new ScoutClient('http://localhost:3000', 'my-bearer-token');
+ *   const report = await client.dispatch({ trigger_type: 'dep_shift', payload: { ... } });
+ */
+export class ScoutClient {
+    baseUrl;
+    bearerToken;
+    constructor(baseUrl, bearerToken) {
+        this.baseUrl = baseUrl;
+        this.bearerToken = bearerToken;
+    }
+    /**
+     * Dispatch a Scout trigger to the worker and return the analysis report.
+     */
+    async dispatch(trigger) {
+        const res = await fetch(`${this.baseUrl}/v1/scout/dispatch`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.bearerToken}`,
+            },
+            body: JSON.stringify({ trigger }),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Scout dispatch failed: ${res.status} ${text}`);
+        }
+        return res.json();
+    }
+}

package/build/scout/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Scout Module — Re-exports
+ */
+export type { ScoutTrigger, DepShiftTrigger, AuthTouchTrigger, GateFixTrigger, ScoutReport, } from './types.js';
+export { SCENARIO_CODES } from './types.js';
+export { ScoutClient } from './client.js';

package/build/scout/index.js

@@ -0,0 +1,5 @@
+/**
+ * Scout Module — Re-exports
+ */
+export { SCENARIO_CODES } from './types.js';
+export { ScoutClient } from './client.js';

package/build/scout/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Scout Types — TypeScript mirrors of Rust ScoutTrigger / ScoutReport.
+ *
+ * These types are wire-compatible with the Rust `POST /v1/scout/dispatch`
+ * endpoint (serde tag = "trigger_type", content = "payload").
+ */
+export interface DepShiftTrigger {
+    trigger_type: 'dep_shift';
+    payload: {
+        crate_name: string;
+        from_version: string;
+        to_version: string;
+    };
+}
+export interface AuthTouchTrigger {
+    trigger_type: 'auth_touch';
+    payload: {
+        file_path: string;
+        diff_summary: string;
+    };
+}
+export interface GateFixTrigger {
+    trigger_type: 'gate_fix';
+    payload: {
+        issue_id: string;
+        code_diff: string;
+    };
+}
+export type ScoutTrigger = DepShiftTrigger | AuthTouchTrigger | GateFixTrigger;
+/** Scenario codes matching Rust ScoutTrigger::scenario_code() */
+export declare const SCENARIO_CODES: Record<ScoutTrigger['trigger_type'], string>;
+export interface ScoutReport {
+    trigger: ScoutTrigger;
+    scenario: string;
+    block_id: string;
+    root_hash: string;
+    analysis: string;
+    latency_ms: number;
+    tokens: number;
+    timestamp: number;
+}

package/build/scout/types.js

@@ -0,0 +1,12 @@
+/**
+ * Scout Types — TypeScript mirrors of Rust ScoutTrigger / ScoutReport.
+ *
+ * These types are wire-compatible with the Rust `POST /v1/scout/dispatch`
+ * endpoint (serde tag = "trigger_type", content = "payload").
+ */
+/** Scenario codes matching Rust ScoutTrigger::scenario_code() */
+export const SCENARIO_CODES = {
+    dep_shift: 'T6',
+    auth_touch: 'T3',
+    gate_fix: 'T8',
+};

package/build/shared/http_client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared HTTP Client Utilities
+ * ============================
+ * Common fetch helpers used across coordinator and gateway clients.
+ *
+ * @module shared/http_client
+ */
+/**
+ * Fetch with timeout using AbortController.
+ * Rejects with AbortError if the request exceeds `timeoutMs`.
+ */
+export declare function fetchWithTimeout(url: string, options: RequestInit, timeoutMs: number): Promise<Response>;

package/build/shared/http_client.js

@@ -0,0 +1,21 @@
+/**
+ * Shared HTTP Client Utilities
+ * ============================
+ * Common fetch helpers used across coordinator and gateway clients.
+ *
+ * @module shared/http_client
+ */
+/**
+ * Fetch with timeout using AbortController.
+ * Rejects with AbortError if the request exceeds `timeoutMs`.
+ */
+export async function fetchWithTimeout(url, options, timeoutMs) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...options, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(id);
+    }
+}

package/build/shared/logger.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Structured Logger (pino)
+ * ========================
+ *
+ * Centralized JSON logger for Vibe PM.
+ * Replaces raw `console.error()` calls with structured, level-aware logging.
+ *
+ * Usage:
+ *   import { logger } from '../shared/logger.js';
+ *   logger.info({ component: 'mcp' }, 'Server started');
+ *   logger.error({ err }, 'Startup failed');
+ *
+ * In stdio MCP mode, logs go to stderr (pino default destination: fd 2)
+ * so they don't interfere with the JSON-RPC stdout channel.
+ */
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;
+export default logger;