forma-dsl-mcp 0.3.7 → 0.3.9

package/src/reference/reference/shapes-3d.md

@@ -11,7 +11,7 @@ Five leaf blocks producing solids. They take attributes and never contain other
 | [`torus`](#torus) | `radius`, `tube_radius` | always |
 
 Anything these cannot express is usually a 2D profile plus
-[`extrude`](conversions.md#extrude) or [`revolve`](conversions.md#revolve) — that is where
+[`extrude`](conversions.md#extrude) or [`revolve`](conversions.md#revolve) - that is where
 the real modelling happens.
 
 ---
@@ -35,7 +35,7 @@ box { size = [40, 20, 10]  center = true }
 #### Caveats
 
 - A single number is accepted as shorthand for all three, so `size = 10` is a 10 mm cube.
-- There is no rounded box. Round a 2D profile and extrude it —
+- There is no rounded box. Round a 2D profile and extrude it -
   see [Usage](#rounded-boxes).
 
 ---
@@ -52,7 +52,7 @@ sphere { diameter = 24  segments = 64 }
 | Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
 | `radius` | number | `1` | |
-| `diameter` | number | — | An alternative spelling of the same thing |
+| `diameter` | number | - | An alternative spelling of the same thing |
 | `segments` | integer | `0` | Segments around the equator; `0` lets the kernel choose |
 
 #### Caveats
@@ -77,17 +77,17 @@ cylinder { bottom_radius = 12  top_radius = 8  height = 15 }
 | Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
 | `height` | number | **required** | Along Z |
-| `radius` | number | — | Both ends alike |
-| `diameter` | number | — | An alternative spelling of `radius` |
-| `bottom_radius` | number | — | The end at Z = 0 |
-| `top_radius` | number | — | The end at Z = `height` |
+| `radius` | number | - | Both ends alike |
+| `diameter` | number | - | An alternative spelling of `radius` |
+| `bottom_radius` | number | - | The end at Z = 0 |
+| `top_radius` | number | - | The end at Z = `height` |
 | `segments` | integer | `0` | Segments around; `0` lets the kernel choose |
 | `center` | bool | `false` | `true` centres it on Z = 0; otherwise it stands on the XY plane |
 
 #### Caveats
 
 - Give **either** `radius`/`diameter`, **or both** `bottom_radius` and `top_radius`. Anything
-  else is `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` —
+  else is `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` -
   one radius on its own is ambiguous, and there is no default.
 - Unlike every other shape, `radius` has no usable default here: the check runs before the
   fallback would apply.
@@ -110,7 +110,7 @@ cone { radius = 10  top_radius = 4  height = 20 }
 | --- | --- | --- | --- |
 | `height` | number | **required** | Along Z |
 | `radius` | number | `1` | The base, at Z = 0 |
-| `diameter` | number | — | An alternative spelling of `radius` |
+| `diameter` | number | - | An alternative spelling of `radius` |
 | `top_radius` | number | `0` | `0` gives a point |
 | `segments` | integer | `0` | Segments around |
 | `center` | bool | `false` | As for [`cylinder`](#cylinder) |
@@ -118,7 +118,7 @@ cone { radius = 10  top_radius = 4  height = 20 }
 #### Caveats
 
 - `cone` and `cylinder` build the same kind of solid; they differ only in which attributes
-  are required and what `top_radius` defaults to. Use whichever reads better — `cone` when
+  are required and what `top_radius` defaults to. Use whichever reads better - `cone` when
   the top is a point, `cylinder` when both ends matter.
 
 ---
@@ -158,7 +158,7 @@ torus { radius = 20  tube_radius = 4  angle = 180 }
 
 ### Rounded boxes
 
-There is no rounded-box primitive. Round the 2D profile and extrude it — which also gives
+There is no rounded-box primitive. Round the 2D profile and extrude it - which also gives
 control over whether the vertical edges or the horizontal ones are rounded:
 
 ```hcl
@@ -270,8 +270,8 @@ box { size = [40, 20, 10] }   // ✓
 ### My cylinder is not where I expect
 
 By default a cylinder stands **on** the XY plane, with its base at Z = 0. `center = true`
-puts its middle there instead. The same is true of `box`, whose minimum corner — not its
-centre — sits at the origin by default.
+puts its middle there instead. The same is true of `box`, whose minimum corner - not its
+centre - sits at the origin by default.
 
 ### Two solids that touch exactly render with artefacts
 

package/src/reference/reference/transforms.md

@@ -36,7 +36,7 @@ translate { offset = [10, 0]     rect { size = [4, 4] } }      // 2D
 
 #### Caveats
 
-- `offset` must have as many components as the child has dimensions — 2 for a cross-section,
+- `offset` must have as many components as the child has dimensions - 2 for a cross-section,
   3 for a solid. A mismatch is `translate: "offset" must be a number or an array of 3
   numbers`.
 - A single number broadcasts to every axis, which is rarely what you want here but is
@@ -54,14 +54,14 @@ rotate { angles = [0, 90, 45]  box { size = [20, 4, 4] } }      // 3D, all three
 rotate { angle = 30  rect { size = [20, 4] } }                  // 2D
 ```
 
-#### Attributes — 3D children
+#### Attributes - 3D children
 
 | Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
-| `angles` | 3-vector | — | Degrees about X, Y and Z at once |
+| `angles` | 3-vector | - | Degrees about X, Y and Z at once |
 | `x`, `y`, `z` | number | `0` | Degrees about that axis, named one at a time |
 
-#### Attributes — 2D children
+#### Attributes - 2D children
 
 | Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -70,7 +70,7 @@ rotate { angle = 30  rect { size = [20, 4] } }                  // 2D
 #### Caveats
 
 - **Rotation is about the origin, not about the geometry.** To spin something in place, put
-  it at the origin, rotate, then translate — or build it centred in the first place.
+  it at the origin, rotate, then translate - or build it centred in the first place.
 - In 3D the axes are applied **X, then Y, then Z**, matching OpenSCAD, so a model ported from
   there lands in the same orientation. Composing rotations in a different order requires
   separate `rotate` blocks.
@@ -100,7 +100,7 @@ scale { factor = [1, 1, 0.5]  sphere { radius = 5 } }    // flattened
 - A negative factor mirrors as well as scales, and flips the winding. Prefer
   [`mirror`](#mirror) when reflection is what you mean.
 - A factor of `0` collapses the geometry to nothing.
-- Non-uniform scaling of a curved surface changes its radii — a scaled sphere is an
+- Non-uniform scaling of a curved surface changes its radii - a scaled sphere is an
   ellipsoid, which is the cheapest way to get one.
 
 ---
@@ -167,7 +167,7 @@ translate {          // …then moved 50 along X
 }
 ```
 
-Swapping the two gives a different result — rotating a translated box sweeps it around the
+Swapping the two gives a different result - rotating a translated box sweeps it around the
 origin on an arc of radius 50.
 
 ### Radial patterns
@@ -183,7 +183,7 @@ for i in range(0, 8) {
 }
 ```
 
-Because identity is content identity, this costs **one** cylinder and eight transforms — the
+Because identity is content identity, this costs **one** cylinder and eight transforms - the
 cylinder node is the same node every time round the loop.
 
 ### Mirrored pairs
@@ -212,7 +212,7 @@ scale { factor = [1, 0.6, 1]  sphere { radius = 20  segments = 64 } }
 ### `translate: "offset" must be a number or an array of 3 numbers`
 
 The offset has the wrong number of components for its child. 2D children want two, 3D
-children want three — and a 2D shape stays 2D until it is extruded:
+children want three - and a 2D shape stays 2D until it is extruded:
 
 ```hcl
 translate { offset = [1, 2, 3]  rect { size = [4, 4] } }   // ✗ rect is 2D
@@ -228,7 +228,7 @@ rotate { angle = 45  box { size = [1, 1, 1] } }    // ✗
 rotate { z = 45      box { size = [1, 1, 1] } }    // ✓
 ```
 
-The reverse — `z` on a 2D child — fails the same way.
+The reverse - `z` on a 2D child - fails the same way.
 
 ### `"translate" needs at least one shape inside it`
 

package/src/reference.js

@@ -3,8 +3,8 @@
  *
  * The manual is the language's own documentation, copied into the package by
  * `scripts/sync-reference.mjs` rather than paraphrased, so an answer from here is the same
- * answer a person reading the published docs would get. Search is deliberately simple —
- * substring matching over headings and body text, ranked — because the corpus is 28 pages
+ * answer a person reading the published docs would get. Search is deliberately simple -
+ * substring matching over headings and body text, ranked - because the corpus is 29 pages
  * and anything cleverer would be a dependency and a source of surprise.
  */
 import { readFile, readdir } from 'node:fs/promises';
@@ -47,6 +47,7 @@ export const PAGES = [
   { path: 'reference/part.md', title: 'part', about: 'Coloured pieces of the rendered scene' },
   { path: 'reference/functions.md', title: 'Functions', about: 'Every builtin function and constant' },
   { path: 'errors.md', title: 'Errors', about: 'Every error message, what raises it, and what to change' },
+  { path: 'cli.md', title: 'Command line', about: 'The forma command: render to STL, list params and models, exit codes' },
   { path: 'api/render.md', title: 'render', about: 'JavaScript API: compile a document and evaluate a model' },
   { path: 'api/describe-parameters.md', title: 'describeParameters', about: 'JavaScript API: read a document’s params without rendering' },
   { path: 'api/evaluation-context.md', title: 'EvaluationContext', about: 'JavaScript API: the digest cache and WASM ownership' },
@@ -95,7 +96,7 @@ export async function readPage(path) {
   const page = BY_PATH.get(normalised);
   if (!page) {
     throw new Error(
-      `no reference page "${path}" — the pages are ${PAGES.map((each) => each.path).join(', ')}`,
+      `no reference page "${path}" - the pages are ${PAGES.map((each) => each.path).join(', ')}`,
     );
   }
   return { path: page.path, title: page.title, markdown: await readFile(join(ROOT, page.path), 'utf8') };

package/src/roots.js

@@ -3,7 +3,7 @@
  *
  * The server does not get to choose the patch of disk it writes to. The MCP `roots`
  * capability is the client's declaration of which directories it is handing over, and asking
- * for it — rather than reading an environment variable the client cannot see — is the whole
+ * for it - rather than reading an environment variable the client cannot see - is the whole
  * of this module. A client that declares nothing gets the directory it launched the server
  * in, which is the one location it did choose.
  */
@@ -17,7 +17,7 @@ import { Workspace } from './workspace.js';
  * The part of the low-level server this module needs.
  *
  * Named structurally rather than as the SDK's `Server`, which is deprecated in favour of
- * `McpServer` — but `McpServer` does not carry `listRoots` or `setNotificationHandler`, so the
+ * `McpServer` - but `McpServer` does not carry `listRoots` or `setNotificationHandler`, so the
  * low-level object is genuinely the right one to take. Describing the three members used is
  * both the honest contract and what lets a test hand this a stub.
  *

package/src/server.js

@@ -43,7 +43,7 @@ export const VERSION = createRequire(import.meta.url)('../package.json').version
 const INSTRUCTIONS = `This server knows forma, a declarative DSL for 3D solids, builds it with
 the real geometry kernel, and writes the documents it builds.
 
-Start with \`forma_guide\` — it is the language in one page. Use \`forma_blocks\` for the
+Start with \`forma_guide\` - it is the language in one page. Use \`forma_blocks\` for the
 attributes of the blocks you are about to write, \`forma_examples\` for a working document of
 a similar shape, and \`forma_reference\` when you need the manual.
 
@@ -61,7 +61,7 @@ first of them. Every write reports the directory it landed in.`;
  * Builds the server, with every tool and resource registered.
  *
  * The workspace is optional, and left out is the normal case: the server then takes its
- * directories from whatever the connected client declares as its roots, which is the point —
+ * directories from whatever the connected client declares as its roots, which is the point -
  * the client knows where the user's files belong and the server does not.
  *
  * @param {Workspace} [workspace] The patch of filesystem the tools may touch. Omitted, the

package/src/tools.js

@@ -23,7 +23,7 @@ import { checkDocument, exportStl } from './document.js';
  * All four hints are stated rather than just `readOnlyHint`, because the omitted ones are not
  * absent: the specification gives `destructiveHint` a default of **true** and `idempotentHint`
  * a default of **false**. A tool declaring neither is therefore advertising itself as
- * destructive and unrepeatable — which, for a call that hands back a page of the manual, is
+ * destructive and unrepeatable - which, for a call that hands back a page of the manual, is
  * simply untrue, and a cautious client is entitled to act on it.
  *
  * `openWorldHint` is false because every answer is bundled with the package. Nothing here
@@ -52,8 +52,8 @@ const say = (text, isError = false) => ({
  * Runs a handler, turning anything it throws into a result the caller can read.
  *
  * A thrown error becomes a protocol-level failure, which most clients surface as "the tool
- * broke" rather than as something the model can correct. A refusal it can read — a path
- * outside the roots, a part that does not exist — belongs in the result instead.
+ * broke" rather than as something the model can correct. A refusal it can read - a path
+ * outside the roots, a part that does not exist - belongs in the result instead.
  *
  * @param {() => Promise<object>} handler What to run.
  * @returns {Promise<object>} Its result, or the failure as text.
@@ -115,9 +115,9 @@ function parameterLines(parameters) {
       return [
         `\`${parameter.name}\``,
         parameter.type,
-        parameter.default === undefined ? '—' : JSON.stringify(parameter.default),
+        parameter.default === undefined ? '-' : JSON.stringify(parameter.default),
         parameter.required ? 'yes' : 'no',
-        bounded ? `${parameter.min ?? '−∞'} … ${parameter.max ?? '∞'}` : '—',
+        bounded ? `${parameter.min ?? '−∞'} … ${parameter.max ?? '∞'}` : '-',
       ];
     }),
   ), ''];
@@ -184,7 +184,7 @@ function sceneLines(scene, stats) {
 function takesOf(entry) {
   if (entry.leaf) return 'nothing';
   if (entry.takes === 'same') return '2D or 3D';
-  return entry.takes ? `${entry.takes}D` : '—';
+  return entry.takes ? `${entry.takes}D` : '-';
 }
 
 /**
@@ -224,7 +224,7 @@ async function documentFrom(workspace, { source, path }) {
   if (source && path) throw new Error('give either "source" or "path", not both');
   if (source) return source;
   if (path) return workspace.read(path);
-  throw new Error('give either "source" — the document itself — or "path" to one already written');
+  throw new Error('give either "source" - the document itself - or "path" to one already written');
 }
 
 /**
@@ -304,7 +304,7 @@ function registerBlocks(server) {
         ['Block', 'Dim', 'Takes', 'Summary'],
         all.filter((entry) => entry.group === name).map((entry) => [
           `\`${entry.name}\``,
-          entry.dim ? `${entry.dim}D` : '—',
+          entry.dim ? `${entry.dim}D` : '-',
           takesOf(entry),
           entry.summary,
         ]),
@@ -319,7 +319,7 @@ function registerBlocks(server) {
  * Every function an expression may call, and the two named constants.
  *
  * There are no user-defined functions in forma, so this answer is complete rather than a
- * sample — which is worth saying, because it is what stops a caller inventing one.
+ * sample - which is worth saying, because it is what stops a caller inventing one.
  *
  * @param {McpServer} server The server.
  * @returns {void}
@@ -363,7 +363,7 @@ function registerReference(server) {
     description:
       'The language\'s full reference manual, bundled with this server. Pass `query` to '
       + 'search it, or `page` to read one page whole. Reach for this when forma_blocks is not '
-      + 'enough — the manual has the worked examples, the caveats and the troubleshooting for '
+      + 'enough - the manual has the worked examples, the caveats and the troubleshooting for '
       + 'every error message the language raises. Call with no arguments to list the pages.',
     inputSchema: {
       query: z.string().optional().describe('Words to search for, e.g. "revolve profile axis".'),
@@ -383,7 +383,7 @@ function registerReference(server) {
         `# ${hits.length} page${plural} matching "${query}"`,
         '',
         ...hits.map((hit) => [
-          `## ${hit.title} — \`${hit.path}\``,
+          `## ${hit.title} - \`${hit.path}\``,
           hit.heading ? `_under "${hit.heading}"_` : '',
           '',
           '> ' + hit.snippet.replaceAll('\n', '\n> '),
@@ -468,7 +468,7 @@ function registerWrite(server, workspace) {
       + 'triangle count and genus, or the error with the line, the column and an excerpt with '
       + 'a caret on it. This is how you find out whether what you wrote is the size you meant, '
       + 'is watertight, and is not silently empty. A document that does not render is refused '
-      + 'and nothing is written — pass `force: true` to write it anyway. Refuses to replace an '
+      + 'and nothing is written - pass `force: true` to write it anyway. Refuses to replace an '
       + 'existing file unless `overwrite` is set.',
     inputSchema: {
       path: z.string()
@@ -494,7 +494,7 @@ function registerWrite(server, workspace) {
 
     const written = await workspace.write(path, source, { overwrite, extension: '.forma' });
     return say([
-      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes`
+      `Wrote \`${written.relative}\` under \`${written.root}\` - ${written.bytes} bytes`
       + `${written.replaced ? ', replacing what was there' : ''}.`,
       '',
       formatReport(report),
@@ -546,7 +546,7 @@ function registerExportStl(server, workspace) {
   server.registerTool('forma_export_stl', {
     title: 'Render and write a binary STL',
     description:
-      'Renders a document and writes one part — or every part unioned — as a binary STL. '
+      'Renders a document and writes one part - or every part unioned - as a binary STL. '
       + 'Lengths are unitless in forma and STL has no unit either; every consumer treats them '
       + 'as millimetres.',
     inputSchema: {
@@ -575,7 +575,7 @@ function registerExportStl(server, workspace) {
       extension: '.stl',
     });
     return say(
-      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes, `
+      `Wrote \`${written.relative}\` under \`${written.root}\` - ${written.bytes} bytes, `
       + `${result.triangles} triangles, from model \`${result.model}\`, part \`${result.part}\`.`,
     );
   }));

package/src/workspace.js

@@ -3,7 +3,7 @@
  *
  * An MCP server writes files on behalf of a model, so the set of paths it will accept is a
  * security boundary rather than a convenience. Which directories make up that set is the
- * client's decision — it declares them as MCP roots, and {@link Workspace} only asks. What
+ * client's decision - it declares them as MCP roots, and {@link Workspace} only asks. What
  * the workspace enforces is that everything goes through `resolve`, which refuses anything
  * landing outside all of them, including by way of `..`, an absolute path, or a symlink
  * pointing out of the tree.
@@ -84,7 +84,7 @@ export class Workspace {
    *
    * A root is resolved once and remembered, so a root that is itself a link still compares
    * equal to the paths resolved beneath it. Roots that do not exist are dropped rather than
-   * fatal — a client may well declare a directory this server has no business in — and only
+   * fatal - a client may well declare a directory this server has no business in - and only
    * an empty result is an error.
    *
    * @returns {Promise<Root[]>} The roots, in the order the client gave them.
@@ -124,7 +124,7 @@ export class Workspace {
     if (!roots.length) {
       throw new WorkspaceError(
         refused.length
-          ? `no usable workspace root — ${refused.join('; ')}`
+          ? `no usable workspace root - ${refused.join('; ')}`
           : 'the client has declared no workspace root, so there is nowhere to read or write; '
             + 'declare one with the MCP roots capability',
       );
@@ -185,7 +185,7 @@ export class Workspace {
     // the caller gave is used to choose segments and never to name a file. Each segment has
     // to match SAFE_SEGMENT, and what comes out is assembled onto a directory the client
     // declared. Every line below, and every caller, works with that value rather than the one
-    // that came in — so the walk beneath cannot be steered by a name this never approved.
+    // that came in - so the walk beneath cannot be steered by a name this never approved.
     const base = this.#baseOf(root, lexical);
     const segments = relative(base, lexical).split(sep).filter(Boolean);
     if (!segments.every((segment) => SAFE_SEGMENT.test(segment))) {
@@ -193,7 +193,7 @@ export class Workspace {
     }
     const absolute = segments.reduce((at, segment) => join(at, segment), base);
 
-    // The file itself may not exist yet — a write is the common case — so the deepest
+    // The file itself may not exist yet - a write is the common case - so the deepest
     // ancestor that does exist is what gets its links followed. This is the one check that
     // cannot be made without the filesystem: whether a directory inside a root is a link out
     // of it is not answerable from the path alone.
@@ -208,7 +208,7 @@ export class Workspace {
   }
 
   /**
-   * Which spelling of a root a path sits under — the one the client gave, or the one symlinks
+   * Which spelling of a root a path sits under - the one the client gave, or the one symlinks
    * resolve it to.
    *
    * @param {Root} root The root holding it.
@@ -294,7 +294,7 @@ export class Workspace {
 
     const replaced = existsSync(absolute);
     if (replaced && !overwrite) {
-      throw new WorkspaceError(`"${path}" already exists — pass overwrite: true to replace it`);
+      throw new WorkspaceError(`"${path}" already exists - pass overwrite: true to replace it`);
     }
 
     await mkdir(dirname(absolute), { recursive: true });