fluidcad 0.0.32 → 0.0.34

package/mcp/dist/tools/source.js

@@ -0,0 +1,434 @@
+// Source-editing tools — let the agent read, write, and walk `.fluid.js`
+// sources inside a workspace. Writes are gated by a dirty-buffer check
+// against the editor extension, atomic via tmp+rename, and confined to the
+// workspace root (symlinks that escape are rejected).
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { findByWorkspace, listLiveInstances } from "../discovery.js";
+import { FluidCadClient, HttpError } from "../client.js";
+import { err, ok } from "../types.js";
+/**
+ * Resolve a workspace argument to a `RegistryEntry`. Distinct from the
+ * inspection-tools variant: source tools rarely need an HTTP client (only
+ * `write_file`/`edit_range` do, and only to probe dirty buffers), so we
+ * return the entry directly and let callers open a client when required.
+ */
+function resolveEntry(input) {
+    if (input?.workspace) {
+        const entry = findByWorkspace(input.workspace);
+        if (!entry) {
+            return err('workspace-not-found', `No running FluidCAD workspace at "${input.workspace}". Call list_workspaces to see what's available.`);
+        }
+        return ok(entry);
+    }
+    const instances = listLiveInstances();
+    if (instances.length === 0) {
+        return err('no-server', 'No running FluidCAD workspaces. Start one with `fluidcad serve`.');
+    }
+    if (instances.length > 1) {
+        return err('no-workspace', `Multiple FluidCAD workspaces are running (${instances.length}). Pass \`workspace\` to disambiguate.`, { workspaces: instances.map((e) => e.workspacePath) });
+    }
+    return ok(instances[0]);
+}
+/**
+ * Resolve a user-supplied path against the workspace root, then verify the
+ * result still lives under the workspace (symlinks included). Returns the
+ * canonical absolute path on success.
+ */
+function resolveWithinWorkspace(workspaceRoot, userPath, { mustExist }) {
+    if (typeof userPath !== 'string' || userPath.length === 0) {
+        return err('invalid-input', '`path` is required and must be a non-empty string.');
+    }
+    const rootReal = (() => {
+        try {
+            return fs.realpathSync(workspaceRoot);
+        }
+        catch {
+            return path.resolve(workspaceRoot);
+        }
+    })();
+    const candidate = path.resolve(rootReal, userPath);
+    let canonical = candidate;
+    try {
+        canonical = fs.realpathSync(candidate);
+    }
+    catch (e) {
+        if (mustExist || e?.code !== 'ENOENT') {
+            if (mustExist) {
+                return err('invalid-input', `File not found: ${userPath}`);
+            }
+            return err('internal', e?.message ?? String(e));
+        }
+        // File doesn't exist yet — for writes, fall back to the parent dir's
+        // realpath so we still catch symlink escape via the parent.
+        const parent = path.dirname(candidate);
+        try {
+            const parentReal = fs.realpathSync(parent);
+            canonical = path.join(parentReal, path.basename(candidate));
+        }
+        catch {
+            // Parent doesn't exist either — keep the resolved candidate; the
+            // boundary check below still catches `..` escapes.
+        }
+    }
+    const rel = path.relative(rootReal, canonical);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        return err('invalid-input', `Path escapes workspace root: ${userPath}`);
+    }
+    return ok({ absPath: canonical, rootReal });
+}
+/**
+ * Static import lint for a `.fluid.js` payload via the server's
+ * `POST /api/lint-fluid-js` endpoint. The server owns the tree-sitter parser
+ * and the FluidCAD symbol table, so MCP stays a thin proxy.
+ *
+ * Failure is non-fatal: if the server endpoint is missing (older release) or
+ * the request errors, the lint is treated as "no missing imports" so writes
+ * still succeed. The render step downstream will catch any resulting
+ * `ReferenceError` if the lint was bypassed.
+ */
+async function lintFluidJsCode(entry, code) {
+    const client = new FluidCadClient(entry);
+    try {
+        const result = await client.postJson('/api/lint-fluid-js', { code });
+        return result;
+    }
+    catch (e) {
+        if (e instanceof HttpError && e.statusCode === 404) {
+            return null;
+        }
+        return null;
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+function isFluidJsPath(absPath) {
+    return absPath.toLowerCase().endsWith('.fluid.js');
+}
+/**
+ * Refuse a write if the post-edit content uses FluidCAD APIs without the
+ * matching `import { … } from "fluidcad/…"` line. Bypassable with
+ * `force: true`, identical to the dirty-buffer guard, since both protect
+ * against the most common "first draft" mistakes LLMs make.
+ */
+async function assertImportsPresent(entry, absPath, code, force) {
+    if (force === true) {
+        return ok(undefined);
+    }
+    if (!isFluidJsPath(absPath)) {
+        return ok(undefined);
+    }
+    const lint = await lintFluidJsCode(entry, code);
+    if (!lint || lint.missing.length === 0) {
+        return ok(undefined);
+    }
+    const symbolList = lint.missing.map((m) => m.symbol).join(', ');
+    return err('missing-imports', [
+        `Refusing to write "${absPath}" — uses ${lint.missing.length} FluidCAD ` +
+            `symbol(s) without an import: ${symbolList}.`,
+        'Add this to the top of the file (pass `force: true` to override):',
+        lint.suggestion,
+    ].join('\n'), { missing: lint.missing, suggestion: lint.suggestion });
+}
+/**
+ * Ask the running FluidCAD server to render `code` for `filePath`. Used by
+ * `write_file` / `edit_range` to make the agent's edit synchronous: the
+ * disk write returns once the render settles, so the caller doesn't need a
+ * separate round-trip to observe completion.
+ *
+ * Non-fatal: any transport error is folded into the outcome as
+ * `render-failed` so the agent still sees the write succeeded.
+ */
+async function triggerRender(entry, filePath, code) {
+    const client = new FluidCadClient(entry);
+    try {
+        const outcome = await client.postJson('/api/render', { filePath, code });
+        return outcome;
+    }
+    catch (e) {
+        if (e instanceof HttpError && e.statusCode === 404) {
+            // Older server without /api/render — silently degrade. The agent still
+            // gets `written: true`; the file watcher (under `fluidcad serve`) or
+            // the next editor save will eventually trigger the render.
+            return { state: 'render-failed', error: 'Server has no /api/render endpoint (upgrade fluidcad).' };
+        }
+        return { state: 'render-failed', error: e?.message ?? String(e) };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+/**
+ * Fetch the editor's dirty-buffer set. Failure to reach the server is
+ * non-fatal — the tool will treat the set as empty so the agent can still
+ * write when the editor extension is not connected. The MCP description
+ * surfaces this caveat.
+ */
+async function fetchDirtyFiles(entry) {
+    const client = new FluidCadClient(entry);
+    try {
+        const dirty = await client.getJson('/api/editor/dirty-files');
+        return Array.isArray(dirty) ? dirty : [];
+    }
+    catch (e) {
+        if (e instanceof HttpError && e.statusCode === 404) {
+            // Older server with no dirty-files endpoint — treat as none dirty.
+            return [];
+        }
+        throw e;
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+function pathsEqual(a, b) {
+    // Best-effort case-insensitive compare on Windows. On Linux/macOS file
+    // systems we still mostly want exact match, but realpath canonicalizes
+    // case on macOS HFS+, so direct `===` is usually enough.
+    if (process.platform === 'win32') {
+        return a.toLowerCase() === b.toLowerCase();
+    }
+    return a === b;
+}
+async function assertNotDirty(entry, absPath, force) {
+    if (force === true) {
+        return ok(undefined);
+    }
+    let dirty;
+    try {
+        dirty = await fetchDirtyFiles(entry);
+    }
+    catch (e) {
+        return err('http-error', `Could not check dirty buffers: ${e?.message ?? String(e)}`);
+    }
+    const conflict = dirty.find((d) => pathsEqual(d.path, absPath));
+    if (conflict) {
+        return err('dirty-buffer', `Refusing to write "${absPath}" — the editor has unsaved changes. Save in the editor, or pass \`force: true\` to overwrite.`, { dirtyFiles: dirty.map((d) => d.path) });
+    }
+    return ok(undefined);
+}
+/**
+ * Atomic file write: write to a sibling tmp file, fsync it, then rename
+ * over the destination. Mirrors `server/src/instance-file.ts` so a crash
+ * mid-write never leaves a half-written `.fluid.js` on disk.
+ */
+async function atomicWrite(absPath, content) {
+    const dir = path.dirname(absPath);
+    await fsp.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(absPath)}.${process.pid}.tmp`);
+    const fh = await fsp.open(tmp, 'w', 0o644);
+    try {
+        await fh.writeFile(content, { encoding: 'utf8' });
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await fsp.rename(tmp, absPath);
+}
+export async function readFile(input) {
+    const entry = resolveEntry(input);
+    if (entry.ok === false) {
+        return entry;
+    }
+    const resolved = resolveWithinWorkspace(entry.data.workspacePath, input?.path, { mustExist: true });
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    try {
+        const content = await fsp.readFile(resolved.data.absPath, 'utf8');
+        return ok({ path: resolved.data.absPath, content });
+    }
+    catch (e) {
+        return err('internal', e?.message ?? String(e));
+    }
+}
+export async function writeFile(input) {
+    if (typeof input?.content !== 'string') {
+        return err('invalid-input', '`content` is required and must be a string.');
+    }
+    const entry = resolveEntry(input);
+    if (entry.ok === false) {
+        return entry;
+    }
+    const resolved = resolveWithinWorkspace(entry.data.workspacePath, input?.path, { mustExist: false });
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    const guard = await assertNotDirty(entry.data, resolved.data.absPath, input.force);
+    if (guard.ok === false) {
+        return guard;
+    }
+    const importGuard = await assertImportsPresent(entry.data, resolved.data.absPath, input.content, input.force);
+    if (importGuard.ok === false) {
+        return importGuard;
+    }
+    try {
+        await atomicWrite(resolved.data.absPath, input.content);
+    }
+    catch (e) {
+        return err('internal', e?.message ?? String(e));
+    }
+    const render = await triggerRender(entry.data, resolved.data.absPath, input.content);
+    return ok({
+        path: resolved.data.absPath,
+        bytesWritten: Buffer.byteLength(input.content, 'utf8'),
+        render,
+    });
+}
+function isValidPosition(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (typeof v.line === 'number' &&
+        Number.isInteger(v.line) &&
+        v.line >= 0 &&
+        typeof v.column === 'number' &&
+        Number.isInteger(v.column) &&
+        v.column >= 0);
+}
+function comparePositions(a, b) {
+    if (a.line !== b.line) {
+        return a.line - b.line;
+    }
+    return a.column - b.column;
+}
+/**
+ * Convert a `{ line, column }` position to a UTF-16 character offset into
+ * `text`. Columns past end-of-line clamp to the line's length; lines past
+ * end-of-file clamp to the file's length. Both behaviours match LSP's
+ * forgiving range semantics and match VSCode's `TextDocument.offsetAt`.
+ */
+function offsetAt(text, pos) {
+    let lineStart = 0;
+    let line = 0;
+    while (line < pos.line) {
+        const nl = text.indexOf('\n', lineStart);
+        if (nl === -1) {
+            return text.length;
+        }
+        lineStart = nl + 1;
+        line++;
+    }
+    const lineEnd = (() => {
+        const nl = text.indexOf('\n', lineStart);
+        return nl === -1 ? text.length : nl;
+    })();
+    return Math.min(lineStart + pos.column, lineEnd);
+}
+export async function editRange(input) {
+    if (typeof input?.newText !== 'string') {
+        return err('invalid-input', '`newText` is required and must be a string.');
+    }
+    if (!isValidPosition(input?.start)) {
+        return err('invalid-input', '`start` must be `{ line: number >= 0, column: number >= 0 }`.');
+    }
+    if (!isValidPosition(input?.end)) {
+        return err('invalid-input', '`end` must be `{ line: number >= 0, column: number >= 0 }`.');
+    }
+    if (comparePositions(input.start, input.end) > 0) {
+        return err('invalid-input', '`start` must be at or before `end`.');
+    }
+    const entry = resolveEntry(input);
+    if (entry.ok === false) {
+        return entry;
+    }
+    const resolved = resolveWithinWorkspace(entry.data.workspacePath, input?.path, { mustExist: true });
+    if (resolved.ok === false) {
+        return resolved;
+    }
+    const guard = await assertNotDirty(entry.data, resolved.data.absPath, input.force);
+    if (guard.ok === false) {
+        return guard;
+    }
+    let original;
+    try {
+        original = await fsp.readFile(resolved.data.absPath, 'utf8');
+    }
+    catch (e) {
+        return err('internal', e?.message ?? String(e));
+    }
+    const startOffset = offsetAt(original, input.start);
+    const endOffset = offsetAt(original, input.end);
+    const next = original.slice(0, startOffset) + input.newText + original.slice(endOffset);
+    const importGuard = await assertImportsPresent(entry.data, resolved.data.absPath, next, input.force);
+    if (importGuard.ok === false) {
+        return importGuard;
+    }
+    try {
+        await atomicWrite(resolved.data.absPath, next);
+    }
+    catch (e) {
+        return err('internal', e?.message ?? String(e));
+    }
+    const render = await triggerRender(entry.data, resolved.data.absPath, next);
+    return ok({
+        path: resolved.data.absPath,
+        bytesWritten: Buffer.byteLength(next, 'utf8'),
+        replacedRange: { start: input.start, end: input.end },
+        render,
+    });
+}
+// ---------------------------------------------------------------------------
+// list_fluid_files
+// ---------------------------------------------------------------------------
+const SKIP_DIRS = new Set(['node_modules', '.git', '.fluidcad', 'dist', 'build']);
+const FLUID_SUFFIX = '.fluid.js';
+const WALK_FILE_LIMIT = 5000;
+export async function listFluidFiles(input) {
+    const entry = resolveEntry(input);
+    if (entry.ok === false) {
+        return entry;
+    }
+    const root = (() => {
+        try {
+            return fs.realpathSync(entry.data.workspacePath);
+        }
+        catch {
+            return path.resolve(entry.data.workspacePath);
+        }
+    })();
+    const files = [];
+    try {
+        await walk(root, root, files);
+    }
+    catch (e) {
+        return err('internal', e?.message ?? String(e));
+    }
+    files.sort();
+    return ok({ files });
+}
+async function walk(root, dir, out) {
+    if (out.length >= WALK_FILE_LIMIT) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= WALK_FILE_LIMIT) {
+            return;
+        }
+        if (e.name.startsWith('.') && e.isDirectory()) {
+            // Hidden dirs (`.git`, `.fluidcad`, …) — always skip.
+            continue;
+        }
+        if (e.isDirectory() && SKIP_DIRS.has(e.name)) {
+            continue;
+        }
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            await walk(root, full, out);
+        }
+        else if (e.isFile() && e.name.endsWith(FLUID_SUFFIX)) {
+            out.push(path.relative(root, full));
+        }
+    }
+}

package/mcp/dist/tools/workspaces.d.ts

@@ -0,0 +1,13 @@
+import { type ToolResult } from '../types.ts';
+export type WorkspaceInfo = {
+    workspacePath: string;
+    port: number;
+    pid: number;
+    version: string;
+    startedAt: string;
+    reachable: boolean;
+};
+export type ListWorkspacesOutput = {
+    workspaces: WorkspaceInfo[];
+};
+export declare function listWorkspaces(): Promise<ToolResult<ListWorkspacesOutput>>;

package/mcp/dist/tools/workspaces.js

@@ -0,0 +1,33 @@
+// Workspace enumeration tool — the agent's entry point for discovery.
+//
+// Returns every running FluidCAD workspace on this machine, with a quick
+// health probe so dead-but-not-yet-pruned entries surface as `reachable: false`
+// instead of being silently dropped.
+import { listLiveInstances } from "../discovery.js";
+import { FluidCadClient } from "../client.js";
+import { ok } from "../types.js";
+export async function listWorkspaces() {
+    const entries = listLiveInstances();
+    const probes = await Promise.all(entries.map(async (entry) => {
+        const client = new FluidCadClient(entry);
+        try {
+            const health = await client.health();
+            return { entry, reachable: health !== null };
+        }
+        finally {
+            // We don't keep clients around past the probe — each tool invocation
+            // re-creates them when needed. Pools are cheap; lingering connections
+            // are not.
+            await client.close().catch(() => { });
+        }
+    }));
+    const workspaces = probes.map(({ entry, reachable }) => ({
+        workspacePath: entry.workspacePath,
+        port: entry.port,
+        pid: entry.pid,
+        version: entry.version,
+        startedAt: entry.startedAt,
+        reachable,
+    }));
+    return ok({ workspaces });
+}

package/mcp/dist/types.d.ts

@@ -0,0 +1,18 @@
+export type { InstanceFile } from '../../server/dist/instance-file.js';
+export type { RegistryEntry } from '../../server/dist/global-registry.js';
+/**
+ * Discriminated result type used by every tool handler so the MCP layer can
+ * render success/failure consistently and the agent can branch on `code`.
+ */
+export type ToolResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    code: ToolErrorCode;
+    message: string;
+    details?: unknown;
+};
+export type ToolErrorCode = 'no-server' | 'no-workspace' | 'workspace-not-found' | 'http-error' | 'ws-error' | 'invalid-input' | 'timeout' | 'compile-error' | 'dirty-buffer' | 'missing-imports' | 'internal';
+export declare function ok<T>(data: T): ToolResult<T>;
+export declare function err(code: ToolErrorCode, message: string, details?: unknown): ToolResult<never>;

package/mcp/dist/types.js

@@ -0,0 +1,11 @@
+// Types shared across the MCP server.
+//
+// We deliberately re-export the discovery types from the server package
+// rather than redefining them — the contract is owned by `server/src/` and
+// imported via the project reference to the built `.d.ts` output.
+export function ok(data) {
+    return { ok: true, data };
+}
+export function err(code, message, details) {
+    return { ok: false, code, message, details };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluidcad",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "description": "Parametric CAD modeling library using javascript",
   "author": "Marwan Aouida <contact@marwan.dev>",
   "homepage": "https://fluidcad.io",
@@ -29,7 +29,9 @@
     "lib/dist/",
     "server/dist/",
     "ui/dist/",
-    "bin/"
+    "mcp/dist/",
+    "bin/",
+    "llm-docs/"
   ],
   "exports": {
     ".": "./lib/dist/index.js",
@@ -40,11 +42,15 @@
     "./math": "./lib/dist/math/index.js"
   },
   "scripts": {
-    "clean": "rm -rf lib/dist server/dist ui/dist lib/tsconfig.tsbuildinfo server/tsconfig.tsbuildinfo",
+    "clean": "rm -rf lib/dist server/dist ui/dist mcp/dist lib/tsconfig.tsbuildinfo server/tsconfig.tsbuildinfo mcp/tsconfig.tsbuildinfo",
     "build:lib": "tsc -p lib/tsconfig.json",
     "build:server": "tsc -p server/tsconfig.json",
     "build:ui": "vite build --config ui/vite.config.ts",
-    "build": "npm run clean && npm run build:lib && npm run build:server && npm run build:ui",
+    "build:mcp": "tsc -p mcp/tsconfig.json",
+    "build:llm-type-docs": "tsx scripts/build-llm-type-docs.ts",
+    "build:llm-docs": "npm run build:llm-type-docs && tsx scripts/build-llm-docs.ts",
+    "check:llm-docs": "npm run build:llm-docs && tsx scripts/check-llm-docs-coverage.ts && vitest run lib/tests/llm-docs-examples.test.ts",
+    "build": "npm run clean && npm run build:lib && npm run build:server && npm run build:ui && npm run build:mcp && npm run build:llm-docs",
     "prepublishOnly": "npm run build",
     "dev:lib": "tsc -p lib/tsconfig.json --watch",
     "dev:server": "node --experimental-transform-types --no-warnings server/src/index.ts",
@@ -55,32 +61,40 @@
     "release": "npx bumpp patch package.json extension/vscode/package.json"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chokidar": "^5.0.0",
     "color-name": "^2.1.0",
+    "commander": "^14.0.3",
     "express": "^5.2.1",
     "occjs-wrapper": "npm:occjs-fluidcad@8.0.0",
+    "open": "^11.0.0",
     "stacktrace-parser": "^0.1.11",
     "tree-sitter-wasms": "^0.1.13",
     "tsx": "^4.21.0",
+    "undici": "^8.3.0",
     "vite": "^8.0.8",
     "web-tree-sitter": "^0.24.7",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@tabler/icons": "^3.40.0",
     "@tailwindcss/vite": "^4.2.2",
     "@types/express": "^5.0.6",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.14.1",
     "@types/three": "^0.180.0",
     "@types/ws": "^8.18.0",
     "camera-controls": "^3.1.2",
     "daisyui": "^5.5.19",
     "eslint": "^9.24.0",
+    "js-yaml": "^4.1.1",
     "lodash": "^4.17.21",
     "prettier": "^3.5.3",
     "tailwindcss": "^4.2.2",
     "three": "^0.180.0",
     "three-viewport-gizmo": "^2.2.0",
+    "ts-morph": "^28.0.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17"
   }

package/server/dist/code-editor.d.ts

@@ -1,3 +1,38 @@
+type TSNode = {
+    type: string;
+    text: string;
+    startPosition: {
+        row: number;
+        column: number;
+    };
+    endPosition: {
+        row: number;
+        column: number;
+    };
+    startIndex: number;
+    endIndex: number;
+    parent: TSNode | null;
+    namedChildren: TSNode[];
+    namedChild(i: number): TSNode | null;
+    childForFieldName(name: string): TSNode | null;
+    descendantForPosition(pos: {
+        row: number;
+        column: number;
+    }): TSNode | null;
+};
+type TSTree = {
+    rootNode: TSNode;
+};
+type TSParser = {
+    setLanguage(lang: any): void;
+    parse(code: string): TSTree;
+};
+/**
+ * Public alias for `getParser()` so other modules in this package (e.g.
+ * `lint-fluid-js.ts`) can reuse the same wasm-backed parser instance instead
+ * of loading the JavaScript grammar twice.
+ */
+export declare function getJavaScriptParser(): Promise<TSParser>;
 export type BreakpointEditResult = {
     newCode: string;
     breakpointLine: number | null;
@@ -19,3 +54,4 @@ export declare function addPick(code: string, sourceLine: number): Promise<CodeE
 export declare function removePick(code: string, sourceLine: number): Promise<CodeEditResult>;
 export declare function removePoint(code: string, sourceLine: number, point: [number, number]): Promise<CodeEditResult>;
 export declare function setPickPoints(code: string, sourceLine: number, points: [number, number][]): Promise<CodeEditResult>;
+export {};

package/server/dist/code-editor.js

@@ -5,6 +5,14 @@ async function loadTreeSitter() {
     return mod.default;
 }
 let parser = null;
+/**
+ * Public alias for `getParser()` so other modules in this package (e.g.
+ * `lint-fluid-js.ts`) can reuse the same wasm-backed parser instance instead
+ * of loading the JavaScript grammar twice.
+ */
+export async function getJavaScriptParser() {
+    return getParser();
+}
 async function getParser() {
     if (parser) {
         return parser;