fluidcad 0.0.32 → 0.0.34

package/server/dist/lint-fluid-js.js

@@ -0,0 +1,271 @@
+// Static import linter for `.fluid.js` sources.
+//
+// LLMs frequently emit a first draft that uses FluidCAD APIs (`sketch`,
+// `extrude`, `face`, …) without an `import { … } from "fluidcad/core"` line —
+// the script then explodes at runtime with `ReferenceError`. The MCP server
+// calls this linter before writing a `.fluid.js` file so the agent gets a
+// precise error pointing at the missing symbols instead of a confusing
+// render failure.
+//
+// Tree-sitter (web-tree-sitter + tree-sitter-wasms) is reused — the parser
+// instance is the same singleton the param editor in `code-editor.ts` uses.
+// Doing it that way means we don't double-load the JavaScript wasm grammar.
+import { getJavaScriptParser } from "./code-editor.js";
+// Authoritative FluidCAD symbol→module map. Mirrors the exports in
+// `lib/core/index.ts`, `lib/core/2d/index.ts`, `lib/filters/index.ts`, and
+// `lib/features/2d/constraints/geometry-qualifier.ts`. If a new public symbol
+// is added there, add it here too — the import lint is the wall the LLM
+// hits, so keep it accurate.
+const CORE_SYMBOLS = new Set([
+    'axis', 'local', 'plane', 'sketch', 'fuse', 'subtract', 'common',
+    'cut', 'revolve', 'extrude', 'sphere', 'cylinder', 'select', 'shell',
+    'chamfer', 'fillet', 'translate', 'rotate', 'mirror', 'copy', 'repeat',
+    'load', 'loft', 'sweep', 'rib', 'color', 'draft', 'remove', 'split',
+    'trim', 'part', 'breakpoint',
+    'line', 'circle', 'ellipse', 'rect', 'hMove', 'vMove', 'rMove',
+    'hLine', 'vLine', 'tLine', 'tCircle', 'tArc', 'arc', 'move', 'pMove',
+    'aLine', 'slot', 'connect', 'polygon', 'offset', 'project', 'intersect',
+    'bezier', 'center', 'back',
+]);
+const FILTER_SYMBOLS = new Set(['face', 'edge']);
+const CONSTRAINT_SYMBOLS = new Set([
+    'outside', 'enclosed', 'enclosing', 'unqualified',
+]);
+const MODULE_FOR_SYMBOL = new Map();
+for (const s of CORE_SYMBOLS) {
+    MODULE_FOR_SYMBOL.set(s, 'fluidcad/core');
+}
+for (const s of FILTER_SYMBOLS) {
+    MODULE_FOR_SYMBOL.set(s, 'fluidcad/filters');
+}
+for (const s of CONSTRAINT_SYMBOLS) {
+    MODULE_FOR_SYMBOL.set(s, 'fluidcad/constraints');
+}
+/**
+ * Walk every named child recursively, invoking `visit` once per node. The
+ * walker stops descending into a subtree when `visit` returns `false`.
+ */
+function walk(node, visit) {
+    const cont = visit(node);
+    if (cont === false) {
+        return;
+    }
+    for (const child of node.namedChildren) {
+        walk(child, visit);
+    }
+}
+/**
+ * Determine whether `node` (an `identifier`) is at a position the JS spec
+ * treats as a *reference* (would throw `ReferenceError` if unbound) vs a
+ * *binding* (a declared name) vs a *property name* (never a reference at
+ * all).
+ *
+ * Tree-sitter's JavaScript grammar has distinct node types for some of
+ * these (`property_identifier`, `shorthand_property_identifier_pattern`,
+ * etc.), but plain `identifier` nodes still cover a lot of ground and we
+ * have to look at parent context to classify them.
+ */
+function isReferenceUse(node) {
+    if (node.type !== 'identifier') {
+        return false;
+    }
+    const parent = node.parent;
+    if (!parent) {
+        return true;
+    }
+    switch (parent.type) {
+        case 'import_specifier':
+        case 'namespace_import':
+        case 'import_clause':
+        case 'import_statement':
+            // Anything inside an `import` statement is bookkeeping, not a use.
+            return false;
+        case 'variable_declarator': {
+            // `const X = ...` → the `name` field is a binding.
+            const nameField = parent.childForFieldName('name');
+            if (nameField && nameField.startIndex === node.startIndex) {
+                return false;
+            }
+            return true;
+        }
+        case 'function_declaration':
+        case 'function_expression':
+        case 'generator_function_declaration':
+        case 'class_declaration':
+        case 'class_expression':
+        case 'method_definition': {
+            const nameField = parent.childForFieldName('name');
+            if (nameField && nameField.startIndex === node.startIndex) {
+                return false;
+            }
+            return true;
+        }
+        case 'formal_parameters':
+        case 'required_parameter':
+        case 'optional_parameter':
+        case 'rest_pattern':
+            // Parameter names are bindings.
+            return false;
+        case 'arrow_function': {
+            // `(x) => …` or `x => …` — parameter is a binding when it's the
+            // function's `parameter` field.
+            const param = parent.childForFieldName('parameter');
+            if (param && param.startIndex === node.startIndex) {
+                return false;
+            }
+            return true;
+        }
+        case 'member_expression': {
+            // `obj.foo` — the `property` field is a name lookup, not a reference.
+            const prop = parent.childForFieldName('property');
+            if (prop && prop.startIndex === node.startIndex) {
+                return false;
+            }
+            return true;
+        }
+        case 'pair': {
+            // `{ key: value }` — `key` (if an identifier) is a property name.
+            const key = parent.childForFieldName('key');
+            if (key && key.startIndex === node.startIndex) {
+                return false;
+            }
+            return true;
+        }
+        case 'property_signature':
+        case 'public_field_definition':
+            // Class/object field declarations — the name slot is a binding.
+            return false;
+        case 'labeled_statement':
+            // `label: stmt` — labels are not references.
+            return false;
+    }
+    return true;
+}
+/**
+ * Walk an `import_statement` and collect every name it locally binds.
+ * Handles:
+ *   - `import x from "…"`               (default)
+ *   - `import { a, b as c } from "…"`   (named, with renaming)
+ *   - `import x, { a } from "…"`        (default + named)
+ *   - `import * as ns from "…"`         (namespace)
+ *   - `import "…"`                      (side-effect, binds nothing)
+ */
+function collectImportedNames(importNode, into) {
+    walk(importNode, (n) => {
+        if (n.type === 'import_specifier') {
+            // `{ a as b }` → `alias` field (b) is what binds; otherwise `name` (a).
+            const alias = n.childForFieldName('alias');
+            const name = n.childForFieldName('name');
+            const local = alias ?? name;
+            if (local && local.type === 'identifier') {
+                into.add(local.text);
+            }
+            return false;
+        }
+        if (n.type === 'namespace_import') {
+            const id = n.namedChildren.find((c) => c.type === 'identifier');
+            if (id) {
+                into.add(id.text);
+            }
+            return false;
+        }
+        if (n.type === 'import_clause') {
+            // The default import (if any) is a direct `identifier` child.
+            for (const child of n.namedChildren) {
+                if (child.type === 'identifier') {
+                    into.add(child.text);
+                }
+            }
+        }
+    });
+}
+/**
+ * Collect names that are bound at the top level of the program: `const`,
+ * `let`, `var`, `function`, `class`. Used so user code like
+ * `const sketch = …` shadows the FluidCAD `sketch` without tripping the
+ * lint. We deliberately keep this top-level-only to keep the implementation
+ * simple — local shadowing inside a function is rare in `.fluid.js` files.
+ */
+function collectTopLevelDeclaredNames(root, into) {
+    for (const stmt of root.namedChildren) {
+        if (stmt.type === 'variable_declaration' || stmt.type === 'lexical_declaration') {
+            for (const decl of stmt.namedChildren) {
+                if (decl.type !== 'variable_declarator') {
+                    continue;
+                }
+                const name = decl.childForFieldName('name');
+                if (name && name.type === 'identifier') {
+                    into.add(name.text);
+                }
+                // Destructuring (`const { a, b } = …`) — pick up shorthand pattern names.
+                if (name) {
+                    walk(name, (n) => {
+                        if (n.type === 'shorthand_property_identifier_pattern' ||
+                            n.type === 'identifier') {
+                            if (n.parent && n.parent.type !== 'pair_pattern') {
+                                into.add(n.text);
+                            }
+                        }
+                    });
+                }
+            }
+        }
+        if (stmt.type === 'function_declaration' || stmt.type === 'class_declaration') {
+            const name = stmt.childForFieldName('name');
+            if (name && name.type === 'identifier') {
+                into.add(name.text);
+            }
+        }
+    }
+}
+export async function lintFluidJs(code) {
+    const parser = await getJavaScriptParser();
+    const tree = parser.parse(code);
+    const root = tree.rootNode;
+    const bound = new Set();
+    for (const stmt of root.namedChildren) {
+        if (stmt.type === 'import_statement') {
+            collectImportedNames(stmt, bound);
+        }
+    }
+    collectTopLevelDeclaredNames(root, bound);
+    const missingByName = new Map();
+    walk(root, (n) => {
+        if (n.type === 'import_statement') {
+            return false;
+        }
+        if (n.type !== 'identifier') {
+            return;
+        }
+        if (!MODULE_FOR_SYMBOL.has(n.text)) {
+            return;
+        }
+        if (bound.has(n.text)) {
+            return;
+        }
+        if (!isReferenceUse(n)) {
+            return;
+        }
+        if (missingByName.has(n.text)) {
+            return;
+        }
+        missingByName.set(n.text, {
+            symbol: n.text,
+            module: MODULE_FOR_SYMBOL.get(n.text),
+            line: n.startPosition.row,
+            column: n.startPosition.column,
+        });
+    });
+    const sorted = Array.from(missingByName.values()).sort((a, b) => a.symbol.localeCompare(b.symbol));
+    const byModule = new Map();
+    for (const m of sorted) {
+        const list = byModule.get(m.module) ?? [];
+        list.push(m.symbol);
+        byModule.set(m.module, list);
+    }
+    const suggestion = Array.from(byModule.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([mod, syms]) => `import { ${syms.join(', ')} } from "${mod}";`)
+        .join('\n');
+    return { missing: sorted, suggestion };
+}

package/server/dist/routes/editor.d.ts

@@ -0,0 +1,24 @@
+import { Router } from 'express';
+export type DirtyFileEntry = {
+    /** Absolute, normalized path of the dirty file. */
+    path: string;
+    /** Editor-observed mtime when the file was last seen on disk, or 0 if unknown. */
+    lastModifiedMs: number;
+};
+/**
+ * Holds the set of files the editor currently considers dirty (unsaved
+ * changes). The MCP source-editing tools query this before writing so a
+ * remote agent never silently clobbers a user's in-flight changes.
+ *
+ * The set is volatile by design — it gets replaced wholesale on every
+ * `editor-dirty-state` IPC and resets when the server restarts. Editors
+ * resend their state on startup.
+ */
+export declare class DirtyBufferState {
+    private files;
+    setDirtyFiles(paths: string[]): void;
+    list(): DirtyFileEntry[];
+    isDirty(absPath: string): boolean;
+    private readMtime;
+}
+export declare function createEditorRouter(state: DirtyBufferState): Router;

package/server/dist/routes/editor.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import { Router } from 'express';
+import { normalizePath } from "../normalize-path.js";
+/**
+ * Holds the set of files the editor currently considers dirty (unsaved
+ * changes). The MCP source-editing tools query this before writing so a
+ * remote agent never silently clobbers a user's in-flight changes.
+ *
+ * The set is volatile by design — it gets replaced wholesale on every
+ * `editor-dirty-state` IPC and resets when the server restarts. Editors
+ * resend their state on startup.
+ */
+export class DirtyBufferState {
+    files = new Map();
+    setDirtyFiles(paths) {
+        const next = new Map();
+        for (const p of paths) {
+            const normalized = normalizePath(p);
+            next.set(normalized, this.readMtime(normalized));
+        }
+        this.files = next;
+    }
+    list() {
+        return Array.from(this.files, ([path, lastModifiedMs]) => ({ path, lastModifiedMs }));
+    }
+    isDirty(absPath) {
+        return this.files.has(normalizePath(absPath));
+    }
+    readMtime(absPath) {
+        try {
+            return fs.statSync(absPath).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+export function createEditorRouter(state) {
+    const router = Router();
+    router.get('/editor/dirty-files', (_req, res) => {
+        res.json(state.list());
+    });
+    return router;
+}

package/server/dist/routes/export.d.ts

@@ -1,3 +1,3 @@
 import { Router } from 'express';
 import type { FluidCadServer } from '../fluidcad-server.ts';
-export declare function createExportRouter(fluidCadServer: FluidCadServer): Router;
+export declare function createExportRouter(fluidCadServer: FluidCadServer, workspacePath: string): Router;

package/server/dist/routes/export.js

@@ -1,8 +1,20 @@
+import fs from 'fs';
+import path from 'path';
 import { Router } from 'express';
-export function createExportRouter(fluidCadServer) {
+export function createExportRouter(fluidCadServer, workspacePath) {
     const router = Router();
+    // Resolve the workspace root once so symlink checks below match the path
+    // we actually allow writes into.
+    const workspaceRoot = (() => {
+        try {
+            return fs.realpathSync(workspacePath);
+        }
+        catch {
+            return path.resolve(workspacePath);
+        }
+    })();
     router.post('/export', (req, res) => {
-        const { format, shapeIds, includeColors, resolution, customAngularDeflectionDeg, customLinearDeflection } = req.body;
+        const { format, shapeIds, includeColors, resolution, customAngularDeflectionDeg, customLinearDeflection, saveAsPath } = req.body;
         if (format !== 'step' && format !== 'stl') {
             res.status(400).json({ error: 'Invalid format. Must be "step" or "stl".' });
             return;
@@ -24,6 +36,10 @@ export function createExportRouter(fluidCadServer) {
                 }
             }
         }
+        if (saveAsPath !== undefined && typeof saveAsPath !== 'string') {
+            res.status(400).json({ error: 'saveAsPath must be a string.' });
+            return;
+        }
         try {
             const result = fluidCadServer.exportShapes(shapeIds, {
                 format,
@@ -38,14 +54,35 @@ export function createExportRouter(fluidCadServer) {
             }
             const ext = format === 'step' ? '.step' : '.stl';
             const mimeType = format === 'step' ? 'application/step' : 'application/sla';
+            const bytes = typeof result.data === 'string'
+                ? Buffer.from(result.data, 'utf-8')
+                : Buffer.from(result.data);
+            if (saveAsPath) {
+                // Resolve against the workspace root, then verify the canonical path
+                // (after symlink resolution of the parent) still lives inside it.
+                const candidate = path.resolve(workspaceRoot, saveAsPath);
+                const parent = path.dirname(candidate);
+                let parentReal;
+                try {
+                    parentReal = fs.realpathSync(parent);
+                }
+                catch {
+                    res.status(400).json({ error: `Parent directory does not exist: ${parent}` });
+                    return;
+                }
+                const canonical = path.join(parentReal, path.basename(candidate));
+                const rel = path.relative(workspaceRoot, canonical);
+                if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                    res.status(400).json({ error: `saveAsPath escapes workspace root: ${saveAsPath}` });
+                    return;
+                }
+                fs.writeFileSync(canonical, bytes);
+                res.json({ savedTo: canonical, bytesWritten: bytes.length });
+                return;
+            }
             res.setHeader('Content-Type', mimeType);
             res.setHeader('Content-Disposition', `attachment; filename="export${ext}"`);
-            if (typeof result.data === 'string') {
-                res.send(Buffer.from(result.data, 'utf-8'));
-            }
-            else {
-                res.send(Buffer.from(result.data));
-            }
+            res.send(bytes);
         }
         catch (err) {
             res.status(500).json({ error: err.message || String(err) });

package/server/dist/routes/health.d.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+export type HealthInfo = {
+    version: string;
+    workspacePath: string;
+    startedAt: string;
+};
+export declare function createHealthRouter(info: HealthInfo): Router;

package/server/dist/routes/health.js

@@ -0,0 +1,14 @@
+import { Router } from 'express';
+export function createHealthRouter(info) {
+    const router = Router();
+    router.get('/health', (_req, res) => {
+        res.json({
+            ok: true,
+            version: info.version,
+            workspacePath: info.workspacePath,
+            startedAt: info.startedAt,
+            pid: process.pid,
+        });
+    });
+    return router;
+}

package/server/dist/routes/lint.d.ts

@@ -0,0 +1,10 @@
+import { Router } from 'express';
+/**
+ * `POST /api/lint-fluid-js` — static import lint for a `.fluid.js` payload.
+ * Used by the MCP server before it writes a file so the agent learns to add
+ * imports on retry instead of failing at runtime with `ReferenceError`.
+ *
+ * Request body: `{ code: string }`
+ * Response:     `{ missing: MissingImport[], suggestion: string }`
+ */
+export declare function createLintRouter(): Router;

package/server/dist/routes/lint.js

@@ -0,0 +1,28 @@
+import { Router } from 'express';
+import { lintFluidJs } from "../lint-fluid-js.js";
+/**
+ * `POST /api/lint-fluid-js` — static import lint for a `.fluid.js` payload.
+ * Used by the MCP server before it writes a file so the agent learns to add
+ * imports on retry instead of failing at runtime with `ReferenceError`.
+ *
+ * Request body: `{ code: string }`
+ * Response:     `{ missing: MissingImport[], suggestion: string }`
+ */
+export function createLintRouter() {
+    const router = Router();
+    router.post('/lint-fluid-js', async (req, res) => {
+        const { code } = req.body ?? {};
+        if (typeof code !== 'string') {
+            res.status(400).json({ error: '`code` must be a string.' });
+            return;
+        }
+        try {
+            const result = await lintFluidJs(code);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message ?? String(err) });
+        }
+    });
+    return router;
+}

package/server/dist/routes/render.d.ts

@@ -0,0 +1,33 @@
+import { Router } from 'express';
+import type { CompileError } from '../ws-protocol.ts';
+export type RenderOutcome = {
+    state: 'rendered';
+    version: number;
+    absPath: string;
+    durationMs: number;
+} | {
+    state: 'compile-error';
+    version: number;
+    durationMs: number;
+    compileError: CompileError;
+} | {
+    state: 'superseded';
+    version: number;
+    durationMs: number;
+} | {
+    state: 'no-scene-manager';
+    version: number;
+    durationMs: number;
+};
+/**
+ * `POST /api/render` — synchronous render trigger used by the MCP server
+ * after it writes a `.fluid.js` file. The body carries the post-write
+ * contents so the server doesn't need to re-read disk and so dedup against
+ * `lastRendered` is exact. Returns the render outcome (rendered / compile-
+ * error / superseded / no-scene-manager) once the OCC pass settles.
+ *
+ * Whoever invokes this is responsible for the on-disk write — we only run
+ * the render. Pairing both in one HTTP round-trip is what lets MCP
+ * `write_file` return a synchronous { written, render } to the agent.
+ */
+export declare function createRenderRouter(runLiveRender: (fileName: string, code: string) => Promise<RenderOutcome>): Router;

package/server/dist/routes/render.js

@@ -0,0 +1,34 @@
+import { Router } from 'express';
+/**
+ * `POST /api/render` — synchronous render trigger used by the MCP server
+ * after it writes a `.fluid.js` file. The body carries the post-write
+ * contents so the server doesn't need to re-read disk and so dedup against
+ * `lastRendered` is exact. Returns the render outcome (rendered / compile-
+ * error / superseded / no-scene-manager) once the OCC pass settles.
+ *
+ * Whoever invokes this is responsible for the on-disk write — we only run
+ * the render. Pairing both in one HTTP round-trip is what lets MCP
+ * `write_file` return a synchronous { written, render } to the agent.
+ */
+export function createRenderRouter(runLiveRender) {
+    const router = Router();
+    router.post('/render', async (req, res) => {
+        const { filePath, code } = req.body ?? {};
+        if (typeof filePath !== 'string' || filePath.length === 0) {
+            res.status(400).json({ error: '`filePath` must be a non-empty string.' });
+            return;
+        }
+        if (typeof code !== 'string') {
+            res.status(400).json({ error: '`code` must be a string.' });
+            return;
+        }
+        try {
+            const outcome = await runLiveRender(filePath, code);
+            res.json(outcome);
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message ?? String(err) });
+        }
+    });
+    return router;
+}

package/server/dist/routes/scene.d.ts

@@ -0,0 +1,5 @@
+import { Router } from 'express';
+import type { FluidCadServer } from '../fluidcad-server.ts';
+import type { CameraStateMessage } from '../ws-protocol.ts';
+export type CameraStateGetter = () => CameraStateMessage | null;
+export declare function createSceneRouter(fluidCadServer: FluidCadServer, getCameraState?: CameraStateGetter): Router;

package/server/dist/routes/scene.js

@@ -0,0 +1,48 @@
+import { Router } from 'express';
+export function createSceneRouter(fluidCadServer, getCameraState = () => null) {
+    const router = Router();
+    router.get('/scene/summary', (_req, res) => {
+        try {
+            const summary = fluidCadServer.getSceneSummary();
+            if (!summary) {
+                res.status(404).json({ error: 'No scene available — the workspace has not rendered a file yet.' });
+                return;
+            }
+            res.json(summary);
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message ?? String(err) });
+        }
+    });
+    router.get('/scene/shapes', (_req, res) => {
+        try {
+            const shapes = fluidCadServer.getShapesList();
+            if (!shapes) {
+                res.status(404).json({ error: 'No scene available — the workspace has not rendered a file yet.' });
+                return;
+            }
+            res.json(shapes);
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message ?? String(err) });
+        }
+    });
+    router.get('/scene/compile-error', (_req, res) => {
+        try {
+            const compileError = fluidCadServer.getCompileError();
+            res.json({ compileError });
+        }
+        catch (err) {
+            res.status(500).json({ error: err?.message ?? String(err) });
+        }
+    });
+    router.get('/camera/state', (_req, res) => {
+        const state = getCameraState();
+        if (!state) {
+            res.status(404).json({ error: 'No camera state available yet — the UI has not connected, or no view change has been observed.' });
+            return;
+        }
+        res.json(state);
+    });
+    return router;
+}