fluidcad 0.0.32 → 0.0.34

package/mcp/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { WebSocket } from 'ws';
+import type { RegistryEntry } from './types.ts';
+/** Lifecycle ping for one render pass on the server. */
+export type RenderEvent = {
+    version: number;
+    state: 'start' | 'end' | 'error';
+    absPath?: string;
+    /** Local monotonic timestamp when the message was received. */
+    receivedAt: number;
+};
+export type IdleResult = {
+    idleMs: number;
+    lastVersion: number | null;
+};
+export type HealthResponse = {
+    ok: boolean;
+    version: string;
+    workspacePath: string;
+    startedAt: string;
+    pid: number;
+};
+export declare class FluidCadClient {
+    readonly entry: RegistryEntry;
+    private readonly origin;
+    private readonly pool;
+    private ws;
+    private wsOpen;
+    private closed;
+    private lastStartAt;
+    private lastStartVersion;
+    private renderListeners;
+    private wsErrorListeners;
+    constructor(entry: RegistryEntry);
+    /** Quick liveness check. Returns null when the server is unreachable. */
+    health(): Promise<HealthResponse | null>;
+    getJson<T>(path: string): Promise<T>;
+    postJson<T>(path: string, body: unknown): Promise<T>;
+    postRaw(path: string, body: unknown): Promise<{
+        statusCode: number;
+        data: Buffer;
+        contentType: string;
+    }>;
+    ensureWebSocket(): Promise<WebSocket>;
+    /**
+     * Wait until `stableMs` has passed since the last observed render `start`.
+     * Resolves immediately (with `idleMs = stableMs`) if no `start` has been
+     * seen since subscription opened.
+     */
+    nextIdle(stableMs: number, timeoutMs: number): Promise<IdleResult>;
+    close(): Promise<void>;
+    private handleWsMessage;
+    private notifyWsError;
+}
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class WsError extends Error {
+    constructor(message: string);
+}
+export declare class HttpError extends Error {
+    readonly statusCode: number;
+    readonly body: string;
+    constructor(statusCode: number, body: string);
+}

package/mcp/dist/client.js

@@ -0,0 +1,248 @@
+// HTTP+WS client against a running FluidCadServer.
+//
+// Owned by the MCP process, one instance per workspace it talks to. Holds an
+// undici Pool keyed by the server's origin and a lazily-opened WebSocket for
+// streaming notifications. The future per-instance auth header would land
+// here (and only here).
+import { Pool } from 'undici';
+import { WebSocket } from 'ws';
+const HEALTH_PROBE_TIMEOUT_MS = 500;
+export class FluidCadClient {
+    entry;
+    origin;
+    pool;
+    ws = null;
+    wsOpen = null;
+    closed = false;
+    // Render-event tracking. Latest `start` timestamp is kept so wait-for-idle
+    // can answer "stable for at least N ms" without re-subscribing each call.
+    // Listeners receive every render-version message.
+    lastStartAt = null;
+    lastStartVersion = null;
+    renderListeners = new Set();
+    wsErrorListeners = new Set();
+    constructor(entry) {
+        this.entry = entry;
+        this.origin = `http://127.0.0.1:${entry.port}`;
+        this.pool = new Pool(this.origin, { connections: 4 });
+    }
+    /** Quick liveness check. Returns null when the server is unreachable. */
+    async health() {
+        try {
+            const res = await this.pool.request({
+                path: '/api/health',
+                method: 'GET',
+                bodyTimeout: HEALTH_PROBE_TIMEOUT_MS,
+                headersTimeout: HEALTH_PROBE_TIMEOUT_MS,
+            });
+            if (res.statusCode !== 200) {
+                return null;
+            }
+            const body = await res.body.json();
+            return body;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getJson(path) {
+        const res = await this.pool.request({ path, method: 'GET' });
+        return readJsonBody(res);
+    }
+    async postJson(path, body) {
+        const res = await this.pool.request({
+            path,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body ?? {}),
+        });
+        return readJsonBody(res);
+    }
+    async postRaw(path, body) {
+        const res = await this.pool.request({
+            path,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body ?? {}),
+        });
+        const chunks = [];
+        for await (const chunk of res.body) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        const contentType = String(res.headers['content-type'] ?? 'application/octet-stream');
+        return { statusCode: res.statusCode, data: Buffer.concat(chunks), contentType };
+    }
+    async ensureWebSocket() {
+        if (this.closed) {
+            throw new Error('Client is closed.');
+        }
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            return this.ws;
+        }
+        if (this.wsOpen) {
+            return this.wsOpen;
+        }
+        const url = `ws://127.0.0.1:${this.entry.port}`;
+        const socket = new WebSocket(url);
+        this.ws = socket;
+        this.wsOpen = new Promise((resolve, reject) => {
+            const onOpen = () => {
+                cleanup();
+                resolve(socket);
+            };
+            const onError = (err) => {
+                cleanup();
+                this.ws = null;
+                this.wsOpen = null;
+                this.notifyWsError(err);
+                reject(err);
+            };
+            const cleanup = () => {
+                socket.off('open', onOpen);
+                socket.off('error', onError);
+            };
+            socket.once('open', onOpen);
+            socket.once('error', onError);
+        });
+        socket.on('message', (raw) => this.handleWsMessage(String(raw)));
+        socket.on('close', () => {
+            if (this.ws === socket) {
+                this.ws = null;
+                this.wsOpen = null;
+            }
+            // Surface a close as an error to anyone currently awaiting events. They
+            // can retry; the next call will reconnect lazily.
+            this.notifyWsError(new Error('WebSocket closed.'));
+        });
+        return this.wsOpen;
+    }
+    /**
+     * Wait until `stableMs` has passed since the last observed render `start`.
+     * Resolves immediately (with `idleMs = stableMs`) if no `start` has been
+     * seen since subscription opened.
+     */
+    async nextIdle(stableMs, timeoutMs) {
+        await this.ensureWebSocket();
+        return new Promise((resolve, reject) => {
+            const subscribeAt = nowMs();
+            let latestStartAt = this.lastStartAt;
+            let latestStartVersion = this.lastStartVersion;
+            const cleanup = () => {
+                clearTimeout(idleTimer);
+                clearTimeout(deadlineTimer);
+                this.renderListeners.delete(onEvent);
+                this.wsErrorListeners.delete(onError);
+            };
+            const settle = () => {
+                cleanup();
+                const last = latestStartAt ?? subscribeAt;
+                resolve({
+                    idleMs: Math.max(0, nowMs() - last),
+                    lastVersion: latestStartVersion,
+                });
+            };
+            const armIdleTimer = (since) => {
+                clearTimeout(idleTimer);
+                const remaining = Math.max(0, stableMs - (nowMs() - since));
+                idleTimer = setTimeout(settle, remaining);
+            };
+            let idleTimer = setTimeout(settle, stableMs);
+            const deadlineTimer = setTimeout(() => {
+                cleanup();
+                reject(new TimeoutError(`Not idle for ${stableMs}ms within ${timeoutMs}ms.`));
+            }, timeoutMs);
+            const onEvent = (event) => {
+                if (event.state !== 'start') {
+                    return;
+                }
+                latestStartAt = event.receivedAt;
+                latestStartVersion = event.version;
+                armIdleTimer(event.receivedAt);
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(new WsError(err.message));
+            };
+            this.renderListeners.add(onEvent);
+            this.wsErrorListeners.add(onError);
+        });
+    }
+    async close() {
+        this.closed = true;
+        this.renderListeners.clear();
+        this.wsErrorListeners.clear();
+        if (this.ws) {
+            this.ws.removeAllListeners('close');
+            this.ws.close();
+            this.ws = null;
+            this.wsOpen = null;
+        }
+        await this.pool.close();
+    }
+    handleWsMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!msg || msg.type !== 'render-version' || typeof msg.version !== 'number') {
+            return;
+        }
+        const state = msg.state;
+        if (state !== 'start' && state !== 'end' && state !== 'error') {
+            return;
+        }
+        const event = {
+            version: msg.version,
+            state,
+            absPath: typeof msg.absPath === 'string' ? msg.absPath : undefined,
+            receivedAt: nowMs(),
+        };
+        if (state === 'start') {
+            this.lastStartAt = event.receivedAt;
+            this.lastStartVersion = event.version;
+        }
+        for (const listener of [...this.renderListeners]) {
+            listener(event);
+        }
+    }
+    notifyWsError(err) {
+        for (const listener of [...this.wsErrorListeners]) {
+            listener(err);
+        }
+    }
+}
+function nowMs() {
+    return Number(process.hrtime.bigint() / 1000000n);
+}
+export class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+export class WsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WsError';
+    }
+}
+async function readJsonBody(res) {
+    if (res.statusCode >= 400) {
+        const text = await res.body.text();
+        throw new HttpError(res.statusCode, text);
+    }
+    return await res.body.json();
+}
+export class HttpError extends Error {
+    statusCode;
+    body;
+    constructor(statusCode, body) {
+        super(`HTTP ${statusCode}: ${body.slice(0, 200)}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.name = 'HttpError';
+    }
+}

package/mcp/dist/discovery.d.ts

@@ -0,0 +1,11 @@
+import type { RegistryEntry } from './types.ts';
+export declare function registryFilePath(): string;
+/**
+ * Read the on-disk registry and return entries whose PID is still alive.
+ *
+ * Unlike the server-side `readInstances()`, this never writes back the pruned
+ * set — a read-only MCP process should not modify shared global state.
+ */
+export declare function listLiveInstances(): RegistryEntry[];
+export declare function findByWorkspace(workspacePath: string): RegistryEntry | null;
+export declare function isPidAlive(pid: number): boolean;

package/mcp/dist/discovery.js

@@ -0,0 +1,78 @@
+// Read-only access to the FluidCAD instance registry.
+//
+// The MCP process never writes the registry — that's owned by the server.
+// We re-implement just the read path here so the MCP package doesn't depend
+// on the entire server package surface.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const REGISTRY_DIR_NAME = '.fluidcad';
+const REGISTRY_FILE_NAME = 'instances.json';
+export function registryFilePath() {
+    return path.join(os.homedir(), REGISTRY_DIR_NAME, REGISTRY_FILE_NAME);
+}
+/**
+ * Read the on-disk registry and return entries whose PID is still alive.
+ *
+ * Unlike the server-side `readInstances()`, this never writes back the pruned
+ * set — a read-only MCP process should not modify shared global state.
+ */
+export function listLiveInstances() {
+    const file = readRegistryFile();
+    return file.instances.filter((entry) => isPidAlive(entry.pid));
+}
+export function findByWorkspace(workspacePath) {
+    for (const entry of listLiveInstances()) {
+        if (entry.workspacePath === workspacePath) {
+            return entry;
+        }
+    }
+    return null;
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err && err.code === 'EPERM') {
+            return true;
+        }
+        return false;
+    }
+}
+const EMPTY = { schemaVersion: 1, instances: [] };
+function readRegistryFile() {
+    try {
+        const raw = fs.readFileSync(registryFilePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isRegistryFile(parsed)) {
+            return parsed;
+        }
+        return EMPTY;
+    }
+    catch {
+        return EMPTY;
+    }
+}
+function isRegistryFile(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    if (v.schemaVersion !== 1 || !Array.isArray(v.instances)) {
+        return false;
+    }
+    return v.instances.every(isRegistryEntry);
+}
+function isRegistryEntry(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (typeof v.workspacePath === 'string' &&
+        typeof v.port === 'number' &&
+        typeof v.pid === 'number' &&
+        typeof v.version === 'string' &&
+        typeof v.startedAt === 'string');
+}

package/mcp/dist/docs-index.d.ts

@@ -0,0 +1,81 @@
+export type DocRecord = {
+    id: string;
+    title: string;
+    summary: string;
+    tags?: string[];
+    symbols?: string[];
+    seeAlso?: string[];
+    file: string;
+    bodyLength: number;
+};
+type IndexFile = {
+    schemaVersion: 1;
+    generatedAt: string;
+    docs: DocRecord[];
+};
+type ApiIndexFile = {
+    schemaVersion: 1;
+    generatedAt: string;
+    symbols: Record<string, string>;
+};
+export type SearchHit = {
+    id: string;
+    title: string;
+    snippet: string;
+    score: number;
+};
+export declare class DocsIndex {
+    /** Absolute path to the docs root directory. */
+    readonly root: string;
+    /** Every doc record, in the order they were emitted by the build script. */
+    readonly docs: ReadonlyArray<DocRecord>;
+    /** Symbol -> docId (from `llm-docs/api/index.json`). */
+    readonly symbols: Readonly<Record<string, string>>;
+    /**
+     * Type-name -> docId, restricted to docs under `api/types/`. Populated by
+     * filtering `symbols` so the same symbol map drives both `get_api_signature`
+     * and `get_type_definition`, but the latter rejects function symbols with a
+     * clear "not a type" error rather than returning a feature signature.
+     */
+    readonly types: Readonly<Record<string, string>>;
+    private readonly byId;
+    private readonly bodyCache;
+    /** token -> docId -> per-field hit counts. */
+    private readonly inverted;
+    constructor(root: string, index: IndexFile, apiIndex: ApiIndexFile);
+    /** All docs, optionally filtered to those carrying a given tag. */
+    list(tag?: string): DocRecord[];
+    get(id: string): DocRecord | null;
+    /**
+     * Load the markdown body for a doc id, stripping the YAML frontmatter so
+     * callers see the same text the docs author wrote (no metadata clutter).
+     */
+    body(id: string): string | null;
+    /** Keyword search. Returns ranked hits with an ~80-char snippet per result. */
+    search(query: string, limit?: number): SearchHit[];
+    /** First fenced code block in the body, used as a symbol's signature surface. */
+    firstCodeBlock(id: string): string | null;
+    private buildInverted;
+    private snippet;
+}
+/**
+ * Locate the on-disk `llm-docs/` directory.
+ *
+ * Resolution order:
+ *   1. The installed package — `require.resolve('fluidcad/package.json')` gives
+ *      us the consumer's `node_modules/fluidcad/`, and `llm-docs/` sits next to
+ *      that `package.json`.
+ *   2. The in-repo path — walk up from this file (`mcp/src/` or `mcp/dist/`)
+ *      until we hit a sibling `llm-docs/` directory.
+ *
+ * We never trust `process.cwd()`: the MCP process is launched by an external
+ * client (Claude Desktop, etc.) so its CWD is whatever they happen to be in.
+ */
+export declare function resolveDocsRoot(): string;
+/**
+ * Load the manifests from `<root>/index.json` and `<root>/api/index.json` and
+ * construct the in-memory index. Throws (with a helpful message) if either
+ * manifest is missing — that almost always means `build:llm-docs` was skipped.
+ */
+export declare function loadDocsIndex(root?: string): DocsIndex;
+export {};